Vendor Direct Fulfillment Payments API v1 Use Case Guide
How to help vendors in the direct fulfillment (DF) program use the Payments API to manage their direct fulfillment operations.
Vendors can use the Direct Fulfillment Payments API to exchange payment related documents with Amazon. The submitInvoice operation allows vendors to send vendor invoices to Amazon for confirmed and shipped orders.
The following operations are included in the Payments API:
| Operation | HTTP method | Path | Description |
|---|---|---|---|
submitInvoice | POST | /vendor/directFulfillment/payments/v1/invoices | Submits one or more invoices for a vendor's direct fulfillment orders. |
submitInvoice
The submitInvoice operation allows vendors to submit vendor invoices to request payment from Amazon for items shipped. Using this API, vendors can submit multiple invoices in a single API call.
Items should be invoiced only after they are confirmed and shipped. Otherwise, the invoice is rejected. An invoice with correct information is processed by Amazon without any human interaction, which means that the vendor receives payment more quickly. Invoices with incorrect information are rejected in Amazon's payee system. To learn how to create invoices with correct information, refer to the business requirements section.
Parallel testing of invoice submission
After you complete the API invoice integration, our Accounts Payable (AP) department requires you to send one successful API invoice in production before considering you as live. If there are any issues with your initial production invoice, our AP team will contact you. After the API invoice is integrated into production, you must send invoices via API only. If you want to return to using just the Vendor Central option, contact us to update your account. Before finalizing your API invoice integration, submit all invoices with a "Non-submitted" status in your account under the Payments tab in the Direct Fulfillment invoices section. Existing invoices with the "Non-submitted" status might be rejected and not paid if sent via API.
Verification of successfully submitted Invoices
The Transaction Status API doesn't show the actual status of invoice processing, it only shows the status of the semantic validations of the submitted invoices. Vendors can verify the actual status of the original/updated version of the invoices via Vendor Central > Payments > Direct Fulfillment Invoices. For more information on how to use the Transaction Status API, refer to the business use case documentation for Transaction Status. Allow the system to take up to 15 minutes to show the original/updated version after submission. If Vendor Central is not showing the correct values for the updated invoice, open a Contact Us case in Vendor Central.
The following diagram shows the integration workflow for submitting invoices for direct fulfillment confirmed and shipped orders:
Business requirements
Invoice numbers must be unique, and they should never be reused (even after one year).
If an invoice sent using the API has failed due to incorrect data, but a paper invoice has the correct data, then the vendor should update the invoice through the API with the correct data using the same Invoice ID.
If an invoice has incorrect data (both paper and API) then the invoice is canceled and a new invoice should be sent with a new Invoice ID.
An invoice with a total amount = 0 should not 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. For a complete list of Amazon bill-to party addresses and JSON code examples, refer to SP-API Bill-to Party Addresses. If you do not know the Amazon Tax ID for a bill-to location, go to Vendor Central and from the Support page, select the Contact Us button to create a case.
Payment terms sent in an invoice should match the payment terms agreed upon with the Amazon buyer.
Item product identifier must match the order item product identifier that was sent to the vendor in the matching purchase order.
The invoice total amount should be equal to the total sum of the items, charges, and allowances.
The total of the tax amount for each line level must be equal to the total of the tax amount at the header level.
The invoice total quantity should match the sum of the quantity of all items.
Every different charge and allowance must be itemized on the header level (for example, freight charge, package charge, small ordering charge).
Country-specific business requirements
Invoices for Direct Fulfillment are not supported in India via the API.
| Functionality | India | Europe | North America |
|---|---|---|---|
| Invoice type | Not supported. | Invoice type should always be Invoice. | Invoice type should always be Invoice. |
| Date | Not supported. | Must be "now" or before. | Must be "now" or before. |
| HSN number | Not supported. | Not used. | Not used. |
| Tax type at line and header level | Not supported. | Tax type to be sent. | Not used. |
| Tax registration number | Not supported. | VAT number. | VAT number. |
| Tax details at line and header level | Not supported. | If multiple taxes are applicable for an item, the Tax details section must be sent multiple times with the appropriate tax type for that item. The same applies to the total amount of the invoice. There is also an additional tax type called "DomesticVAT", which can be used to submit the tax amount in the local currency. In order to process the Domestic VAT you must use the same TaxRate used on tax Type "VAT". | If multiple taxes are applicable for an item, the Tax details section must be sent multiple times with the appropriate tax type for that item. The same applies to the total amount of the invoice. |
| Remit-to party | Not supported. | Tax and address details of the party (vendor) who will be receiving payment for the shipped items. This is required. | Tax and address details of the party (vendor) who will be receiving payment for the shipped items. This is required. |
| Ship-from party | Not supported. | Vendor code or warehouse code and address of the party from where items will be shipped. | Vendor code or warehouse code and address of the party from where items will be shipped. |
| Ship-to party | Not supported. | Ship To Party is the DF warehouse code. | Ship To Party is the DF warehouse code. |
| Bill-to party | Not supported. | Tax and Address details of the party (Amazon) who will be billed for shipped items. This field is required. | Tax and Address details of the party (Amazon) who will be billed for shipped items. This field is required. |
| Amazon Product Identifier and External Product Identifier | Not supported. | At least one of those values is required. The identifier must be the same as what is received in the order. | At least one of those values is required. The identifier must be the same as what is received in the order. |
| Net cost | Not supported. | This field is required. | This field is required. |
| Purchase order number | Not supported. | One invoice can have information for multiple orders. The PO number should be sent accordingly for different line items. Required. | One invoice can have information for multiple orders. The PO number should be sent accordingly for different line items. Required. |
| Additional details | Not supported. | This field is used when the selling party has to submit additional details for special purposes. For example, in the case of Polish split payment invoices, the selling party must send in the detail "mechanizm podzielonej płatności" of type "SUR" and languageCode "PL". | Not used. |
referenceNumber | Not supported. | Not used. | Not used. |
submitInvoice request
To submit one or more invoices, call the submitInvoice operation.
Updated about 1 month ago