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.

API Version: v1

What is the Direct Fulfillment Payments API?

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:

OperationHTTP MethodPathDescription
submitInvoicePOST/vendor/directFulfillment/payments/v1/invoicesSubmits 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 to Amazon. Otherwise the invoice will be rejected. An invoice with correct information will be processed by Amazon without any human interaction, which means that the vendor receives payment more quickly. Invoices with incorrect information will be rejected in Amazon's payee system, so sending correct information is very important. See the business requirements section to learn how to create invoices with correct information.

Parallel testing of invoice submission

Vendors need to complete parallel testing with our payments system before they can start using the submitInvoice operation for payment processing. When vendors begin sending their invoices using the API, the parallel testing phase begins. During the parallel testing phase, vendors send both paper and API invoices for all orders shipped. Vendors are required to parallel test until the content of at least 5 to 10 EDI invoice files are validated. Parallel testing is conducted with production POs and invoices. The Amazon API team will contact you when parallel testing is complete, or if there are any content discrepancies in your invoices. When a vendor receives an email saying parallel testing is complete, they no longer need to send paper invoices. From that moment on they can process their payments by sending their invoices using the 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 once submitted. 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:

Direct Fulfillment 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 cancelled 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.

Payment terms sent in an invoice should match the payment terms agreed upon with the Amazon buyer.

Item product identifier should 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, etc.).

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 Amazon ID or warehouse code and address of the party to which items will be shipped. Amazon ID or warehouse code and address of the party to which items will be shipped.
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 and pass the following parameter:

Body parameter:

Name Description Required
invoices The request schema for the submitInvoice operation.

Type: < InvoiceDetail > array

Yes

Request example:

POST https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/payments/v1/invoices
{
  "invoiceNumber": "0092590411",
  "invoiceDate": "2020-03-13T11:16:24Z",
  "remitToParty": {
    "partyId": "YourVendorCode",
    "address": {
      "name": "Jane Doe",
      "addressLine1": "123 Any Street",
      "addressLine2": "123 Any Street",
      "addressLine3": "123 Any Street",
      "city": "Any Town",
      "county": "Schwabing",
      "district": "München",
      "stateOrRegion": "Bayern",
      "postalCode": "DEPostCode",
      "countryCode": "DE"
    },
    "taxRegistrationDetails": [
      {
        "taxRegistrationType": "VAT",
        "taxRegistrationNumber": "DE123456789"
      }
    ]
  },
  "shipFromParty": {
    "partyId": "ABCD"
  },
  "billToParty": {
    "partyId": "5450534005838",
    "address": {
      "name": "John Doe",
      "addressLine1": "100 Main Street",
      "city": "Anytown",
      "county": "Schwabing",
      "district": "München",
      "stateOrRegion": "Bayern",
      "postalCode": "80807",
      "countryCode": "DE"
    },
    "taxRegistrationDetails": [
      {
        "taxRegistrationType": "VAT",
        "taxRegistrationNumber": "DE814584193",
        "taxRegistrationAddress": {
          "name": "John Doe",
          "addressLine1": "100 Main Street",
          "city": "Anytown",
          "postalCode": "80807",
          "countryCode": "DE"
        },
        "taxRegistrationMessage": "txmessage"
      }
    ]
  },
  "shipToCountryCode": "DE",
  "paymentTermsCode": "Basic",
  "invoiceTotal": {
    "currencyCode": "EUR",
    "amount": "1428.00"
  },
  "taxTotals": [
    {
      "taxType": "CGST",
      "taxRate": "0.19",
      "taxAmount": {
        "currencyCode": "EUR",
        "amount": "228.00"
      },
      "taxableAmount": {
        "currencyCode": "EUR",
        "amount": "1200.00"
      }
    }
  ],
  "items": [
    {
      "itemSequenceNumber": "1",
      "buyerProductIdentifier": "B00IVLAABC",
      "invoicedQuantity": {
        "amount": 1,
        "unitOfMeasure": "Each"
      },
      "netCost": {
        "currencyCode": "EUR",
        "amount": "1200.00"
      },
      "purchaseOrderNumber": "D3rC3KTxG",
      "vendorOrderNumber": "0092590411",
      "hsnCode": "76.06.92.99.00",
      "taxDetails": [
        {
          "taxType": "CGST",
          "taxRate": "0.19",
          "taxAmount": {
            "currencyCode": "EUR",
            "amount": "228.00"
          },
          "taxableAmount": {
            "currencyCode": "EUR",
            "amount": "1200.00"
          }
        }
      ]
    }
  ]
}

submitInvoice Response

A successful response includes the following:

Name Description Required
transactionId GUID to identify this transaction. This value can be used with the Transaction Status API to return the status of this transaction.

Type: string

No

Response example:

{
  "transactionId": "20190905010908-8a3b6901-ef20-412f-9270-21c021796605"
}