Vendor Direct Fulfillment Shipping API v1 Use Case Guide

API Version: v1

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, send shipment status updates, and retrieve customer invoices.

Note that customer invoices are specific to the India region.

The following operations are available:

submitShippingLabelRequest

The submitShippingLabelRequest operation allows vendors to 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 are available for download using the getShippingLabel operation.

Shipping label requests don't require a vendor SKU or an ASIN.

The submitShippingLabelRequest and corresponding getShippingLabels operations can be used to obtain shipping labels for your DF orders in PNG or ZPL format. The content of the label is a Base64 string. You must convert the Base64 string into a format that you support. By default, the label format is PNG. You can change the label format setting in Vendor Central under Warehouse Settings.

ZPL and PNG labels must be requested only on the day when the orders are due for shipping. Don't print any additional information, such as a warehouse ID or part ID, on the shipping label that you receive from Amazon.

⭐

Tip

The standard label size is 4 inches by 6 inches. Labels in ZPL format have 203 DPI. Amazon can't change the barcode size and cannot encode the tracking number on the label with a linear barcode instead of a 2D barcode.

Verification of successfully submitted shipping label requests

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

Shipping label request API integration workflow

The following diagram shows the 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.

submitShippingLabelRequest request

To request shipping labels, call the submitShippingLabelRequest operation. You can submit shipping label requests between the carrier pick-up time of the previous day of the expected ship date and the actual day of shipping. If you submit requests earlier, a label flip might occur. Requests might also fail if you reach the capacity limits on that day.

You can request shipping labels by providing only the required parameters, which are order ID, vendor code (sellingParty), and warehouse code (shipFromParty). Amazon gets the information about the items from the catalog. However, if you have custom information, such as in a multiple-box scenario, you must provide package data when you request shipping labels. In this case, package data is required so that the shipping labels correspond to the correct dimensions.

The amount of packedQuantity must match the total quantity of the items to ship, not the total quantity of the items packed in that container. The pieceNumber in the containers acts as a trigger for our system to produce multiple tracking numbers for the order. If the quantities don't match, our system returns a NOT_ALL_ITEMS_PRESENT error.

The following code shows an example of a submitShippingLabelRequest request that includes pieceNumber.

"containers": [
    {
        "containerIdentifier": "145267052",
        "packedItems": [
            {
                "itemSequenceNumber": 1,
                "pieceNumber": 1,
                "packedQuantity": {
                    "amount": 1,
                    "unitOfMeasure": "EA"
                }
            }
        ],
        "containerType": "carton",
        "weight": {
            "unitOfMeasure": "LB",
            "value": "51.79"
        },
        "dimensions": {
            "unitOfMeasure": "IN",
            "length": "30",
            "width": "40",
            "height": "30"
        }
    }
]

The following example shows an error message that's returned if the packed quantity doesn't match the total quantity of items.

[
  {
    "errorCode":"NOT_ALL_ITEMS_PRESENT",
    "errorStringId":"DF-ORDER-NOT-ALL-ITEMS-PRESENT-ERROR",
    "errorText":"Request Rejected: Order quantity does not match the shipped quantity. All items in the order must be provided.",
    "errorTokens": {
        "shipmentId":"MWRQMCdN2"
      },
    "actionStringId":"DF-ORDER- NOT-ALL-ITEMS-PRESENT-ACTION","actionText":"Ensure you add the correct quantity of shipped items to packages. For items - B084HNL8FH, the expected quantity is 2, but the provided quantity is 1.",
    "actionTokens": {
      "expectedQuantity":"2",
      "fnSku":"B084HNL8FH",
      "providedQuantity": "1"
    }
  }
]

If you include the containers array in a shipping label request, you must include valid dimensions and weight. Values cannot be 0, negative numbers, or non-numeric values. If you provide the package weight as a decimal value, our system rounds it up to the nearest integer.

If you don't include dimensions, the API returns the following error message.

"code": "INVALID_MESSAGE_PAYLOAD", "message": "Invalid input field Length.", "details": "Please correct the input and try again."

If you don't include the weight, the API returns the following error message.

"code": "INVALID_MESSAGE_PAYLOAD", "message": "Invalid input field PackageWeight.", "details": "Please correct the input and try again."

📘

Note

A shipping label request is validated against the item information in the Amazon catalog. If the package weight and dimensions differ from the catalog values, the API returns a NO_SHIP_METHOD_ASSIGNABLE error.

getShippingLabels

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 can 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.

📘

Restricted Data Token for authorization

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:

getShippingLabels request

To retrieve a list of shipping labels, call the getShippingLabels operation.

Get a 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.

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

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

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

Shipments that require multiple boxes

If the order requires more than one box, each label must be on the correct box because Amazon needs to know the dimensions and weights of each box to accurately assign shipping methods. In this case, you must assign unique parcel identifiers and pass the parcel identifiers in the containerIdentifier parameters of the shipping label request. The containerIdentifier parameters associate the shipping label with the correct package.

The value that you specify for containerIdentifier in the shipping label request is returned as packageIdentifier in the getShippingLabel response.

If you only ship one box for an order, you only need to include the purchase order number, the vendor code, and the warehouse code in the shipping label request.

The following code shows an example of a shipping label request.

{
    "sellingParty": {
        "partyId": "999US"
    },
    "shipFromParty": {
        "partyId": "ABCD",
        "containers": [
            {
                "containerIdentifier": "145267052",
                "packedItems": [
                    {
                        "itemSequenceNumber": 1,
                        "pieceNumber": 1,
                        "packedQuantity": {
                            "amount": 1,
                            "unitOfMeasure": "EA"
                        }
                    }
                ],
                "containerType": "carton",
                "weight": {
                    "unitOfMeasure": "LB",
                    "value": "51.79"
                },
                "dimensions": {
                    "unitOfMeasure": "IN",
                    "length": "30",
                    "width": "40",
                    "height": "30"
                }
            }
        ]
    }
}

The following code shows an example of a shipping label response.

{
    "labelData": [
        {
            "shipMethod": "AMZL_US_SH",
            "packageIdentifier": "111",
            "trackingNumber": "TBA000123456",
            "content": "Base64EncodedLabelData"
        },
        {
            "shipMethod": "AMZL_US_SH",
            "packageIdentifier": "145267052",
            "trackingNumber": "TBA000123457",
            "content": "Base64EncodedLabelData"
        }
    ],
    "sellingParty": {
        "partyId": "999US"
    },
    "labelFormat": "PNG",
    "purchaseOrderNumber": "12345",
    "shipFromParty": {
        "partyId": "ABCD"
    }
}

getShippingLabel request

To request a shipping label, call the getShippingLabel operation.

Amazon ignores any tracking number that you specify in the shipping label request. Amazon generates the tracking number and returns it in the API response. If you specify container details in the request, the shipping label includes the package ID.

submitShipmentConfirmations

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 through Vendor Central > Orders > Direct Fulfillment Orders or using the Direct Fulfillment Transaction Status API. Allow the system up to 10 min to determine the status after submission. 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:

To avoid common errors with shipment confirmations:

• Use the Direct Fulfillment Transaction Status API to confirm the shipment of an order within four hours after the order ships from your warehouse.
• For floor-denied shipments, set the shipmentStatus parameter to FLOOR_DENIAL.
• Include all the purchase order line items in the shipment confirmation. Partial order fulfillment isn't allowed. If any line items aren't available, reject the order as a floor denial.
• Set the itemSequenceNumber parameter for an item to the value that it has in the order message.
• You must provide buyerProductIdentifier or vendorProductIdentifier in the shipment confirmation. You must send the same value as the purchase order specifies.
• For Vendor-Own-Carrier (VOC) vendors, you must include the scacCode parameter.
• If Amazon provides the shipping label, the container details are optional because Amazon has access to the package information. You must submit the items details.

Business requirements

You must use this API to confirm shipment of an order within four 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 must be present in the shipment confirmation. Partial order fulfillment is not allowed. Vendors must reject the entire order as floor denial if any items or units can not be fulfilled.

The itemSequenceNumber for an item must 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.

submitShipmentConfirmations request

To submit shipment confirmations, call the submitShipmentConfirmations operation.

submitShipmentStatusUpdates

❗

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 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 is then forwarded to Amazon customers on the Your Orders page and thus improves 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 through Vendor Central > Orders > Direct Fulfillment Orders or by using the Direct Fulfillment Transaction Status API. Allow the system up to 10 min to determine the status after submission. 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:

Business requirements

You must use this API only if you are a VOC (Vendor Own Carrier) vendor, meaning you use your own carrier to transport the shipment to the customer.

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

The trackingNumber in the shipment status API must match 100% with the trackingNumber provided in the shipment confirmation, otherwise shipment status update fails.

One Shipment Status Update API call must 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 must send shipment status whenever possible following the Amazon Shipment Status guidelines.

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

Additional Fields Explanation

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:

submitShipmentStatusUpdates request

To submit shipment status updates, call the submitShipmentStatusUpdates operation.

getPackingSlips

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.

📘

Restricted Data Token for authorization

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 must 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 can 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:

getPackingSlips request

To retrieve packing slips, call the getPackingSlips operation.

getPackingSlip

The getPackingSlip operation returns information about the specific packing slip that you specify using the purchase order number. The response includes a base64 encoded string of the packing slip. The content type is always "application/pdf".

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

getPackingSlip request

To return a packing slip, call the getPackingSlip operation.

getCustomerInvoices

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 can 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:

getCustomerInvoices request

To return customer invoices, call the getCustomerInvoices operation.

getCustomerInvoice

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.

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

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

Country-specific business requirements

Only the India region must use the customer invoice API.

getCustomerInvoice request

To return a customer invoice, call the getCustomerInvoice operation.