Vendor Direct Fulfillment Shipping API v2021-12-28 Use Case Guide

How to use the vendor direct fulfillment (DF) shipping API.

API Version: 2021-12-28

What is the Direct Fulfillment Shipping API?

Vendors can use the Direct Fulfillment Shipping API to exchange shipment related documents with Amazon. Vendors can request shipping labels, receive shipping labels, send shipment confirmations, get packing slips, and retrieve customer invoices.

Please note that customer invoices are specific to the India region.

The following operations are available:

Operation HTTP Method Path Description
submitShippingLabelRequest POST /vendor/directFulfillment/shipping/2021-12-28/shippingLabels Submit single or multiple shipping label requests.
getShippingLabels GET /vendor/directFulfillment/shipping/2021-12-28/shippingLabels Get a list of shipping labels based on filter criterion.

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.

getShippingLabel GET /vendor/directFulfillment/shipping/2021-12-28/shippingLabels/{purchaseOrderNumber} Get a shipping label by purchase order number.

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.

createShippingLabels POST /vendor/directFulfillment/shipping/2021-12-28/shippingLabels/{purchaseOrderNumber} Creates shipping labels for a purchase order and returns the labels. This is a synchronous operation that does not require calling the Transaction Status API.

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.

submitShipmentConfirmations POST /vendor/directFulfillment/shipping/2021-12-28/shipmentConfirmations Submit single or multiple shipment confirmations to Amazon.
submitShipmentStatusUpdates POST /vendor/directFulfillment/shipping/2021-12-28/shipmentStatusUpdates Submit a shipment status update. Vendor Own Carrier vendors only.
getPackingSlips GET /vendor/directFulfillment/shipping/2021-12-28/packingSlips Returns a list of packing slips for the purchase orders that match the criteria specified. Date range to search must not be more than 7 days.

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.

getPackingSlip GET /vendor/directFulfillment/shipping/2021-12-28/packingSlips/{purchaseOrderNumber} Returns a packing slip based on the purchaseOrderNumber that you specify.

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.

getCustomerInvoices GET /vendor/directFulfillment/shipping/2021-12-28/customerInvoices Get a list of customer invoices based on filter criterion.

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.

getCustomerInvoice GET /vendor/directFulfillment/shipping/2021-12-28/customerInvoices/{purchaseOrderNumber} Returns a customer invoice based on the purchaseOrderNumber that you specify.

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.

Submit shipping label requests

The submitShippingLabelRequest operation lets vendors request shipping label information from Amazon for each purchase order. You can send multiple shipping label requests in bulk in one API call by adhering to the schema. When shipment labels are created by Amazon, they will be available to download using the getShippingLabel operation.

Verification of successfully submitted shipping label requests

Vendors can verify the status of their shipping label requests using the Direct Fulfillment Transaction Status API 2021-12-28. Allow the system up to 15 min to show the status once submitted. If the transaction status is not updated after 30 minutes, open a "Contact Us" case in Vendor Central.

The following diagram shows the workflow for submitting shipping label requests.

Direct Fulfillment integration workflow for submitting shipping label requestsDirect Fulfillment integration workflow for submitting shipping label requests

Business requirements

  • Amazon must receive a shipping label request after the purchase order is confirmed to be accepted by the vendor using the order acknowledgement API.

  • If using Amazon own shipping labels, sending item information or package information in the request is optional.

Country specific business requirements

No country specific requirements exist.

submitShippingLabelRequest request

To request shipping labels, call the submitShippingLabelRequest operation and pass the following parameters:

Body parameters:

Name

Description

Required
shippingLabelRequests Request one or more shipping labels.

Type: < ShippingLabelRequest > array

Yes

Request example

POST "https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/2021-12-28/shippingLabels"
{
  "shippingLabelRequests": [
    {
      "purchaseOrderNumber": "2JK3S9VC",
      "sellingParty": {
        "partyId": "999US"
      },
      "shipFromParty": {
        "partyId": "ABCD"
      },
      "containers": [
        {
          "containerType": "carton",
          "containerIdentifier": "123",
          "trackingNumber": "XXXX",
          "dimensions": {
            "length": "12",
            "width": "12",
            "height": "12",
            "unitOfMeasure": "IN"
          },
          "weight": {
            "unitOfMeasure": "KG",
            "value": "10"
          },
          "packedItems": [
            {
              "itemSequenceNumber": 1,
              "buyerProductIdentifier": "B07DFVDRAB",
              "packedQuantity": {
                "amount": 1,
                "unitOfMeasure": "Each"
              }
            }
          ]
        }
      ]
    }
  ]
}

submitShippingLabelRequest response

A successful response includes the following:

Name

Description

Required
transactionId GUID to identify this transaction. This value can be used with the Transaction Status API 2021-12-28 to return the status of this transaction.

Type: string

No

Response example

{
  "transactionId": "20190905010908-8a3b6901-ef20-412f-9270-21c021796605"
}

Get shipping labels

The getShippingLabels operation returns shipping labels for all orders which meet the filter criteria specified in the request. You must have already requested shipping labels using the submitShippingLabelRequest operation before you use this API to get shipping labels available to you for fulfillment. Amazon recommends that vendors check for shipping labels at least once per hour during business hours. Depending on your business volume, you may choose to check more frequently. You can get up to 100 shipping labels in one API call. If there are more than 100 shipping labels you can use the nextToken value to get the next set of shipping labels.

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.

The following diagram shows the integration workflow when retrieving shipping labels:

Direct Fulfillment integration workflow when retrieving shipping labelsDirect Fulfillment integration workflow when retrieving shipping labels

getShippingLabels request

To retrieve a list of shipping labels, call the getShippingLabels operation and pass the following parameters:

Query parameters:

Name Description Required
shipFromPartyId The vendor warehouseId for order fulfillment. If not specified, the response will contain orders for all warehouses.

Type: string

No
limit The limit to the number of records returned.

Type: integer

No
createdAfter Shipping labels that became available after this date and time will be included in the response. Must be in ISO-8601 date/time format.

Type: string (date-time)

Yes
createdBefore Shipping labels that became available before this date and time will be included in the result. Must be in ISO-8601 date/time format.

Type: string (date-time)

Yes
sortOrder Sort ASC or DESC by order creation date.

Type: enum ( SortOrder )

No
nextToken Used for pagination when there are more ship labels than the specified result size limit. The token value is returned in the previous API call.

Type: string

No

Request example

GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/2021-12-28/shippingLabels?limit=2&createdAfter=2020-02-15T14:00:00-08:00&createdBefore=2020-02-20T00:00:00-08:00&sortOrder=DESC

getShippingLabels response

A successful response includes the following:

Name Description Required
pagination If more than 100 ship labels are returned, nextToken is returned in the response for pagination.

Type: string

No
shippingLabels List of ship labels.

Type: < ShippingLabel > array

No

Response example

{
  "pagination": {
    "nextToken": "MDAwMDAwMDAwMQ=="
  },
  "shippingLabels": [
    {
      "purchaseOrderNumber": "2JK3S9VC",
      "sellingParty": {
        "partyId": "999US"
      },
      "shipFromParty": {
        "partyId": "ABCD"
      },
      "labelFormat": "PNG",
      "labelData": [
        {
          "packageIdentifier": "PKG001",
          "trackingNumber": "1Z6A34Y60369738804",
          "shipMethod": "UPS_GR_RES",
          "shipMethodName": "UPS Ground Residential",
          "content": "Base 64 encoded string goes here "
        }
      ]
    }, {
      "purchaseOrderNumber": "2JK3S9VD",
      "sellingParty": {
        "partyId": "999US"
      },
      "shipFromParty": {
        "partyId": "ABCD"
      },
      "labelFormat": "PNG",
      "labelData": [
        {
          "packageIdentifier": "PKG002",
          "trackingNumber": "1Z6A34Y60369738805",
          "shipMethod": "UPS_GR_RES",
          "shipMethodName": "UPS Ground Residential",
          "content": "Base 64 encoded string goes here "
        }
      ]
    }
  ]
}

Get shipping label

The getShippingLabel operation returns information about the shipping label that you specify using the purchase order number. The response includes complete shipping label information for the purchase order, including label type, purchase order details and ship method.

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.

You can also use this API to get details for any shipping label (in the time range of 7 days from a rolling window of last 6 months, after the vendor went live on API).

The following diagram shows the integration workflow for retrieving a specific shipping label:

Direct Fulfillment integration workflow for retrieving a specific shipping labelDirect Fulfillment integration workflow for retrieving a specific shipping label

Business requirements

  • What kind of labels are available to download?

Both ZPL and PNG file format labels are supported. Label content is provided in base64 string format so you can convert the string into desired label format. The choice of label format is with the vendor and they decide this as part of on-boarding process into direct fulfillment program.

  • By when the shipping label should be requested?

ZPL and PNG labels should be requested only on the day when the orders are due for shipping.

Country specific business requirements

There are no country specific requirements for shipping label responses.

getShippingLabel request

To request a shipping label, call the getShippingLabel operation and pass the following parameters:

Path parameters:

Name Description Required
purchaseOrderNumber The purchase order number for which you want to return the shipping label. It should be the same purchaseOrderNumber as received in the order.

Type: string

Yes

Request example

GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/2021-12-28/shippingLabels/2JK3S9VC

getShippingLabel response

A successful response includes the following:

Name Description Required
purchaseOrderNumber The purchase order number for this order.

Type: string

Yes
sellingParty The identifier of the selling party or vendor.

Type: PartyIdentification

Yes
shipFromParty The warehouse code of the vendor.

Type: PartyIdentification

Yes
labelFormat The format of the label.

enum ( LabelFormat )

Yes
labelData Provides the details of the packages in this shipment.

Type: < LabelData > array

Yes

Response example

{
  "purchaseOrderNumber": "2JK3S9VC",
  "sellingParty": {
    "partyId": "999US"
  },
  "shipFromParty": {
    "partyId": "ABCD"
  },
  "labelFormat": "PNG",
  "labelData": [
    {
      "packageIdentifier": "PKG001",
      "trackingNumber": "1Z6A34Y60369738804",
      "shipMethod": "UPS_GR_RES",
      "shipMethodName": "UPS Ground Residential",
      "content": "Base 64 encoded string goes here"
    }
  ]
}

Create shipping labels (synchronous)

The createShippingLabels operation creates shipping labels for a purchase order and returns the labels. It does not require calling the Transaction Status API.

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.

The following diagram shows the workflow for creating shipping labels using the createShippingLabels operation.

Direct Fulfillment integration workflow for creating shipping labels synchronouslyDirect Fulfillment integration workflow for creating shipping labels synchronously

Business requirements

You can return shipping labels for one purchase order per request. Multiple purchase orders in a single request is not supported.

Country specific business requirements

There are no country specific requirements.

createShippingLabels request

To create shipping labels synchronously, call the createShippingLabels operation and pass the following parameters:

Path parameter:

Name Description Required
purchaseOrderNumber The purchaseOrderNumber for the shipping labels you want.

Type: string

Yes

Body parameter:

Name Description Required
sellingParty ID of the selling party or vendor.

Type: PartyIdentification

Yes
shipFromParty Warehouse code of vendor.

Type: PartyIdentification

Yes
containers A list of the packages in this shipment.

Type: < Container > array

No

Request example

POST https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/
shipping/2021-12-28/shippingLabels/XhvBghry
{
  "sellingParty": {
    "partyId": "999US"
  },
  "shipFromParty": {
    "partyId": "ABCD"
  }
}

createShippingLabels response

A successful response includes the following:

Name Description Required
purchaseOrderNumber The purchase order number for this order.

Type: string

Yes
sellingParty The identifier of the selling party or vendor.

Type: PartyIdentification

Yes
shipFromParty The warehouse code of the vendor.

Type: PartyIdentification

Yes
labelFormat The format of the label.

enum ( LabelFormat )

Yes
labelData Provides the details of the packages in this shipment.

Type: < LabelData > array

Yes

Response example

{
  "purchaseOrderNumber": "XhvBghry",
  "sellingParty": {
    "partyId": "999US"
  },
  "shipFromParty": {
    "partyId": "ABCD"
  },
  "labelFormat": "PNG",
  "labelData": [
    {
      "packageIdentifier": "1",
      "trackingNumber": "1Z69664F0310685739",
      "shipMethod": "UPS_GR_RES_SIG",
      "shipMethodName": "UPS Ground Residential",
      "content": "Base 64 encoded string goes here"
    }
  ]
}

Response example (error)

{
  "errors": [
    {
      "code": "InvalidInput",
      "message": "[MISMATCHED_ITEM]: Request Rejected: Order quantity does not match the shipped quantity. All items in the order must be provided. Ensure you add the correct quantity of shipped items to packages. For items - ${fnSku}, the expected quantity is ${expectedQuantity}, but the provided quantity is ${providedQuantity}.",
      "details": ""
    }
  ]
}

List of possible error response details

The following table contains a list of all possible error response details. Included are any recommended steps to take to resolve the error condition before retrying the request. You should design a failure handling mechanism in your application to anticipate and handle these potential errors.

It is possible that additional error responses will be added over time, so your application should also be prepared to gracefully handle errors that are not included in this list.

Bracketed values preceded by a $ that appear in the Message column (for example, ${fnSku}) will be replaced with actual values in the error response.

Code Message Details
InvalidInput [MISMATCHED_ITEM]: Request Rejected: Order quantity does not match the shipped quantity. All items in the order must be provided. Ensure you add the correct quantity of shipped items to packages. For items - ${fnSku}, the expected quantity is ${expectedQuantity}, but the provided quantity is ${providedQuantity}. -
InvalidInput [NO_ITEMS_PRESENT]: Request Rejected: Order ID ${shipmentId} has items not assigned to any package(s). Please make sure all items are map to the package(s). -
InvalidInput [PACKAGE_DIMENSION_NOT_VALID]: Request Rejected: Order ID ${shipmentId} has invalid dimension for the package(s). Please add valid dimensions for your package(s). -
InvalidInput [PACKAGE_WEIGHT_NOT_VALID]: Request Rejected: Order ID ${shipmentId} has invalid weight for the package(s). Please add valid weight for your package(s). -
InvalidInput [PIECE_NUMBER_ONE_NOT_PROVIDED]: The container sequence number '1' is not provided for at least one item. Check if the container sequence number is missing -
InvalidInput [INCONSISTENT_PIECE_NUMBER_QUANTITY]: The container sequence number of at least one item is either not consistent or incompatible with the item quantity. Verify the container sequence number is correct, and the quantity of each item is the same as the item sequence number -
InvalidInput [INVALID_VENDOR_CODE]: Invalid vendor code ${vendorCode}. Verify that the vendor code is correct for the order -
InvalidInput [INVALID_ORDER_ID_WAREHOUSE_COMBINATION]: Shipping Label Rejected: Order ID ${shipmentId} doesn't belong to warehouse ${warehouseCode}. Please verify that the warehouse code and Order Id are correct -
InvalidInput [INCORRECT_VENDOR_GROUP_ID]: Invalid vendor group Id ${vendorGroupId}. Verify that the vendor group Id is correct for the order -
InvalidInput [DUPLICATE_VENDOR_PACKAGE_ID]: Duplicate VendorPackageIds. Please fix the Duplicate container identifiers and try again -
InvalidInput [EMPTY_VENDOR_PACKAGE_ID]: Invalid VendorPackageIds. Please fix the Invalid container identifiers and try again -
InvalidInput [SHIP_METHOD_NOT_SUPPORTED]: ${ship_method} is not supported. Use your existing set-up to generate the label for ${ship_method} -
InvalidInput [SHIP_METHOD_CHANGED]: The ship method for this PO has changed from ${old_ship_method} to ${ship_method}. Use your existing set-up to generate the label for ${ship_method} -
InvalidInput [INCONSISTENT_SHIP_METHODS]: Request Rejected: Different ship methods are assigned across different packages. Try to ship all items in a single box. If that is not possible, please contact us. -
ConflictError [SHIPMENT_NOT_MUTABLE]: Request Rejected: Package dimensions for Order ID ${shipmentId} cannot be updated with current status. No further action is required. -
ConflictError [ORDER_SHIPPED_WITH_VENDOR_LABEL]: You have already shipped the order with a carrier other than Amazon Transportation, therefore you can't print the label for this order. No action is required. You have already confirmed the shipped order. -
InternalFailure We encountered an internal error. Please try again. -

Submit shipment confirmations

The submitShipmentConfirmations operation lets vendors submit shipment confirmations to Amazon. Your shipment confirmation allows us to efficiently track your shipments and inform our customers. It contains information about the items being shipped, including purchase order number, ship date, estimated delivery date, and tracking number.

Shipment confirmations allow us to collaborate more effectively with carriers in tracking your shipments.

The lack of valid shipment confirmations can result in:

  • Inadequate visibility about shipments.

  • Errors in reconciling the physical shipments with purchase orders.

  • Manual follow-ups to resolve discrepancies.

Verification of successfully submitted shipment confirmations

Vendors can verify the status of their shipment confirmations via "Vendor Central >Orders> Direct Fulfillment Orders" or using the Direct Fulfillment Transaction Status API 2021-12-28. Allow the system up to 10 min to see the status once submitted. If Vendor Central is not showing the correct values for the shipment confirmation, open a "Contact Us" case in Vendor Central. Refer to the Business Requirements section for information about creating shipment confirmations.

The following diagram shows the integration workflow for submitting shipment confirmations:

Direct Fulfillment integration workflow for submitting shipment confirmationsDirect Fulfillment integration workflow for submitting shipment confirmations

Business requirements

  • You should use this API to confirm shipment of an order within 4 hours after the order has shipped from your warehouse.

  • For floor denied shipments, set the "shipmentStatus" field value to "FLOOR_DENIAL".

  • All the purchase order line items should be present in the shipment confirmation. Partial order fulfillment is not allowed. Vendors should reject the order as floor denial if any of the line items are not available to fulfill.

  • The "itemSequenceNumber" for an item should be the same as was received in the order message.

  • Either "buyerProductIdentifier" or "vendorProductIdentifier" is mandatory to send in the shipment confirmation. You need to send the same value as received in the purchase order.

  • For vendor own carriers, sending "scacCode" is mandatory.

  • If the shipment label is provided by Amazon, then the container section is optional since Amazon has access to the package information. Items section is mandatory to submit.

  • The container in a shipment confirmation must have a shipMethod specified.

Country specific business requirements

None

submitShipmentConfirmations request

To submit shipment confirmations, call the submitShipmentConfirmations operation and pass the following parameters:

Body parameters:

Name Description Required
shipmentConfirmations List of confirmed shipments

Type: < ShipmentConfirmation > array

Yes

Request example

POST https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/2021-12-28/shipmentConfirmations
{
  "shipmentConfirmations": [
    {
      "purchaseOrderNumber": "PO00050003",
      "shipmentDetails": {
        "shippedDate": "2019-08-07T19:56:45.632Z",
        "shipmentStatus": "SHIPPED",
        "isPriorityShipment": true,
        "estimatedDeliveryDate": "2019-08-07T19:56:45.632Z"
      },
      "sellingParty": {
        "partyId": "VENDORCODE"
      },
      "shipFromParty": {
        "partyId": "VENDORWAREHOUSECODE"
      },
      "items": [
        {
          "itemSequenceNumber": 1,
          "buyerProductIdentifier": "ASIN001",
          "vendorProductIdentifier": "9782700001659",
          "shippedQuantity": {
            "amount": 100,
            "unitOfMeasure": "Each"
          }
        },
        {
          "itemSequenceNumber": 2,
          "buyerProductIdentifier": "ASIN002",
          "vendorProductIdentifier": "9782700001659",
          "shippedQuantity": {
            "amount": 100,
            "unitOfMeasure": "Each"
          }
        },
        {
          "itemSequenceNumber": 3,
          "buyerProductIdentifier": "ASIN003",
          "vendorProductIdentifier": "9782700001659",
          "shippedQuantity": {
            "amount": 100,
            "unitOfMeasure": "Each"
          }
        },
        {
          "itemSequenceNumber": 4,
          "buyerProductIdentifier": "ASIN004",
          "vendorProductIdentifier": "9782700001659",
          "shippedQuantity": {
            "amount": 100,
            "unitOfMeasure": "Each"
          }
        }
      ],
      "containers": [
        {
          "containerType": "carton",
          "containerIdentifier": "123",
          "trackingNumber": "TRACK001",
          "scacCode": "SCAC001",
          "carrier": "ABCD001",
          "shipMethod": "UPS",
          "dimensions": {
            "length": "10",
            "width": "10",
            "height": "10",
            "unitOfMeasure": "IN"
          },
          "weight": {
            "unitOfMeasure": "KG",
            "value": "10"
          },
          "packedItems": [
            {
              "itemSequenceNumber": 1,
              "buyerProductIdentifier": "ASIN001",
              "packedQuantity": {
                "amount": 100,
                "unitOfMeasure": "Each"
              }
            }
          ]
        },
        {
          "containerType": "carton",
          "containerIdentifier": "234",
          "trackingNumber": "TRACK002",
          "scacCode": "SCAC001",
          "carrier": "ABCD001",
          "shipMethod": "UPS",
          "dimensions": {
            "length": "10",
            "width": "10",
            "height": "10",
            "unitOfMeasure": "IN"
          },
          "weight": {
            "unitOfMeasure": "KG",
            "value": "10"
          },
          "packedItems": [
            {
              "itemSequenceNumber": 2,
              "buyerProductIdentifier": "ASIN002",
              "packedQuantity": {
                "amount": 100,
                "unitOfMeasure": "Each"
              }
            }
          ]
        },
        {
          "containerType": "carton",
          "containerIdentifier": "ABCD",
          "trackingNumber": "TRACK003",
          "scacCode": "SCAC001",
          "carrier": "ABCD001",
          "shipMethod": "UPS",
          "dimensions": {
            "length": "10",
            "width": "10",
            "height": "10",
            "unitOfMeasure": "IN"
          },
          "weight": {
            "unitOfMeasure": "KG",
            "value": "10"
          },
          "packedItems": [
            {
              "itemSequenceNumber": 3,
              "buyerProductIdentifier": "ASIN003",
              "packedQuantity": {
                "amount": 100,
                "unitOfMeasure": "Each"
              }
            }
          ]
        },
        {
          "containerType": "carton",
          "containerIdentifier": "id12",
          "trackingNumber": "TRACK004",
          "scacCode": "SCAC001",
          "carrier": "ABCD001",
          "shipMethod": "UPS",
          "dimensions": {
            "length": "10",
            "width": "10",
            "height": "10",
            "unitOfMeasure": "IN"
          },
          "weight": {
            "unitOfMeasure": "KG",
            "value": "10"
          },
          "packedItems": [
            {
              "itemSequenceNumber": 4,
              "buyerProductIdentifier": "ASIN004",
              "packedQuantity": {
                "amount": 100,
                "unitOfMeasure": "Each"
              }
            }
          ]
        }
      ]
    }
  ]
}

submitShipmentConfirmations response

A successful response includes the following:

Name Description Required
transactionId GUID to identify this transaction. This value can be used with the Transaction Status API 2021-12-28 to return the status of this transaction.

Type: string

Yes

Response example

{
  "transactionId": "20190905010908-8a3b6901-ef20-412f-9270-21c021796605"
}

Submit shipment status updates

IMPORTANT: Shipment Status Updates are only to be used by VOC (Vendor Own Carrier) vendors. This means vendors that use their own carrier for shipment delivery and do not use Amazon carriers to transport the shipment to the customer. Vendors will ultimately cover the transportation costs and the responsibility to deliver the shipment to customer.

The submitShipmentStatusUpdates operation allows vendors to update the transportation status event for shipments that are on route to the final customer. VOC vendors are required to update shipment status (commonly known as scans) during the transportation phase.

This information will then be forwarded to Amazon customers on the "your Orders" page and thus will improve visibility on the order tracking and delivery process.

Failure to update shipment status updates can result in bad operational KPIs such as low scan rate and eventually warehouse suspension.

Verification of successfully submitted shipment status updates

Vendors can verify the status of their shipment status updates via "Vendor Central >Orders> Direct Fulfillment Orders" or by using the Direct Fulfillment Transaction Status 2021-12-28 API. Allow the system up to 10 min to see the status once submitted. If Vendor Central is not showing the correct values for the shipment confirmation, open a "Contact Us" case in Vendor Central. Refer to the Business Requirements section for information about creating shipment confirmations.

The following diagram shows the integration workflow for submitting shipment status updates:

Direct Fulfillment integration workflow for submitting shipment status updatesDirect Fulfillment integration workflow for submitting shipment status updates

Business requirements

  • You should use this API only if you use your own carrier to transport the shipment to the customer i.e. you are a VOC (Vendor Own Carrier) vendor.

  • You should only use this API to update the status of a shipment after the shipment is confirmed via shipment confirmation API or Vendor Central shipment confirmation.

  • The trackingNumber in the shipment status API should match 100% with the trackingNumber provided in the shipment confirmation, otherwise shipment status update will fail.

  • One Shipment Status Update API call should correspond to one physical package. You can update the shipment status for several packages in one API call by batching them as an array of Shipment Status Updates.

  • A direct fulfillment order can result in several physical packages to be delivered to the customer. Thus, several shipment status updates are needed to reflect the full shipment status of the complete order.

  • Vendors should send shipment status whenever possible following the Amazon Shipment Status guidelines.

  • For scheduled delivery orders, vendors should send the "shipmentSchedule" array that specifies estimated delivery time and delivery window.

Country specific business requirements

None

Additional fields explanation

1) "statusCode" and "reasonCode"

These fields are standard codes used in EDI standards (for example, ISA X12 and EDIFACT) that are used to provide a specific status event and the reason for the status event. We expect a specific combination of "statusCode" and "reasonCode" that determine an event within the shipment transportation phase to the end customer.

These are the status and reason codes we support and their equivalency to current Vendor Central:

EDIFACT Status CodeEDIFACT Reason CodeOperational DescriptionVendor Central UI Equivalency
404117Shipment is delayed because of a large scale accidentDELAYED
301000Shipment delivered to customerDELIVERED
101000Shipment has departed the FCDEPARTED_FROM_FC
201000Shipment arrived at a carrier facilityIN_TRANSIT
409000Carrier lost the shipmentLOST
302000Shipment is out for deliveryOUT_FOR_DELIVERY
407000Recipient refused to accept the shipmentREJECTED
416000Shipment is undeliverable and will be destroyedUNDELIVERABLE
X12 Status CodeX12 Reason CodeOperational DescriptionVendor Central UI Equivalency
DEAFShipment is delayed because of a large scale accidentDELAYED
D1NSShipment delivered to customerDELIVERED
XBNSShipment has departed the FCDEPARTED_FROM_FC
O1NSShipment arrived at a carrier facilityIN_TRANSIT
CAPLCarrier lost the shipmentLOST
ODNSShipment is out for deliveryOUT_FOR_DELIVERY
A7AMRecipient refused to accept the shipmentREJECTED
APBGShipment is undeliverable and will be destroyedUNDELIVERABLE

submitShipmentStatusUpdates request

To submit shipment status updates, call the submitShipmentStatusUpdates operation and pass the following parameters:

Body parameters:

Name Description Required
shipmentStatusUpdates List of confirmed shipments.

Type: < ShipmentStatusUpdate > array

Yes

Request example

POST https://sellingpartnerapi-na.amazon.com/ /vendor/directFulfillment/shipping/2021-12-28/shipmentStatusUpdates
{
  "shipmentStatusUpdates": [
    {
      "purchaseOrderNumber": "DX00050015",
      "sellingParty":
      {
        "partyId": "999US"
      },
      "shipFromParty":
      {
        "partyId": "ABCD"
      },
      "statusUpdateDetails":
      {
        "trackingNumber": "TRACK005",
        "statusDateTime": "2020-08-07T19:56:45Z",
        "statusCode": "D1",
        "reasonCode": "NS",
        "statusLocationAddress":
        {
          "name": "ABC",
          "addressLine1": "1st street",
          "city": "Seattle",
          "countryCode": "US",
          "postalCode": "124",
          "stateOrRegion": "CA"
        }
      }
    }
  ]
}

submitShipmentStatusUpdates response

A successful response includes the following:

Name Description Required
transactionId GUID to identify this transaction. This value can be used with the Transaction Status API v2021-12-28 to return the status of this transaction.

Type: string

Yes

Response example:

{
  "transactionId": "20190905010908-8a3b6901-ef20-412f-9270-21c021796605"
}

Get packing slips

The getPackingSlips operation returns a list of packing slips for the orders which meet the criteria specified. If you need to get a packing slip for a specific order, use the getPackingSlip operation instead.

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.

You should use this API to get packing slips for the purchase orders available to you for fulfillment. Amazon recommends that vendors check for orders at least once per hour during business hours. Depending on your business volume, you may choose to check more frequently. You can get up to 100 packing slips in one API call. If there are more than 100 packing slips, you can use the nextToken value as a parameter in your next request to get the next set.

The following diagram shows the integration workflow when retrieving packing slips:

Direct Fulfillment integration workflow when retrieving packing slipsDirect Fulfillment integration workflow when retrieving packing slips

getPackingSlips request

To retrieve packing slips, call the getPackingSlips operation and pass the following parameters:

Query parameters:

Name Description Required
shipFromPartyId The vendor warehouseId from which the order will be fulfilled. If not specified the result will contain orders for all warehouses.

Type: string

No
limit The limit to the number of records returned.

Type: integer

No
createdAfter Packing slips that became available after this date and time will be included in the result. Must be in ISO-8601 date/time format.

Type: string (date-time)

Yes
createdBefore Packing slips that became available before this date and time will be included in the result. Must be in ISO-8601 date/time format.

Type: string (date-time)

Yes
sortOrder Sort ASC or DESC by packing slip creation date.

Type: enum ( SortOrder )

No
nextToken Used for pagination when there are more orders than the specified result size limit. The token value is returned in the previous API call.

Type: string

No

Request example

GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/2021-12-28/packingSlips?createdBefore=2020-06-12T12:00:00-08:00&createdAfter=2020-06-12T00:00:00-08:00&limit=2&sortOrder=DESC

getPackingSlips response

A successful response includes the following:

Name Description Required
pagination If more than 100 orders are returned, nextToken is returned in the response for pagination.

Type: string

No
packingSlips Includes details for the packing slips.

Type: < PackingSlip > array

No

Response example

{
  "pagination": {
    "nextToken": "NEBxNEBxNEBxNR=="
  },
  "packingSlips": [
    {
      "purchaseOrderNumber": "UvgABdBjQ",
      "content": "base64 encoded string",
      "contentType": "application/pdf"
    },
    {
      "purchaseOrderNumber": "VvgCDdBjR",
      "content": "base64 encoded string",
      "contentType": "application/pdf"
    }
  ]
}

Get packing slip

The getPackingSlip operation returns the packing slip for the purchase order number that you specify. The response includes a base64 encoded string of the packing slip. The content type will always be "application/pdf".

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.

The following diagram shows the integration workflow when retrieving a packing slip:

Direct Fulfillment integration workflow when retrieving a packing slipDirect Fulfillment integration workflow when retrieving a packing slip

Business requirements

  • Are packing slips required for all orders?

A packing slip is required only if it is for a Business to Business [B2B] order or a gift order. When the value of the "isPslipRequired" field is true, a packing slip is required for the order.

getPackingSlip request

To return a packing slip, call the getPackingSlip operation and pass the following parameters:

Path parameters:

Name Description Required
purchaseOrderNumber The purchaseOrderNumber for the packing slip you want.

Type: string

Yes

Request example

GET https://sellingpartnerapi-na.amazon.com /vendor/directFulfillment/shipping/2021-12-28/packingSlips/UkP3YkKDr

getPackingSlip response

A successful response includes the following:

Name Description Required
purchaseOrderNumber Purchase order number of the shipment.

Type: string

Yes
content

A Base64encoded string of the packing slip PDF.

Type: string

Yes
contentType

The format of the file such as PDF, JPEG etc.

Type: enum ( ContentType )

No

Response example

{
  "purchaseOrderNumber": "UvgABdBjQ",
  "content": "base64 encoded string",
  "contentType": "application/pdf"
}

Get customer invoices

The getCustomerInvoices operation returns customer invoices for all purchase orders which meet the filter criteria you specify. The use of this API is mandatory only in the India region and not required in any other region. Amazon recommends that vendors check for customer invoices at least once per hour during business hours. Depending on your business volume, you may choose to check more frequently. You can get up to 100 customer invoices in one API call. If there are more than 100 customer invoices you can use the nextToken value as a parameter in the next request to get the next set of customer invoices.

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.

The following diagram shows the integration workflow when retrieving customer invoices:

Direct Fulfillment integration workflow when retrieving customer invoicesDirect Fulfillment integration workflow when retrieving customer invoices

getCustomerInvoices request

To return customer invoices, call the getCustomerInvoices operation and pass the following parameters:

Query parameters:

Name Description Required
shipFromPartyId The vendor warehouseId from which the order will be fulfilled. If not specified, the result will contain orders for all warehouses.

Type: string

No
limit The limit to the number of records returned.

Type: integer

No
createdAfter Orders that became available after this date and time will be included in the result. Must be in ISO-8601 date/time format.

Type: string (date-time)

Yes
createdBefore Orders that became available before this date and time will be included in the result. Must be in ISO-8601 date/time format.

Type: string (date-time)

Yes
sortOrder Sort ASC or DESC by order creation date.

Type: enum ( SortOrder )

No
nextToken Used for pagination when there are more ship labels than the specified result size limit. The token value is returned in the previous API call.

Type: string

No

Request example

GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/2021-12-28/customerInvoices?limit=2&createdAfter=2020-02-15T14:00:00-08:00&createdBefore=2020-02-20T00:00:00-08:00&sortOrder=DESC

getCustomerInvoices response

A successful response includes the following:

Name Description Required
pagination If more than 100 customer invoices are returned, nextToken is returned in the response for pagination.

Type: Pagination

No
customerInvoices List of customer invoices.

Type: < CustomerInvoice > array

No

Response example

{
  "pagination": {
    "nextToken": "MDAwMDAwMDAwMQ=="
  },
  "customerInvoices": [
    {
      "purchaseOrderNumber": "PO98676856",
      "content": "base 64 content goes here"
    }
  ]
}

Get customer invoice

The getCustomerInvoice operation returns information about the customer invoice that you specify using the purchase order number. The response includes complete customer invoice information for that purchase order.

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.

You can also use this API to get details for any customer invoice (in the time range of 7 days from a rolling window of the last 6 months, after the vendor went live on the API).

The following diagram shows the integration workflow for returning a customer invoice:

Direct Fulfillment integration workflow for retrieving a customer invoiceDirect Fulfillment integration workflow for retrieving a customer invoice

Business requirements

  • What kind of customer invoices are available to download?

The customer invoice is a PDF file which is encoded in binary64 string format. All purchase orders for the India region should have a customer invoice created which should be sent with the shipment.

Country specific business requirements

Only India region needs to use the customer invoice API.

getCustomerInvoice request

To return a customer invoice, call the getCustomerInvoice operation and pass the following parameters:

Path parameters:

Name Description Required
purchaseOrderNumber Purchase order number of the shipment for which to return the invoice.

Type: string

Yes

Request example

GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/2021-12-28/shippingLabels/2JK3S9VC

getCustomerInvoice response

A successful response includes the following:

Name Description Required
purchaseOrderNumber The purchase order number for this order.

Type: string

Yes
content The Base64-encoded customer invoice.

Type: string

Yes

Response example

{
  "purchaseOrderNumber": "PO98676856",
  "content": "base 64 encoded string"
}

Did this page help you?