Vendor Direct Fulfillment FAQ

No. You can't specify a higher quantity in the order acknowledgment than the quantity that you submitted in the purchase order.

Yes. To update the status of an order, you must confirm the purchase order by using the SP-API or Vendor Central. If you can't meet the order acknowledgement requirements by using the SP-API, you must confirm your purchase orders by using Vendor Central. If you don't have a Vendor Central account, contact your Amazon business representative.

Yes. This information is required to update the order status.

Return the invalid item number in the acknowledgment and use the appropriate order acknowledgement code. For a list of codes, refer to Business Requirements. Don't process or ship an item that arrives with an invalid item number on the order.

Yes. Acknowledgments must return exactly the same product identifier that the purchase order specifies.

Yes. You must provide an acknowledgement code so that we can update the status of the order.

Partial shipments aren't allowed. You must either confirm or reject the full order.

No. You can't use the Vendor Direct Fulfillment Orders API to change an order.

To verify the status of your shipment confirmations, you can use Vendor Central or the Direct Fulfillment Transaction Status API. Give the system up to ten minutes to update the status.

To avoid common errors, review the following information:

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

You must include a packing slip in the following cases:

• The order is a business-to-business (B2B) order or a gift order.
• The isPslipRequired parameter in the order message is true.

A customer invoice is a PDF file in binary64 string format. For the IN region, include a customer invoice with the shipment of all purchase orders.

Yes. Approval of your developer profile is required for you to use the Vendor Direct Fulfillment APIs. To integrate with the Vendor Direct Fulfillment APIs, you must submit your developer profile with the Direct to Consumer Shipping (Restricted) role when you register in Vendor Central. Our vetting team then performs the assessment. This assessment can take up to five business days. The outcome is either an approval or feedback on why the request is denied.

No. API integration is based on roles. To get access to the APIs, you can create one application client and add the required roles. If you need to use both the retail and direct fulfillment APIs, your application can have both roles.

Yes. You must submit a separate developer registration form for each vendor code.

To access the Vendor Direct Fulfillment API, you must have the Direct to Consumer Shipping (Restricted) role in your developer registration form. This role is restricted because it allows access to Personally Identifiable Information (PII) about Amazon buyers. As a result, you must provide additional information about your data use and security controls.

No. After you submit the form, you must wait until your form is accepted or rejected to make changes.

After you submit the developer registration form, our system automatically creates a case. It can take up to five business days for our vetting team to review your case and provide the outcome. If your case is approved, you can create an application in Vendor Central.

If your case is denied, you receive an explanatory email at the primary email address that you provided with the form. Review the comments from our vetting team. To understand the changes that you must implement, review Amazon's Data Protection Policy and Acceptable Use Policy. After you make the changes, you can resubmit the form.

After you create an application in Vendor Central, you must self-authorize your application to generate your Login with Amazon (LWA) refresh token. You can use this refresh token to generate the access token that is required to access the API.

The refresh token is valid for one year. You can generate a refresh token at any time from your app in Vendor Central.

If you get an access denied error for your API request, review the following troubleshooting tips:

• Verify that the account is in the same region as the endpoint in the request. Applications are global; seller accounts are not.
• Verify that your application has access to the API.
• After your developer registration form is approved, verify that you have access to the Direct to Consumer Shipping (Restricted) role.
• If the error persists, file a support case to Amazon. Include the following details in the support case:
  • Application ID
  • Request ID with timestamp
  • API operation (specify if it is a sandbox request)
  • Error response received

You must ship the order from the warehouse by the date specified in requiredShipDate. In contrast, the promisedDeliveryDate parameter is the date that we promised to deliver the order to the customer.

No. You must acknowledge the order before you submit the shipping label request.

Make one synchronous API call to the createShippingLabels operation per order.

The latency for the createShippingLabels operation is between three and five seconds.

Yes. You can submit requests to createShippingLabels in batches. You can also make multiple single-label or batch requests in parallel. A batch file can have shipping label requests for a maximum of 100 orders. To reduce label retrieval latency, keep the batch size to 10-15 requests.

For batches, you must use the submitShippingLabelRequest operation, which is asynchronous, and then call the getShippingLabel operation to get the generated shipping labels.

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.

The container details are only required for multi-box scenarios. You can omit the container details for single-box orders. You can request shipping labels for single-box orders by providing only the purchase order number, the vendor code (sellingParty), and the warehouse code (shipFromParty) in the request. In this case, Amazon generates the shipping label based on the item details in the catalog.

No. Partial shipping label requests are rejected. You must use one shipping label request to for all the items in the order, even if the items cannot fit in one box. If you can't submit all the items in the order in one shipping label request, you must cancel the order.

No. You must include the package details for all the items in the purchase order. Partial shipments aren't supported.

Yes. 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"
    }
  }
]

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

You must include an item sequence number if you include container details. The item sequence number for each item in the shipping label request must match the item sequence number that you receive in the purchase order.

Yes. You can receive multiple labels if the ASIN is defined in the catalog as a multi-box item.

Yes. 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"
    }
}

Yes. If you include the containers array in a shipping label request, you must include valid dimensions. 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."

Yes. If you include the containers array in the shipping label request, you must include a weight. 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."

No. The weight must be a valid value. If you use an invalid value, such as 0, the API returns the following error message.

"code": "PACKAGE_WEIGHT_NOT_VALID", "message": "Request Rejected: Order ID M4qxXXXX has invalid package weights", "details": "Please add valid weight for your package(s)."

Yes. If they don't match, the API might return a NO_SHIP_METHOD_ASSIGNABLE error.

If you provide the package weight as a decimal value, our system rounds it up to the nearest integer. If you require the package weights to match, send an integer value in your shipping label request. Amazon ships the package regardless of the weight on the label.

Yes. The UOM is required if you provide container details. The UOM must be standard and the dimensions and weights must represent actual measurements of the shipped packages. The UOM in PackedItem is a string.

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

The answer depends on whether you specify container details in the request. If you specify container details in the request, the shipping label includes the package ID.

Labels are available in ZPL and PNG formats. 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. If you want the label format to be ZPL, you can change the label format setting in Vendor Central under Warehouse Settings.

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

Before you can get shipping labels, you must create the labels. To create the labels, call the createShippingLabels operation. If that request succeeds, you can use the getShippingLabels operation to get the label. Before you call getShippingLabels to get the label, call the getTransactionStatus operation.

Labels in ZPL format have 203 DPI.

The standard label size is 4" by 6".

No. Don't print any additional information, such as a warehouse ID or part ID, on the shipping label that you receive from Amazon.

No. Amazon can't change the barcode size.

No.

If you use AMXL and AT shipping methods for the same warehouse, the AMXL Oversize and XL markers on the label help differentiate between AMXL and AT labels.

Label flips occur when the shipping method that is assigned during shipping label generation differs from the shipping method that is assigned during order creation.

Label flips are expected. During shipping label requests, our planning system might find a better shipping method than the shipping method that the purchase order originally assigned. However, you can greatly reduce the number of label flips by incorporating the following best practices into your processes:

• For single-package orders, don't include any container details in the body of shipping label creation request.
• Set sellingParty.partyId to the vendor code.
• Set shipFromParty.partyId to the warehouse ID.

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

{
    "shippingLabelRequests": {
        "sellingParty": {
            "partyId": "ExampleSellingPartyId"
        },
        "shipFromParty": {
            "partyId": "ExampleShipFromPartyId"
        }
    }
}

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

No. The ASN should reflect the actual shipping method. Therefore, you must generate the shipping label prior to the ASN process. Otherwise, the shipping label request is rejected.

Yes. However, the label might flip to a different shipping method when you request a new label.

To avoid shipping method mismatches, always specify the actual shipping method on the ASN.

In the ASN, you must provide the shipping method and tracking number that you receive in the shipping label from Amazon even if there is a UPS tracking number on the label. You can differentiate a standard UPS label from a Landmark-UPS label based on the presence or absence of a Landmark logo in the corner of the label.

This scenario is common. For example, you might see a UPS tracking number for a Landmark shipping method in multi-leg shipments that Landmark orchestrates.

Yes. You can discard the shipping label if you no longer require it. You can submit a new shipping label request and call the getShippingLabel operation to retrieve the new label. In general, however, try to avoid discarding labels. Discarding labels can result in carrier pick-up issues and might negatively impact your metrics.