Vendor Direct Fulfillment FAQ
SP-API vendor direct fulfillment frequently asked questions.
Order acknowledgements
Can I use the submitAcknowledgement
operation to increase the quantity that I submitted in the original purchase order?
submitAcknowledgement
operation to increase the quantity that I submitted in the original purchase order?Select to expand the answer.
No. You can't specify a higher quantity in the order acknowledgment than the quantity that you submitted in the purchase order.
Must I send an order acknowledgment for each purchase order?
Select to expand the answer.
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.
Must I specify every purchase order line item in the corresponding order acknowledgment?
Select to expand the answer.
Yes. This information is required to update the order status.
How should I report invalid items on an order when I submit an order acknowledgment?
Select to expand the answer.
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.
Must I return the same product identifier in the order acknowledgment that I received in the order transaction?
Select to expand the answer.
Yes. Acknowledgments must return exactly the same product identifier that the purchase order specifies.
Must I provide an order acknowledgement code for all line items?
Select to expand the answer.
Yes. You must provide an acknowledgement code so that we can update the status of the order.
What is the policy on partial shipments? How should I report partial shipments when I submit an order acknowledgment?
Select to expand the answer.
Partial shipments aren't allowed. You must either confirm or reject the full order.
Order changes
Can I change an order by using the Vendor Direct Fulfillment Orders API?
Select to expand the answer.
No. You can't use the Vendor Direct Fulfillment Orders API to change an order.
Shipment confirmations
How can I avoid errors when I submit shipment confirmations?
Select to expand the answer.
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 toFLOOR_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
orvendorProductIdentifier
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 theitems
details.
Packing slips
Must I include a packing slip for all orders?
Select to expand the answer.
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 istrue
.
Invoices
What is the format of a customer invoice?
Select to expand the answer.
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.
Developer profile registration
Is developer profile registration required?
Select to expand the answer.
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.
Do I need to register separate application clients for retail and direct fulfillment shipping label API access?
Select to expand the answer.
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.
My Vendor Central account has two vendor codes in it. Must I submit a separate developer registration form for both vendor codes?
Select to expand the answer.
Yes. You must submit a separate developer registration form for each vendor code.
What role do I need for Vendor Direct Fulfillment API integration access?
Select to expand the answer.
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.
Can I edit answers in the developer registration form after I submit it?
Select to expand the answer.
No. After you submit the form, you must wait until your form is accepted or rejected to make changes.
What do I do if my developer registration form is denied?
Select to expand the answer.
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.
Authorization
How do I get my tokens and credentials to access the API?
Select to expand the answer.
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.
Does the LWA access token expire?
Select to expand the answer.
Yes. The access token is only valid for 60 minutes. You must get a new access token every time you call the API.Does the refresh token expire?
Select to expand the answer.
The refresh token is valid for one year. You can generate a refresh token at any time from your app in Vendor Central.
Why do I get an "Unauthorized - Access Denied" error (403 error code) in response to my API request after my developer profile is approved?
Select to expand the answer.
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
Shipping
By when should I ship an order?
Select to expand the answer.
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.
Shipping label creation by using the Vendor Direct Fulfillment Shipping API
Can I request a shipping label for a direct fulfillment order before I acknowledge the order?
Select to expand the answer.
No. You must acknowledge the order before you submit the shipping label request.
What API calls are required for shipping label integration?
Select to expand the answer.
Make one synchronous API call to the createShippingLabels
operation per order.
Is the createShippingLabels
operation synchronous?
createShippingLabels
operation synchronous?Select to expand the answer.
Yes.What is the latency of the createShippingLabels
operation?
createShippingLabels
operation?Select to expand the answer.
The latency for the createShippingLabels
operation is between three and five seconds.
Can I call the createShippingLabels
operation in batches? What is the maximum batch size?
createShippingLabels
operation in batches? What is the maximum batch size?Select to expand the answer.
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.
When should I request shipping labels by using the API?
Select to expand the answer.
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.
Can I omit the container details when I create shipping labels by using the API?
Select to expand the answer.
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.
Can I send a partial shipping label request?
Select to expand the answer.
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.
For an order that has two items, can I send a shipping label request with package details for only one of the items?
Select to expand the answer.
No. You must include the package details for all the items in the purchase order. Partial shipments aren't supported.
For an order where one ASIN requires multiple containers, must the amount
of the packedQuantity
in each container of the shipping label request match the total quantity of shipped items?
amount
of the packedQuantity
in each container of the shipping label request match the total quantity of shipped items?Select to expand the answer.
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"
}
}
]
Must I include a vendor SKU and an ASIN in shipping label requests?
Select to expand the answer.
No. Shipping label requests don't require a vendor SKU or an ASIN.
How important is the item sequence number? Can I use my own sequence number in the shipping label request?
Select to expand the answer.
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.
Can I receive multiple labels if I submit a shipping label request without container details?
Select to expand the answer.
Yes. You can receive multiple labels if the ASIN is defined in the catalog as a multi-box item.
When a purchase order requires multiple boxes, does it matter which label I put on each box? If so, what is the unique package identifier that enables me to match each label to the correct box?
Select to expand the answer.
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"
}
}
Must I specify dimensions in my shipping label requests?
Select to expand the answer.
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."
Must I specify weights in my shipping label requests?
Select to expand the answer.
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."
Can I send 0
as the value for the weight
in a shipping label request?
0
as the value for the weight
in a shipping label request?Select to expand the answer.
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)."
Should the package weight and dimensions in the shipping label request match the item weight and dimensions in the Amazon catalog?
Select to expand the answer.
Yes. If they don't match, the API might return a NO_SHIP_METHOD_ASSIGNABLE
error.
Why doesn't the package weight that I provide in my shipping label request match the package weight on my shipping label?
Select to expand the answer.
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.
Is the Unit of Measure (UOM) on the shipping label request required?
Select to expand the answer.
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.
Does the shipping label include the tracking number that I provide in the shipping label request?
Select to expand the answer.
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.
Does the shipping label include the package ID that I provide in the shipping label request?
Select to expand the answer.
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.
What label formats can I download?
Select to expand the answer.
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.
Can I omit the package data or item data from a shipping label request?
Select to expand the answer.
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.
Why doesn't the getShippingLabels
operation return any shipping labels?
getShippingLabels
operation return any shipping labels?Select to expand the answer.
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.
What dots per inch (DPI) are available for shipping labels in ZPL format?
Select to expand the answer.
Labels in ZPL format have 203 DPI.
What is the standard label size?
Select to expand the answer.
The standard label size is 4" by 6".
Can I print additional information on the shipping label that I receive from Amazon?
Select to expand the answer.
No. Don't print any additional information, such as a warehouse ID or part ID, on the shipping label that you receive from Amazon.
Can Amazon resize the barcodes on the label?
Select to expand the answer.
No. Amazon can't change the barcode size.
Can Amazon encode the tracking number on the label with a linear barcode instead of a 2D barcode for Amazon shipping methods?
Select to expand the answer.
No.
How can I differentiate between Amazon Extra Large (AMXL) and Amazon Transportation Services (ATS) shipping labels?
Select to expand the answer.
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.
What are label flips and how can I avoid them?
Select to expand the answer.
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.
Advance shipping notice (ASN)
Can I request a shipping label after I submit an ASN?
Select to expand the answer.
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.
Can I request shipping labels more than once before submitting the ASN?
Select to expand the answer.
Yes. However, the label might flip to a different shipping method when you request a new label.
Which shipping method should I specify on the ASN when the actual shipping method differs from the shipping method on the original purchase order?
Select to expand the answer.
To avoid shipping method mismatches, always specify the actual shipping method on the ASN.
My shipping label image show a UPS tracking number even though the shipping method flipped from UPS to Landmark. What shipping method and tracking number should I send in the ASN?
Select to expand the answer.
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.
For a re-pack scenario, can I discard a label I already retrieved?
Select to expand the answer.
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.
Need more help?
For additional support, contact Selling Partner API Developer Support. For vendor applications, submit a support case in Vendor Central by navigating to Vendor Central > Support > Contact Us > API Integration.
Updated 23 days ago