Manage shipping zones

Important

This integration guide supports physical goods. The physical goods product category is in Early Availability status. Features in Early Availability status are only available in production to a limited number of customers based on fit with specific use cases. For more information about Early Availability status, see Product lifecycle phases. If you would like to use the product capabilities described here during the Early Availability phase, contact your AppDirect technical representative.

A zone is a group of regions or countries that have the same shipping rates and the same default fulfillment service.

Marketplace Managers can currently create and edit zones in the user interface, at Manage > Marketplace > Settings > Settings | Shipping (see Configure shipping). However, because they cannot associate a specific fulfillment service to a zone in the UI, they must use APIs to do that.

A Marketplace Manager, or any other user with the ROLE_CHANNEL_ADMIN scope, can use the following zone APIs to create, read, update and list zones. To manage a zone using the API, you will need to get credentials from whoever manages the connector.

note

Marketplace Managers can optionally request that AppDirect manage zones on their behalf.

Create zones

Use the following request to create a zone.

POST https://{marketplaceUrl}/api/platformAdministration/v1/shippingConfigurations/zone

Required Payload:

Note the following regarding the payload values:

• Country codes must follow ISO standards
• The base URL is the shipping connector URL (varies depending on where the connector is hosted).
• You can obtain the shared secret from whoever manages the connector that you are using. The Physical Fulfillment Manager (PFM) uses the shared secret to encrypt data that is sent between the PFM and the shipping connector. See Shipment authentication for a description of shared secrets used for shipping.

{
  "name": "Europe",
  "countries": [
    {
      "shortCode": "FR",
      "includedRegions": [
        "FR+NOR",
        "FR+BFC",
        "FR+BRE",
        "FR+CVL",
        "FR+GP",
        "FR+NC"
      ]
    },
    {
      "shortCode": "GA",
      "includedRegions": [
        "GA+7",
        "GA+8",
        "GA+9",
        "GA+3",
        "GA+4"
      ]
    }
  ],
  "defaultConnector": "manual",
  "connectorConfigurations": {
    "custom": {
      "baseUrl": "http://some-url.com/endpoint",
      "sharedSecret": "34fdcvg334vfgdolgophwrtomcb90nflqoglasz24cvml"
    }
  }
}

Read zones

Use the following request to read a zone. You have to retrieve the UUID with the List all zones request so that you can specify it here.

GET https://{marketplaceUrl}/api/platformAdministration/v1/shippingConfigurations/zones/{uuid}

Possible response:

{
  "uuid": "e16b6ac6-c8ff-11e9-a32f-2a2ae2dbcce4",
  "name": "Europe",
  "countries": [
    {
      "shortCode": "FR",
      "includedRegions": [
        "FR+NOR",
        "FR+BFC",
        "FR+BRE",
        "FR+CVL",
        "FR+GP",
        "FR+NC"
      ]
    },
    {
      "shortCode": "GA",
      "includedRegions": [
        "GA+7",
        "GA+8",
        "GA+9",
        "GA+3",
        "GA+4"
      ]
    }
  ],
  "defaultConnector": "manual",
  "connectorConfigurations": { }
}

Update zones

Use the following request to update a zone (you can update any field).

PUT https://{marketplace-domain}/api/platformAdministration/v1/shippingConfigurations/zones/{uuid}

Possible payload

{
  "name": "Europe",
  "countries": [
    {
      "shortCode": "FR",
      "includedRegions": [
        "FR+NOR",
        "FR+BFC",
        "FR+BRE",
        "FR+CVL",
        "FR+GP",
        "FR+NC"
      ]
    },
    {
      "shortCode": "GA",
      "includedRegions": [
        "GA+7",
        "GA+8",
        "GA+9",
        "GA+3",
        "GA+4"
      ]
    }
  ],
  "defaultConnector": "manual",
  "connectorConfigurations": {
    "custom": {
      "baseUrl": "http://some-url.com/endpoint",
      "sharedSecret": "34fdcvg334vfgdolgophwrtomcb90nflqoglasz24cvml"
    }
  }
}

List all zones

This API endpoint returns an array of all configured zones. Use this request to retrieve zone UUIDs, which are required for the "Read zones" and "Update zones" requests.

GET https://{marketplaceUrl}/api/platformAdministration/v1/shippingConfigurations/zones