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

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.

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"
}