Vendor Direct Fulfillment Payments API v1 Use Case Guide

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:

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. Refer to the business requirements section to learn how to create invoices with correct information.

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

Country specific business requirements

Invoices for Direct Fulfillment are not supported in India via the API.

submitInvoice request

To submit one or more invoices, call the submitInvoice operation and pass the following parameter:

Body parameter:

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:

Response example

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