VENDOR API FAQs

The purpose of this document is to provide guidance to Vendors on API Integration

related queries.

Table of Contents
REGISTRATION AND ACCESS ............................................................................................... 2
API ERRORS .................................................................................................................. 7
DIRECT FULFILLMENT API ............................................................................................... 11
Registration and Access

1. Who can help add vendor codes to my Vendor Central account?

If you use a single vendor group to manage all of your vendor codes, you can authorize
an application to access the data in that vendor group. To do this, register as a
developer using the credentials for the Vendor Central account associated with the
vendor group.

To be sure that your vendor group contains all of the vendor codes that you want your
application to access, check the vendor codes in your vendor group. If you need to, you
can add or remove vendor codes from your vendor group at any time.

To add or remove vendor codes from your vendor group:

1. Go to Vendor Central. See Vendor Central URLs for a list of URLs by country.
2. Sign in using the credentials for the Vendor Central account with the vendor
group for which you want to add or remove vendor codes.
3. Click the Support link at the top of the page.
4. On the Support page, click the Contact Us button.
5. On the Contact Amazon support page, click Settings and Account Management,
then choose Account Settings.
6. In the Settings and Account Management box, at the bottom, click Still need
help?.
7. Follow the instructions to contact Amazon support.

2. Is there an additional price for adopting Vendor APIs?

No, it is a free service and you can start Vendor API integration by following the steps
below:

Register as a developer
https://github.com/amzn/selling-partner-api-docs/blob/main/guides/en-US/developer-
guide/SellingPartnerApiDeveloperGuideForVendors.md#registering-as-a-developer

To register as a developer, you will need to create an AWS (Amazon Web Service)
account. IAM (Identity and Access Management) is a feature offered at no additional
charge. If you sign up for the free tier and the only AWS service you use is IAM, your
account should continue to be free.

You might incur charges after 12 months for the use of other AWS services by your
users, if you use any other AWS services.
You can reference the IAM Pricing FAQ here and the AWS Free tier info here which
includes information about which services always have free usage tiers / limits and
which ones have 12 month free trials.
https://aws.amazon.com/iam/faqs/?nc=sn&loc=5#Pricing
https://aws.amazon.com/free/

3. Do I need to register separate application clients for Retail and DF (Direct

Fulfillment) API access?

No. API integration is based on access to specific roles. You can create one application
client and add the required roles to have access to the APIs. So one application can have
both the roles if you need access to both Retail and DF APIs.

4. What can I do if my developer profile is not approved?

You can appeal the decision via a support case with our vetting team, and they will
provide insight on the missing details or any relevant changes that the submission needs
to have to get the application approved.

5. I have multiple vendor groups, do I need to submit a developer profile for all
Vendor groups?

Yes. If you use multiple vendor groups to manage your vendor codes, for Selling Partner
API integrations we recommend that you either 1) Create a new vendor group
containing all of the vendor codes you need, or 2) Choose an existing vendor group and
add the vendor codes that you need. You can add or remove vendor codes in a vendor
group at any time. However once you have registered as a developer, you cannot
change the vendor group associated with that developer. If you want to maintain
separate API integrations for different businesses, you can. To do this, register as a
developer separately for each vendor group that you want to access. Then you can
develop separate API integrations with each registered developer.

6. Where can I find documentation related to Vendor API?

Navigate to the “Integration” > “API Integration” section of your Vendor Central
account, and click on the “API Documentation” hyperlink to download the
documentation.

The “Getting Started” page under the “Integration” menu item also has additional
details including FAQs on EDI vs API usage.
7. What are the available APIs and Operations for Vendor API?

Offered Vendor APIs

The current API offerings include APIs for following business functions:

For Direct Fulfillment:

Orders: The Orders API will enable vendors to get purchase orders from Amazon and
Acknowledge orders.
Shipping: The Shipping API will enable vendors to send shipment confirmations, request
and download shipping labels, download customer invoices [IN only], download packing
slips, send shipment status updates for VOC [vendor own carrier].
Payments: The Payments API will enable vendors to submit invoices.
Transactions: The Transactions API will provide vendors visibility on processing status of
Order Acknowledgement, Shipment Confirmation, Shipping Label Request, Inventory
Feed.
Inventory: The Transactions API will let vendors submit changes to their inventory levels
of existing items. Listing of new items is not supported via this API.

For Retail:

Orders: Using the Orders API, vendors can receive purchase orders, updates to the
orders and send order acknowledgements
Shipment: Vendors can use the Shipment API to send shipment confirmations to
Amazon.
Payments: Vendors can use the Payments APIs to submit invoices to Amazon.
Transaction: Vendors can use these this API to check the transaction status of the
shipment confirmations, purchase order acknowledgments.

8. What role do I need for the API integration access?

For Retail API access, you must have the Amazon Fulfillment role added to your
application client.
For Direct Fulfillment API access, must have the Direct-to-Consumer Shipping role
added.
(Note: Direct-to-Consumer Shipping is a restricted role. Restricted roles allow access to
Personally Identifiable Information (PII) about Amazon Buyers so you will be required to
provide additional information about your data use and security controls.)

9. What should be the correct IAM ARN (Amazon Resource Name) value to be added
during registering my application?

When registering your application, the IAM ARN that you provide must be for the IAM
entity to which you attached the IAM policy from Step 3. Create an IAM policy.

In this workflow, that IAM entity is the IAM role from Step 4. Create an IAM role. If you
register your application using your IAM user, be sure that the IAM policy is attached to
it. Otherwise your calls to the Selling Partner API will fail.

We recommend registering your application using an IAM role, as shown in this

workflow, to help you better control access to your AWS resources.

The steps can be followed on the next link:

Register your application

https://github.com/amzn/selling-partner-api-docs/blob/main/guides/en-US/developer-
guide/SellingPartnerApiDeveloperGuideForVendors.md#step-6-register-your-
application

10. What are the regions in which Vendor API is currently available?

Our vendor API integration features and support operations are only available the
following regions:

NA: (US, CA, MX)

EU: (ES, UK, FR, DE, IT)
India: (IN)
FE: (JP, AU, SG)

Please make sure to enable the API integration through the correct vendor code, region
and country since this is not yet open to all countries.

11. Is there a sandbox environment for Vendor API?

Yes. The Selling Partner API provides a sandbox environment that allows you to test
your applications without affecting production data or triggering real-world events.
Making sandbox calls to the Selling Partner API is identical to making production calls
except you direct the calls to the Selling Partner API sandbox endpoints.

The authorization and authentications models are the same for sandbox calls and
production calls. Calling the sandbox endpoints returns static, mocked responses for all
Selling Partner APIs. You can refer to these mocked responses in the Swagger model
JSON file for the API that you want to call. For more information you can refer to the
next link:

How to make a sandbox call to the Selling Partner API -

https://github.com/amzn/selling-partner-api-docs/blob/main/guides/en-US/developer-
guide/SellingPartnerApiDeveloperGuideForVendors.md#how-to-make-a-sandbox-call-
to-the-selling-partner-api

Selling Partner API sandbox endpoints -

https://github.com/amzn/selling-partner-api-docs/blob/main/guides/en-US/developer-
guide/SellingPartnerApiDeveloperGuideForVendors.md#selling-partner-api-sandbox-
endpoints

12. Is there a list of 3rd party providers for Vendor API?

Yes, we have included a list of third party developers in our Vendor Central
documentation:
https://m.media-amazon.com/images/G/01/RAPI-
P0/documentation/docs/Developer_Tools/APIDocs._TTH_.zip

13. Can Vendor API be integrated through EDI?

No, Vendor API is built on our Selling Partner API (SP-API) and the registration process
and integration can be viewed on the following link:

What is the Selling Partner API?

https://github.com/amzn/selling-partner-api-docs/blob/main/guides/developer-
guide/SellingPartnerApiDeveloperGuideForVendors.md#what-is-the-selling-partner-api

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

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

Refer to: “Connecting to the Selling Partner API” section in VendorDevGuide_xx.pdf

under "Authentication" folder
API Errors

1. Why am I getting an Unauthorized - Access Denied error (403 error code) for my API
request after completing registration successfully?

If you are getting an Access Denied error for your API request, please refer to the
troubleshooting tips below –

1. Check the API operation you are making a call to and verify if your application
has access to that API. To verify role permissions, navigate to Integration > API
Integration and click on Edit App button to view the App registration form. The
check boxes selected will tell you what role you have added to your application.

2. If you are missing the role you need for the API access, navigate to Developer
Profile to ensure you requested access to that role. Please note that Direct
 Fulfillment requires a restricted role and you may need to re-submit your
Developer Profile for access to it. Once the role is added, re-authorize your
application i.e. Generate a new LWA Refresh token to make valid API calls.

3. If you have all the correct roles and permissions added, verify your IAM ARN
added to the application (see screenshot). The IAM ARN added should be the
one to which the IAM policy was attached during registration process (Step 3)
a. If IAM ARN is IAM Role, ensure that IAM policy is attached to the Role.
b. If IAM ARN is IAM User, ensure that IAM policy is attached to the User
and there is no IAM Role created.

4. If the IAM ARN added to the application is IAM Role, you need to use AWS STS to
request temporary credentials and a session token which is to be added to your
request along with the LWA Access Token.
When you send HTTP requests to the Selling Partner API, you sign the requests so that
Amazon can identify who sent them. You sign requests using your AWS access keys,
which consists of an access key ID and a secret access key. If you registered your
application with IAM role, you need to use AWS Security Token Service (AWS STS) to
request temporary AWS access keys to sign your requests.

For more information about using AWS STS and the AWS SDKs that can help with your
implementation, see Requesting temporary security credentials in the AWS
documentation.

If the error persists, please log a support case with Amazon to further troubleshoot
the issue. Please include below details in the support case -

o Application ID
o Request ID with timestamp
o API operation (please specify if it is a sandbox request)
o Error response received

2. Why am I getting a 500 error when making request to sandbox endpoint?

The Selling Partner API sandbox works like many mocking frameworks, in that it uses
pattern matching to return a specified response when the specified parameters are
present. A developer receives a response defined in the x-amazon-spds-sandbox-
behaviors object when they send a request that matches the specified parameters.

If the request sent to the sandbox endpoint does not match the parameter values in the
x-amazon-spds-sandbox-behaviors object, you will receive a "500 Internal Server Error"
in the response. You must be sure to send the request with the exact values specified in
the model.

If the API requires any parameters that are not specified in the x-amazon-spds-sandbox-
behaviors object, the sandbox provides the response regardless of the parameter values
in the request, as long as the request is valid.

How to make a sandbox call to the Selling Partner API -

https://github.com/amzn/selling-partner-api-docs/blob/main/guides/en-US/developer-
guide/SellingPartnerApiDeveloperGuideForVendors.md#how-to-make-a-sandbox-call-
to-the-selling-partner-api

3. Is there a way to access postman collection with example directly from Vendor
Central, do we need to open a case to request access for them?

For postman collection you need to open a case for now but in future we will make it
available in Vendor Central from where you can directly download it.

4. Can we test using our production data before going live?

Testing is not available with vendors’ production data as of now. Vendors can test in
sandbox environment using mock request and responses. Sandbox does syntax and
semantic validations but we do not perform business validations in sandbox testing.

How to make a sandbox call to the Selling Partner API -

https://github.com/amzn/selling-partner-api-docs/blob/main/guides/en-US/developer-
guide/SellingPartnerApiDeveloperGuideForVendors.md#how-to-make-a-sandbox-call-
to-the-selling-partner-api
Direct Fulfillment API

1. I am getting a “Processing” message for the Transactions API Call, what can I do?

The transaction status will be supported for following API operations:

• Acknowledge Order
• Submit Shipment Confirmations
• Submit Shipment Status Updates
• Shipping Label Request
• Inventory Feed
If transaction status is “Processing” and not updated to “Failure” or “Success” after 5
minutes, that indicates transaction not successfully completed in our system. The
“Success” status will be there if the transaction is successful and an error code will be
provided for “Failure”.

You can’t use this API for “Invoice” messages as they are not supported to check and
status will be always “Processing”.

For Shipping Label Requests, if the transaction is failed with a reason code like “Internal
server error” which are terminal errors, you must create a “contact us” case to get the
cause investigated. This generally happens due to operational constraints.

2. I am getting an error message for the “Submit Invoices” operation call, what can I
do?

The operation parameters need to be filled out correctly, these are some points that
you need to take into consideration when filling the API call:

- Invoice numbers must be unique and they should never be reused (even after one
year).
- If an invoice sent by API has failed due to incorrect data but paper invoice has the
correct data then vendor should update it through API with correct data under same
Invoice ID.
- If invoice has wrong data (both paper and API) then invoice is cancelled and new
invoice should be sent with new Invoice ID.
- No invoice with total amount "0" should be sent, as this would cause the invoice to fail.
- Amazon requires the full address details in the address segments for tax compliance
reasons. This is especially important for the bill-to party. For this segment the Amazon
Payee system requires an exact match.
- Payment terms sent in invoice should match the payment terms agreed upon with the
Amazon buyer
- Item product identifier should match the order item product identifier that were sent
to the vendor in matching Purchase Order. Invoice total amount should be equal to the
total sum of the items, charges and allowances.
- Total of tax amount for each line level must be equal to total of tax amount at header
level.
- Invoice total quantity should match the sum of the quantity of all items. Each different
charges and allowance has to be itemized on the header level.

If one of these parameters are missing or filled out incorrectly, this will lead the API call
to retrieve incorrect details, please make sure to provide the required information when
submitting the operation.

3. Can a vendor increase the original quantity submitted in the purchase order using
the Order Acknowledgment API?

No, Amazon does not allow the vendor to send a higher quantity in the
acknowledgment than what was submitted in the purchase order.

4. Is it a requirement to send an order acknowledgment for each purchase order?

Yes, in order to update the status of an order in the Amazon system correctly, Amazon
requires PO confirmation using the API or Vendor Central. If you are unable to meet our
order acknowledgement requirements using the API, you must confirm your POs using
Vendor Central. Please contact your Amazon business representative if you do not have
a Vendor Central account.

5. Is it a requirement to provide every PO line item in the corresponding order

acknowledgment?

Yes, so Amazon can update the order status correctly.

6. How should invalid items or details on an order be reported using the order
acknowledgment?

Do not process or ship an item that arrived with an invalid item number on the order.
Please return the invalid item number on the acknowledgment and acknowledge it with
the codes which are provided in the Direct Fulfillment User Guide.

7. Do I need to return the same product identifier in the acknowledgment that I

received in the orders transaction?

Acknowledgments must return exactly the same product identifier that were sent in the
purchase order.

8. Is it required to provide an acknowledgement code for all line items regardless of

status?
Yes, it is required so we can correctly update the status of the order. If the
acknowledgment code is omitted, the acknowledgment will be rejected in our EDI
system.

9. What is the policy on partial shipments? How should partial shipments be reported
when submitting an order acknowledgment?

Partial shipments are not allowed. Vendors need to either confirm or reject the full
order (fill or kill model).

10. I am having issues submitting shipment confirmations, what can I do?

Vendors can verify the status of their shipment confirmations via “Vendor Central
>Orders> Direct Fulfillment Orders” or using the Direct-fulfillment Transaction Status
API. Allow the system up to 10 min to see the status once submitted.

Here are some common errors a vendor might face when submitting this API call:

- 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, send “shipmentStatus” field value as “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.
- “itemSequenceNumber” for an item should be same as received in order message.
- Either “buyerProductIdentifier” or “vendorProductIdentifier” is mandatory to send in
the shipment confirmation. You need to send the same value as received in purchase
order.
- For vendor own carriers, sending “scacCode” is mandatory.
- If the shipment label is provided by Amazon, then container section is optional since
Amazon has access to the package information. Items section is mandatory to submit.

11. What kind of labels are available to download?

ZPL and PNG labels are supported. Vendor’s Label content is provided in base64 string
format so you can convert the string into desired label format. The choice of format of
label is with vendor and they decide this as part of on-boarding process into direct
fulfillment program. Please open a case with DF Operations team if you want to
change the format of label.

12. 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.
13. Are packing slips required for all orders?
Packing slip is required only if it is a Business to Business [B2B] order or a gift order.
“isPslipRequired” field from the Order message must be read and if it is true, Packing
slip is required for that order.

14. What kind of customer invoices are available to download?

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

15. Can the package/items data be omitted from Shipping label request?
Yes, Shipping lables can be requested by providing only the minimal 3 fields, order id,
vendor code [SellingParty] and warehouse code [shipFromParty]. Amazon will get the
information about items from catalogue in this order and create a shipping label. If
there is custom information like multi box scenario, then the package loop is mandatory
to request labels so they are created as per dimensions provided.

16. Shipping labels are not available when making the GET call?
Shipping labels must be created first by making a POST call with the information about
the order. Only if that request succeeds, a label will be available in the back end to
request via the GET call. Make sure the POST call is made first, the status is checked via
the transaction status API before trying to download a label via GET call.