Frequently Asked Questions

Amazon Shipping API FAQs to address some of the pre and post-integration related queries

If your integration query isn't answered in the FAQs, please create a support ticket here: Developer Central

Integration Related FAQ

Recommended tool for integration?

  • We recommend Postman for testing APIs since it has the support to make the calls with OAuth 2.0. Sample Postman Collections and Postman Environments files are available in JSON format - Postman Collection and Environment.

Is channelDetails required for both Amazon and off-Amazon orders?

  • Yes, channelDetails is required for both Amazon and off-Amazon orders since it contains channelType which is a mandatory field. channelType value should be set as “AMAZON” for all on-Amazon orders and as “EXTERNAL” for off-amazon orders. Additionally, Amazon Order ID field value is mandatory for all On-Amazon orders. For additional details please refer "Get Rates for a Shipment".

Is itemValue field mandatory?

  • While generating Shipping labels, passing a value in the itemValue field is mandatory. Off-Amazon shippers should send a price to generate labels and if no value is available, then it is recommended to default the value to $1 for generating the label.

What if I provide no values for returnTo Address or shipDate while calling the getRates Operation/API?

  • shipFrom value will be considered for returnTo and currentDate and time will be considered for shipDate.

What is the recommended label format for the shippers?

  • We recommend that the shippers use .zpl format (supported by the Amazon shipping APIs) since it has a lower latency. The other supported label formats are “PDF” and “PNG”. In terms of latency, ZPL is the fastest followed by PDF and PNG. Refer the API Swagger model for the complete list.
    Please note that you will need a Zebra printer to print ZPL labels. Please validate the dpi requirement of the Zebra printer.

What are some of the key things to consider during integration?

  • Provide the details related to serviceID for both On-Amazon & Off-Amazon orders. ServiceID can be found in the GetRates API response for each of the returned rates.
  • shipDate parameter is OPTIONAL, don't pass it if you are unsure of how to use it. shipDate should ONLY be used for future shipments.
  • If you are a multi-warehouse shipper and have more than 1 warehouse address registered with Amazon, then please make sure that the “shipFrom” address should have the address of the registered warehouse from where the pickups are expected to take place.

Can Amazon Shipping API be integrated through EDI?

  • No, Amazon Shipping API is built on the Selling Partner API (SP-API) and the registration process and integration is described in the Selling Partner Developer Guide.

How do I get an access token for the API requests?

  • A Login with Amazon (LWA) access token authorizes your application to take certain actions on behalf of a selling partner. An access token expires one hour after it is issued, and must be included with every request to the Selling Partner API. (For more information, see the Connecting to the Selling Partner API within the Selling Partner Developer Guide.)

When does the Access Token and Refresh Token expire?

  • Access Token: It expires 1 hour after it is generated. New Access Token should be generated once it is expired.
  • Refresh Token: It doesn't expire. Refresh Token should be exchanged to get a new Access Token.

What are the Sandbox and Production hosts for Amazon Shipping v2 API?

EU (UK, FR, IT, ES) Marketplace:

US Marketplace:

Sandbox and Production endpoints for Amazon Shipping v2 API?

EU (UK, FR, IT, ES) Marketplace:

RegionAPI NameCall TypeAmazon Shipping Sandbox EndpointsAmazon Shipping Production Endpoints
EUGetRatesV2POSThttps://sandbox.sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/rateshttps://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/rates
EUPurchaseShipmentPOSThttps://sandbox.sellingpartnerapi-eu.amazon.com/shipping/v2/shipmentshttps://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments
EUOneClickShipment (Smart Purchase)POSThttps://sandbox.sellingpartnerapi-eu.amazon.com/shipping/v2/oneClickShipmenthttps://sellingpartnerapi-eu.amazon.com/shipping/v2/oneClickShipment
EUGetTrackingV2GEThttps://sandbox.sellingpartnerapi-eu.amazon.com/shipping/v2/tracking?trackingId={trackingId}&carrierId={carrierId}https://sellingpartnerapi-eu.amazon.com/shipping/v2/tracking?trackingId={trackingId}&carrierId={carrierId}
EUGetShipmentDocumentsGEThttps://sandbox.sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/{shipmentId}/documents?packageClientReferenceId={packageReferenceId}https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/{shipmentId}/documents?packageClientReferenceId={packageReferenceId}
EUCancelShipmentV2PUThttps://sandbox.sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/{shipmentId}/cancelhttps://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/{shipmentId}/cancel
EUgetAccessPointsGEThttps://sandbox.sellingpartnerapi-eu.amazon.com/shipping/v2/accessPointshttps://sellingpartnerapi-eu.amazon.com/shipping/v2/accessPoints
EUgetAdditionalInputsGEThttps://sandbox.sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/additionalInputs/schemahttps://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/additionalInputs/schema

US Marketplace:

RegionAPI NameCall TypeAmazon Shipping Sandbox EndpointsAmazon Shipping Production Endpoints
NAGetRatesV2POSThttps://sandbox.sellingpartnerapi-na.amazon.com/shipping/v2/shipments/rateshttps://sellingpartnerapi-na.amazon.com/shipping/v2/shipments/rates
NAPurchaseShipmentPOSThttps://sandbox.sellingpartnerapi-na.amazon.com/shipping/v2/shipmentshttps://sellingpartnerapi-na.amazon.com/shipping/v2/shipments
NAOneClickShipment (Smart Purchase)POSThttps://sandbox.sellingpartnerapi-na.amazon.com/shipping/v2/oneClickShipmenthttps://sellingpartnerapi-na.amazon.com/shipping/v2/oneClickShipment
NAGetTrackingV2GEThttps://sandbox.sellingpartnerapi-na.amazon.com/shipping/v2/tracking?trackingId={trackingId}&carrierId={carrierId}https://sellingpartnerapi-na.amazon.com/shipping/v2/tracking?trackingId={trackingId}&carrierId={carrierId}
NAGetShipmentDocumentsGEThttps://sandbox.sellingpartnerapi-na.amazon.com/shipping/v2/shipments/{shipmentId}/documents?packageClientReferenceId={packageReferenceId}https://sellingpartnerapi-na.amazon.com/shipping/v2/shipments/{shipmentId}/documents?packageClientReferenceId={packageReferenceId}
NACancelShipmentV2PUThttps://sandbox.sellingpartnerapi-na.amazon.com/shipping/v2/shipments/{shipmentId}/cancelhttps://sellingpartnerapi-na.amazon.com/shipping/v2/shipments/{shipmentId}/cancel
NAgetAdditionalInputsGEThttps://sandbox.sellingpartnerapi-na.amazon.com/shipping/v2/shipments/additionalInputs/schemahttps://sellingpartnerapi-na.amazon.com/shipping/v2/shipments/additionalInputs/schema

I am getting "Access to requested resource is denied." when making an API call to "GetTrackingV2" OR "GetShipmentDocuments"?

  • "GetTrackingV2" OR "GetShipmentDocuments" are GET operations. The code: Unauthorized is displayed if POST operation is used for these APIs.

Can I send multiple "packages" elements in the getRates request? So for example if a customer wanted to ship multiple parcels with different weights/dimensions?

  • No, Amazon Shipping currently supports a single getRates request per package. If there are more than 1 packages being shipped to the same address, please make the getRates request for each package and subsequent purchaseShipment calls to generate the label.
  • In future, we plan to expand the getRates capabilities to handle multiple packages.

What are the label formats available for Amazon Shipping labels via the API integration?

Supported label formats for ON Amazon request - PDF, PNG, ZPL (203 and 300 DPI)

Supported label formats for OFF Amazon request - PDF, PNG, ZPL (203 and 300 DPI)

Can I send a hard coded dimensions OR weight in getRates request?

  • No, Amazon Shipping API calculates the rates/ delivery options based on accurate dimensions and weight. Please ensure to send accurate dimensions and weight in the getRates request.

Is there a list of FAQs I can refer to when I have questions regarding how to create the developer profile?

  • Yes. Please refer to this link Developer Profile FAQ. If you have still any questions, please reach out to your account team for assistance.

Additional Resources - See these additional resources for more information

How can I generate the Refresh Token after creating the App in Developer Central ?

Step by step detail is captured below for Self authorization.

Step-1: For the application that you want to authorize, click the arrow next to the Edit App button, and then click Authorize.

1045

Step-2: Please click on "sign into that account", this will redirect to login page.

1043

Step-3: The Authorize application page appears. Please use the user account having admin role, or else the Authorize button will not appear.


528

Step-4: Please click on "Authorize app" to generate the refresh token.
Note. If your selling account is merged with accounts from other regions, you will receive a separate refresh token for each region. Your application is now authorized to access your selling account(s).

1732

Post Integration FAQ

I am seeing the error message "Access to requested resource is denied"

  • Access denied error messages are returned due to Unauthorized errors or MissingAuthenticationToken errors.

Unauthorized

An Unauthorized with status code 403 error is returned for the following scenarios:

  1. Shipper Account: Check that shipper account is in active status, valid rate card should be enabled for the shipper account. For additional information, please check with your Launch manager.
  2. API access: Check the API operation you are making a request to and verify that your application has access to that API. Amazon Shipping access is available via the following roles: 1) Direct-to-Consumer Shipping and 2) Amazon Logistics. To verify role permissions, in Seller Central, navigate to Partner Network > Develop Apps. Choose Edit App and review the roles selected for your application. In Developer Central, navigate to Developer Central page. Choose Edit App and review the roles selected for your application.
  3. Missing SP-API Role: If you are missing the role you need for the API access, check your Developer Profile to verify you requested access to that role. If you are missing access to a restricted role, you may need to re-submit your Developer Profile for access to that restricted role. Once the role is added, re-authorize your application (that is, generate a new LWA Refresh token to make valid API calls).

What should be the input for the requestedDocumentSpecification object in the purchaseShipment request call?

  • As part of the getRates response, each rate will have the supported formats mentioned in the supportedDocumentSpecifications object and it is base 64 encoded. To avoid errors, the same dimensions & format for the selected rate should be used in the PurchaseShipment call
  • requestedDocumentSpecification is a mandatory field while making the PurchaseShipment API call and it is expected that it should match exactly with one of the specifications that was returned in the GetRates response for that rate.

Which carrierID to use while calling Tracking API?

  • It is advised to use the same carrierID that was returned in the getRates API response. Integrators might have to consider storing this information and reuse it while calling TrackingAPIs.

Which x-amzn-shipping-business-id to use as request header while calling Shipping V2 API?

  • Amazon shipping business to assume for this request from the below enumeration

Type : enum

ValueDescription
AmazonShipping_USThe United States Amazon shipping business.
AmazonShipping_INThe India Amazon shipping business.
AmazonShipping_UKThe United Kingdom Amazon shipping business.
AmazonShipping_ITThe Italy Amazon shipping business.
AmazonShipping_ESThe Spain Amazon shipping business.
AmazonShipping_FRThe France Amazon shipping business.

What are the Amazon Shipping Service Ids in Production environments ?

Production Environment

  • Marketplace UK (ON Amazon Labels) - United Kingdom
Service IdService NameCarrier IDCarrier Name
prime-premium-uk-mfnAmazon Shipping One-Day TrackedAMZN_UKAmazon Shipping
std-uk-mfnAmazon Shipping Two-Day TrackedAMZN_UKAmazon Shipping
econ-uk-mfnAmazon Shipping Standard TrackedAMZN_UKAmazon Shipping
  • Marketplace UK (OFF Amazon Labels/ Own Website) - United Kingdom
Service IdService NameCarrier IDCarrier Name
SWA-UK-PREMAmazon Shipping One DayAMZN_UKAmazon Shipping
SWA-UK-2DAmazon Shipping Two DayAMZN_UKAmazon Shipping
  • Marketplace IT (ON Amazon Labels) - Italy
Service IdService NameCarrier IDCarrier Name
prime-premium-it-mfnSpedizione nazionale expressaAMZN_ITAmazon Shipping
  • Marketplace IT (OFF Amazon Labels/ Own Website) - Italy
Service IdService NameCarrier IDCarrier Name
SWA-IT-PRIME-PREMSpedizione nazionale expressAMZN_ITAmazon Shipping
  • Marketplace FR (ON Amazon Labels) - France
Service IdService NameCarrier IDCarrier Name
prime-premium-fr-mfnAmazon Shipping One-Day TrackedAMZN_FRAmazon Shipping
  • Marketplace FR (OFF Amazon Labels) - France
Service IdService NameCarrier IDCarrier Name
SWA-FR-PRIME-PREMAmazon Shipping One DayAMZN_FRAmazon Shipping
  • Marketplace ES (ON Amazon Labels) - Spain
Service IdService NameCarrier IDCarrier Name
prime-premium-es-mfnAmazon Shipping One-Day TrackedAMZN_ESAmazon Shipping
  • Marketplace ES (OFF Amazon Labels) - Spain
Service IdService NameCarrier IDCarrier Name
SWA-ES-PRIME-PREMAmazon Shipping expressAMZN_ESAmazon Shipping
  • Marketplace IN (OFF Amazon Labels/ Own Website)
Service IdService NameCarrier IDCarrier Name
SWA-IN-OAAmazon Shipping StandardATSAmazon Shipping
  • Marketplace US (ON Amazon Labels)
Service IdService NameCarrier IDCarrier Name
std-us-swa-mfnAmazon Shipping GroundAMZN_USAmazon Shipping
  • Marketplace US (OFF Amazon Labels/ Own Website)
Service IdService NameCarrier IDCarrier Name
std-us-swa-mfnAmazon Shipping GroundAMZN_USAmazon Shipping

Our Sandbox environment is undergoing updates, Service Ids in sandbox environment may be different e.g. SWA-UK-PRIME-PREM and SWA-UK-ECON. Please ensure to have the header "x-amzn-shipping-business-id" in the getRates and purchaseShipment requests to get the marketplace specific response.

What is API throttling and how is it assigned to me?

  • Amazon Shipping limits the rate of API requests that a shipper/integrator can make to the API every second to keep the service stable for all the customers. This process is defined as API throttling. At the time of on-boarding, every Application is allocated default 5 TPS (Transactions per second) as an initial limit which includes all requests in the following category: GetRates, PurchaseShipment, CancelShipment, GetShipmentDocument and a dedicated 5 TPS for Tracking API. If the allocated rate limit is exceeded, then the API will temporarily respond to all requests with a HTTP 429 status code. Client’s access will automatically be reinstated in the next seconds after which they can retry any failed requests and continue to use the API as before.

How do I need to manage Transaction per Second (TPS) limit?

  • Post integration development, integrators have to provide the TPS details with which they need to call the API & they have to stick to this TPS limit. If these limits are exceeded, then it can result an error message saying "You exceeded your quota for the requested resource". In this case, shippers/integrators will have to limit their request rate or reach out to their account manager for updating/increasing limits.
    For additional details and best practices please check the following Blogs:
    Overview of usage plans and rate limits
    Strategies to optimize rate limits for your application workloads

What are the most common printer issues?

Troubleshooting Printing Issues: The common printing issue shippers encounter with Amazon Shipping customer:

1. "Amazon Shipping labels are printing too small or only part of it is printed"

Please go through the following steps to resolve the issue:
a. Make sure your printer configuration matches the shipping labels being generated.

Example: The Printer that you are using is configured for 203 DPI and label is requested for 300 DPI.

PurchaseShipment API is invoked with the following shipping label configuration for 300 DPI and ZPL format, however Printer is configured for 203 DPI:

"requestedDocumentSpecification": {
        "format": "ZPL",
        "size": {
            "width": 4,
            "length": 6,
            "unit": "INCH"
        },
        "dpi": 300,
        "pageLayout": "DEFAULT",
        "needFileJoining": false,
        "requestedDocumentTypes": [
            "LABEL"
        ]
    }

b. If you are using 3P integrator, contact them to review if your printer configuration matches the shipping labels generated from them.

Illustration of the impact of incorrect and correct printer configuration on Shipping Labels: The label is generated with 300 DPI option, whereas the printer is configured with 203 DPI setting - Part of the label is cut due to mismatch in label generated format vs the printer configuration.

What are the list of of tracking status codes and eventCodes?

Tracking Statuses (Summary status)

  • PreTransit: package has been created but has not been picked up.
  • InTransit: package has been picked up and is in transit.
  • Delivered: package has been delivered successfully.
  • Lost: package is lost.
  • OutForDelivery: package is out for delivery.
  • Rejected: package has been rejected by the recipient.
  • Undeliverable: package was undeliverable.
  • DeliveryAttempted: delivery was attempted to the recipient location, but was not delivered.
  • PickupCancelled: indicate that pickup was canceled for the package.
  • AwaitingCustomerPickup:Package held at facility for the customer pickup.

Tracking Event Codes

  • ReadyForReceive: package has been created and is ready for pickup the shippers location. This is a pre-transit status event code.
  • PickupDone: package has been picked up by the carrier and is in transit within the carrier network.
  • Delivered: package has been delivered.
  • Departed: package has departed from a particular location in carrier network.
  • DeliveryAttempted: delivery was attempted but unsuccessful.
  • Lost: package is lost.
  • OutForDelivery: package is out for delivery.
  • ArrivedAtCarrierFacility: package is in transit and has been received at a carrier location.
  • Rejected: package was rejected by the recipient.
  • Undeliverable: package is undeliverable.
  • PickupCancelled: pickup scheduled for the package was canceled.
  • ReturnInitiated:Return label has been generated.
  • AvailableForPickup:Package held for recipient pickup.

What are the list of of tracking detail codes used to provide additional info on the forward and return leg of the shipment?

TrackingDetailCodes(Summary trackingDetailCodes)

  • BusinessClosed:Attempted delivery but the business was closed.
  • CustomerUnavailable:Attempted delivery but the recipient was unavailable.
  • PaymentNotReady:Attempted delivery but cash was not available from recipient.
  • OtpNotAvailable:Attempted delivery but the recipient did not have the PIN available.
  • DeliveryAttempted:Delivery was attempted.
  • UnableToAccess:Attempted delivery but could not access the recipient location.
  • UnableToContactRecipient:Attempted delivery but unable to contact the recipient to coordinate delivery.
  • DeliveredToBehindWheelieBin:Shipment delivered behind wheelie bin.
  • DeliveredToPorch:Shipment delivered to front porch or front door.
  • DeliveredToGarage:Shipment delivered to garage.
  • DeliveredToGarden:Shipment delivered to garden.
  • DeliveredToGreenhouse:Shipment delivered to greenhouse.
  • DeliveredToMailSlot:Shipment delivered to letterbox/mail slot.
  • DeliveredToMailRoom:Shipment delivered to mailroom.
  • DeliveredToNeighbor:Shipment delivered and signed for by neighbor.
  • DeliveredToRearDoor:Shipment delivered to rear porch or rear door.
  • DeliveredToReceptionist:Shipment delivered to reception.
  • DeliveredToShed:Shipment delivered to shed.
  • Signed:Shipment delivered and signature received.
  • Damaged:Shipment was damaged. When paired with Rejected this indicates the recipient refused to accept the shipment because the shipment was damaged. When paired with UNDELIVERABLE it means the shipment was undeliverable due to being damaged and may be returned to the seller.
  • IncorrectItems:Recipient refused to accept the shipment because the shipment contains incorrect item/s.
  • NotRequired:Recipient refused to accept the shipment because the recipient did not want the shipment.
  • Rejected:Recipient refused to accept the shipment.
  • CancelledByRecipient:Shipment was cancelled by the recipient. This tag is paired with the rejected shipment status.
  • AddressNotFound:Shipment is undeliverable and is returning to seller because the address was missing or incorrect.
  • HazmatShipment:Shipment is non-compliant Hazmat.
  • Undeliverable:Shipment is undeliverable and is returning to the seller.

What should be the shipDate in the getRates request ?

  • Amazon Shipping calculates the Package pick-up and delivery dates based on two parameters: 1) Pick-up window configured within Amazon Shipping, 2) ShipDate parameter sent in API getRate request (considered in UTC).
    The shipDate is optional, if not passed the system calculate the pick-up/ delivery windows based on timestamp of the API request, else, if a parameter is passed in shipDate it overrides the API request timestamp and considers the Date and Timestamp from the API request.
    Note - Timestamp in ShipDate is considered in UTC.

Example: Pick-up window: 6:00PM - 7:00PM
Scenario 1- If shipDate: 2022-03-10T10:00:00Z is passed in API getRate request, Amazon will consider the next available pick-up window for planning. In this case for 1 day delivery: Pick-up date: 10th March and Delivery date: 11th March
Scenario 2- If shipDate: 2022-03-10T18:30:00Z is passed in API getRate request, Amazon will consider the next available pick-up window for planning. In this case the next available window will be on the 11th of March. For 1 day delivery: Pick-up date: 11th March and Delivery date: 12th March

1. If you are unsure, we recommend to not pass the shipDate in API request and let Amazon plan the pick-up and delivery promises accordingly. In case of future parcel pick-up, please ensure to use the shipDate parameter as it is required for Amazon logistics to plan deliveries.

2. If passing the shipDate parameter, it is mandatory it should be a future date and timestamp. Providing a past date OR timestamp when compared to current GMT time would result in error response.
"errorCode":"INVALID_REQUEST","errorMessage":"ShipDate in the request XXXX-XX-XXTxx:xx:xxZ is in the past. Please pass a ship date in the future"

How does the sample request and response look like for a 2DD request?

  • Below is an example of the sample request:
{
  "shipTo": {
    "name": "TEST",
    "addressLine1": "Stamford Bridge",
    "addressLine2": "SWA Test Account",
    "stateOrRegion": "London",
    "city": "London",
    "countryCode": "GB",
    "postalCode": "BB3 2EN",
    "email": "[email protected]",
    "phoneNumber": "0123456789"
  },
  "shipFrom": {
    "name": "2DD test",
    "addressLine1": "68 Mansel Rd",
    "addressLine2": "SWA Test Account",
    "stateOrRegion": "Birmingham",
    "city": "Birmingham",
    "countryCode": "GB",
    "email": "[email protected]",
    "postalCode": "B10 9LZ"
  },
  "packages": [
    {
      "dimensions": {
        "length": 131.00,
        "width": 33.00,
        "height": 21.50,
        "unit": "CENTIMETER"
      },
      "weight": {
        "unit": "KILOGRAM",
        "value": 13.00
      },
      "items": [
        {
          "quantity": 1,
          "itemIdentifier": "A91-062-1/1",
          "description": "Item Description",
          "isHazmat": false,
          "weight": {
            "unit": "KILOGRAM",
            "value": 13.00
          }
        }
      ],
      "insuredValue": {
        "unit": "GBP",
        "value": 100.00
      },
      "packageClientReferenceId": "REF12345"
    }
  ],
  "channelDetails": {
    "channelType": "EXTERNAL"
  }
}
  • Sample 2DD Response:
{
  "payload": {
    "requestToken": "amzn1.1db70dcc-d563-47cb-833b-4a874b12e01e",
    "rates": [
      {
        "rateId": "e1b7cf2d1516d8c5343a087e10a5a2261ff36b83bdb5a91c6ce51b19586ed9861507200580943",
        "carrierId": "AMZN_UK",
        "carrierName": "Amazon Shipping",
        "serviceId": "SWA-UK-PRIME-PREM",
        "serviceName": "Amazon Shipping One Day",
        "promise": {
          "pickupWindow": {
            "start": "2022-04-08T18:00:00Z",
            "end": "2022-04-08T19:00:00Z"
          },
          "deliveryWindow": {
            "start": "2022-04-09T20:00:00Z",
            "end": "2022-04-09T20:00:00Z"
          }
        },
        "supportedDocumentSpecifications": [
          {
            "format": "PNG",
            "size": {
              "width": 4.0,
              "length": 6.0,
              "unit": "INCH"
            },
            "printOptions": [
              {
                "supportedDPIs": [
                  300,
                  203
                ],
                "supportedPageLayouts": [
                  "DEFAULT"
                ],
                "supportedFileJoiningOptions": [
                  false
                ],
                "supportedDocumentDetails": [
                  {
                    "name": "LABEL",
                    "isMandatory": true
                  }
                ]
              }
            ]
          },
          {
            "format": "ZPL",
            "size": {
              "width": 4.0,
              "length": 6.0,
              "unit": "INCH"
            },
            "printOptions": [
              {
                "supportedDPIs": [
                  300,
                  203
                ],
                "supportedPageLayouts": [
                  "DEFAULT"
                ],
                "supportedFileJoiningOptions": [
                  false
                ],
                "supportedDocumentDetails": [
                  {
                    "name": "LABEL",
                    "isMandatory": true
                  }
                ]
              }
            ]
          },
          {
            "format": "PDF",
            "size": {
              "width": 4.0,
              "length": 6.0,
              "unit": "INCH"
            },
            "printOptions": [
              {
                "supportedDPIs": [
                  300,
                  203
                ],
                "supportedPageLayouts": [
                  "DEFAULT"
                ],
                "supportedFileJoiningOptions": [
                  false
                ],
                "supportedDocumentDetails": [
                  {
                    "name": "LABEL",
                    "isMandatory": true
                  }
                ]
              }
            ]
          }
        ],
        "availableValueAddedServiceGroups": [
          
        ],
        "totalCharge": {
          "unit": "GBP",
          "value": 4.76
        },
        "billedWeight": {
          "value": 1.0,
          "unit": "KILOGRAM"
        },
        "requiresAdditionalInputs": false
      },
      {
        "rateId": "dcaad3aa31791b900cdb3d32c5b4e37d13dd4e3a30e2a784977cc7fdedb717e41647870923840",
        "carrierId": "AMZN_UK",
        "carrierName": "Amazon Shipping",
        "serviceId": "SWA-UK-2D",
        "serviceName": "Amazon Shipping Two Day",
        "promise": {
          "pickupWindow": {
            "start": "2022-04-08T18:00:00Z",
            "end": "2022-04-08T19:00:00Z"
          },
          "deliveryWindow": {
            "start": "2022-04-10T20:00:00Z",
            "end": "2022-04-10T20:00:00Z"
          }
        },
        "supportedDocumentSpecifications": [
          {
            "format": "PNG",
            "size": {
              "width": 4.0,
              "length": 6.0,
              "unit": "INCH"
            },
            "printOptions": [
              {
                "supportedDPIs": [
                  300,
                  203
                ],
                "supportedPageLayouts": [
                  "DEFAULT"
                ],
                "supportedFileJoiningOptions": [
                  false
                ],
                "supportedDocumentDetails": [
                  {
                    "name": "LABEL",
                    "isMandatory": true
                  }
                ]
              }
            ]
          },
          {
            "format": "ZPL",
            "size": {
              "width": 4.0,
              "length": 6.0,
              "unit": "INCH"
            },
            "printOptions": [
              {
                "supportedDPIs": [
                  300,
                  203
                ],
                "supportedPageLayouts": [
                  "DEFAULT"
                ],
                "supportedFileJoiningOptions": [
                  false
                ],
                "supportedDocumentDetails": [
                  {
                    "name": "LABEL",
                    "isMandatory": true
                  }
                ]
              }
            ]
          },
          {
            "format": "PDF",
            "size": {
              "width": 4.0,
              "length": 6.0,
              "unit": "INCH"
            },
            "printOptions": [
              {
                "supportedDPIs": [
                  300,
                  203
                ],
                "supportedPageLayouts": [
                  "DEFAULT"
                ],
                "supportedFileJoiningOptions": [
                  false
                ],
                "supportedDocumentDetails": [
                  {
                    "name": "LABEL",
                    "isMandatory": true
                  }
                ]
              }
            ]
          }
        ],
        "availableValueAddedServiceGroups": [
          
        ],
        "totalCharge": {
          "unit": "GBP",
          "value": 3.72
        },
        "billedWeight": {
          "value": 1.0,
          "unit": "KILOGRAM"
        },
        "requiresAdditionalInputs": false
      }
    ],
    "ineligibleRates": null
  }
}

How does the sample request and response look like for ON Amazon request?

  • Below is the example of Sample getRatesV2 request for ON Amazon label
{
	"shipTo": {
		"name": "Chris",
		"addressLine1": "Redacted",
		"addressLine2": "Redacted",
		"addressLine3": "Redacted",
		"companyName": "",
		"stateOrRegion": "Redacted",
		"city": "Redacted",
		"countryCode": "GB",
		"postalCode": "Redacted"
	},
	"shipFrom": {
		"name": "Gary",
		"addressLine1": "Redacted",
		"addressLine2": "Redacted",
		"stateOrRegion": "Redacted",
		"city": "Redacted",
		"countryCode": "GB",
		"postalCode": "Redacted",
		"email": "[email protected]",
		"phoneNumber": "Redacted"
	},
	"packages": [
		{
			"dimensions": {
				"unit": "CENTIMETER",
				"length": 29.3,
				"width": 32.0,
				"height": 39.0
			},
			"weight": {
				"unit": "GRAM",
				"value": 3386.0
			},
			"insuredValue": {
				"value": 10.0,
				"unit": "GBP"
			},
			"isHazmat": false,
			"packageClientReferenceId": "432626-0", /*This can be Amazon Order ID or Shipper internal Order ID*/
			"items": [
				{
					"itemValue": {
						"value": 26.99,
						"unit": "GBP"
					},
					"description": "Border Biscuits 100 Luxury Mini Packs with 5 Varieties",
					"itemIdentifier": "60334228527867",		/*This is OrderItemID*/
					"quantity": 1,
					"weight": {
						"unit": "GRAM",
						"value": 3086.0
					},
					"isHazmat": false
				}
			]
		}
	],
	"channelDetails": {
		"channelType": "AMAZON",	/*Channel Type = AMAZON for ON AMAZON label request*/
		"amazonOrderDetails": {
			"orderId": "202-7179886-3817928"		/*orderID is the Amazon Order number*/
		}
	}
}
  • Below is the example of getRatesV2 response for ON Amazon label
{
	"payload": {
		"ineligibleRates": [
			{
				"carrierId": "HERMES_UK",
				"carrierName": "Hermes UK",
				"ineligibilityReasons": [
					{
						"code": "UNKNOWN",
						"message": "It is not a premium offering"
					},
					{
						"code": "UNKNOWN",
						"message": "The ship method you selected for this order is not available because you have not accepted the carrier’s terms and conditions. To accept the carrier’s terms and conditions, please visit the Seller Central MWS API registration page at: https://sellercentral.amazon.com/orders-st/terms-and-conditions"
					}
				],
				"serviceId": "HERMES_UK_MFN_TWODAY_DROPOFF",
				"serviceName": "Hermes Two Day - Drop Off"
			},
			{
				"carrierId": "ROYAL_MAIL",
				"carrierName": "Royal Mail",
				"ineligibilityReasons": [
					{
						"code": "UNKNOWN",
						"message": "It is not a premium offering"
					}
				],
				"serviceId": "ROYAL_MFN_TRACKED_48",
				"serviceName": "Royal Mail Tracked 48"
			},
			{
				"carrierId": "AMZN_UK",
				"carrierName": "Amazon Shipping",
				"ineligibilityReasons": [
					{
						"code": "UNKNOWN",
						"message": "It is not a premium offering"
					}
				],
				"serviceId": "econ3-uk-mfn",
				"serviceName": "Amazon Shipping Standard Tracked"
			},
			{
				"carrierId": "DPD_UK",
				"carrierName": "DPD UK",
				"ineligibilityReasons": [
					{
						"code": "UNKNOWN",
						"message": "Does Not Meet Promised Delivery Date"
					},
					{
						"code": "UNKNOWN",
						"message": "The ship method you selected for this order is not available because you have not accepted the carrier’s terms and conditions. To accept the carrier’s terms and conditions, please visit the Seller Central MWS API registration page at: https://sellercentral.amazon.com/orders-st/terms-and-conditions"
					}
				],
				"serviceId": "DPD_UK_MFN_PARCEL_SAT",
				"serviceName": "Parcel Saturday"
			},
			{
				"carrierId": "HERMES_UK",
				"carrierName": "Hermes UK",
				"ineligibilityReasons": [
					{
						"code": "UNKNOWN",
						"message": "Does Not Meet Promised Delivery Date"
					},
					{
						"code": "UNKNOWN",
						"message": "The ship method you selected for this order is not available because you have not accepted the carrier’s terms and conditions. To accept the carrier’s terms and conditions, please visit the Seller Central MWS API registration page at: https://sellercentral.amazon.com/orders-st/terms-and-conditions"
					}
				],
				"serviceId": "HERMES_UK_MFN_STANDARD_DROPOFF",
				"serviceName": "Hermes Standard - Drop Off"
			},
			{
				"carrierId": "AMZN_UK",
				"carrierName": "Amazon Shipping",
				"ineligibilityReasons": [
					{
						"code": "UNKNOWN",
						"message": "Does Not Meet Promised Delivery Date"
					}
				],
				"serviceId": "std-uk-mfn",
				"serviceName": null
			},
			{
				"carrierId": "DPD_UK",
				"carrierName": "DPD UK",
				"ineligibilityReasons": [
					{
						"code": "UNKNOWN",
						"message": "The ship method you selected for this order is not available because you have not accepted the carrier’s terms and conditions. To accept the carrier’s terms and conditions, please visit the Seller Central MWS API registration page at: https://sellercentral.amazon.com/orders-st/terms-and-conditions"
					}
				],
				"serviceId": "DPD_UK_MFN_PARCEL",
				"serviceName": "Parcel Next Day"
			}
		],
		"rates": [
			{
				"availableValueAddedServiceGroups": [
					{
						"groupDescription": "Confirmation",
						"groupId": "VAS_GROUP_ID_CONFIRMATION",
						"isRequired": true,
						"valueAddedServices": [
							{
								"cost": {
									"unit": "GBP",
									"value": 0.3
								},
								"id": "SIGNATURE_CONFIRMATION",
								"name": "Signature confirmation"
							},
							{
								"cost": {
									"unit": "GBP",
									"value": 0.0
								},
								"id": "DELIVERY_CONFIRMATION",
								"name": "Delivery confirmation"
							}
						]
					},
					{
						"groupDescription": "Pickup",
						"groupId": "VAS_GROUP_ID_PICKUP",
						"isRequired": true,
						"valueAddedServices": [
							{
								"cost": {
									"unit": "GBP",
									"value": 0.0
								},
								"id": "CARRIER_PICKUP_CHARGE",
								"name": "Carrier Pickup"
							}
						]
					}
				],
				"billedWeight": null,
				"carrierId": "ROYAL_MAIL",
				"carrierName": "Royal Mail",
				"promise": {
					"deliveryWindow": {
						"end": "2022-04-28T22:59:59Z",
						"start": "2022-04-28T22:59:59Z"
					},
					"pickupWindow": {
						"end": null,
						"start": null
					}
				},
				"rateId": "70aeaea6-d904-43ab-b9b6-2520097a64a2",
				"requiresAdditionalInputs": false,
				"serviceId": "ROYAL_MFN_TRACKED_24",
				"serviceName": "Royal Mail Tracked 24",
				"supportedDocumentSpecifications": [
					{
						"format": "ZPL",
						"printOptions": [
							{
								"supportedDPIs": [
									300
								],
								"supportedDocumentDetails": [
									{
										"isMandatory": true,
										"name": "LABEL"
									}
								],
								"supportedFileJoiningOptions": [
									true
								],
								"supportedPageLayouts": [
									"LEFT"
								]
							}
						],
						"size": {
							"length": 6.0,
							"unit": "INCH",
							"width": 4.0
						}
					},
					{
						"format": "PNG",
						"printOptions": [
							{
								"supportedDPIs": [],
								"supportedDocumentDetails": [
									{
										"isMandatory": true,
										"name": "LABEL"
									}
								],
								"supportedFileJoiningOptions": [
									true
								],
								"supportedPageLayouts": [
									"LEFT"
								]
							}
						],
						"size": {
							"length": 6.0,
							"unit": "INCH",
							"width": 4.0
						}
					}
				],
				"totalCharge": {
					"unit": "GBP",
					"value": 10.77
				}
			},
			{
				"availableValueAddedServiceGroups": [
					{
						"groupDescription": "Pickup",
						"groupId": "VAS_GROUP_ID_PICKUP",
						"isRequired": true,
						"valueAddedServices": [
							{
								"cost": {
									"unit": "GBP",
									"value": 0.0
								},
								"id": "CARRIER_PICKUP_CHARGE",
								"name": "Carrier Pickup"
							}
						]
					}
				],
				"billedWeight": null,
				"carrierId": "AMZN_UK",
				"carrierName": "Amazon Shipping",
				"promise": {
					"deliveryWindow": {
						"end": "2022-04-28T19:00:00Z",
						"start": "2022-04-28T19:00:00Z"
					},
					"pickupWindow": {
						"end": "2022-04-27T16:00:00Z",
						"start": "2022-04-27T15:00:00Z"
					}
				},
				"rateId": "708ac4e1-0d43-4b12-82af-75fdb5205dc8",
				"requiresAdditionalInputs": false,
				"serviceId": "prime-premium-uk-mfn",
				"serviceName": "Amazon Shipping One-Day Tracked",
				"supportedDocumentSpecifications": [
					{
						"format": "ZPL",
						"printOptions": [
							{
								"supportedDPIs": [
									300
								],
								"supportedDocumentDetails": [
									{
										"isMandatory": true,
										"name": "LABEL"
									}
								],
								"supportedFileJoiningOptions": [
									true
								],
								"supportedPageLayouts": [
									"LEFT"
								]
							}
						],
						"size": {
							"length": 6.0,
							"unit": "INCH",
							"width": 4.0
						}
					},
					{
						"format": "PNG",
						"printOptions": [
							{
								"supportedDPIs": [],
								"supportedDocumentDetails": [
									{
										"isMandatory": true,
										"name": "LABEL"
									}
								],
								"supportedFileJoiningOptions": [
									true
								],
								"supportedPageLayouts": [
									"LEFT"
								]
							}
						],
						"size": {
							"length": 6.0,
							"unit": "INCH",
							"width": 4.0
						}
					}
				],
				"totalCharge": {
					"unit": "GBP",
					"value": 3.34
				}
			}
		],
		"requestToken": "amzn1.rq.c7xxxx28-a634-45da-80d7-73e5xxx440e0.101"
	}
}

How should the purchaseShipment request be created from getRates response for ON Amazon request?

  • Below you can find a snippet of getRates response and example of building the purchaseShipment request for ZPL. Please note the following:
    (1) There are 2 Value Added Services (VAS) groups: VASGROUP_ID_CONFIRMATION and VAS_GROUP_ID_PICKUP and both the VAS is marked as "isRequired": true_ - We would need to pass the values for both the VAS ids in purchaseShipment request. Another thing to note is VAS - VAS_GROUP_ID_CONFIRMATION has two available Services - SIGNATURE_CONFIRMATION and DELIVERY_CONFIRMATION. In purchaseShipment request ONLY 1 Service can be enabled for each VAS groups. In the example provided below from VAS service "Pickup" - CARRIER_PICKUP_CHARGE is selected and from VAS service "Confirmation" - DELIVERY_CONFIRMATION is selected for purchaseShipment request.
    (2) ZPL DPI - 300 DPI is supported and is required in the purchaseShipment request.

  • Below you can find a snippet of getRates response and example of building the purchaseShipment request for PNG or PDF.
    Please note the following:
    (1) There is 1 Value Added Services (VAS) groups: VASGROUP_ID_PICKUP and VAS is marked as "isRequired": true_ - We would need to pass the values for the VAS id in purchaseShipment request. In the example provided below from VAS service "Pickup" - CARRIER_PICKUP_CHARGE is selected for purchaseShipment request.
    (2) PNG DPI - Null . As the DPI is NULL, DPI tag should be omitted from the purchaseShipment request. Same will be applicable for PDF.