Amazon Vendor Procurement Order Invoices
Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)
| Version | Date | Created / Updated | Notes |
|---|---|---|---|
| v1.0 | 09.02.2024 | Bogomil Pavlov | First publish |
| v1.1 | 10.06.2024 | Bogomil Pavlov | Change limit |
| v1.2 | 02.05.2025 | Bogomil Pavlov | Mapping Changes |
Through the Vendor Invoices API, we have the opportunity to exchange documents related to payments with Amazon. The Submit Invoices operation allows us to securely send vendor invoices to Amazon for orders that have been confirmed and shipped. The invoice submission is via API and we are not generating and sending an invoice but we are populating the invoice details in body of the request. We want to track the invoices using our current structure, fields and tables.
We will be submitting the invoices order per order The trigger for submitting an invoice will be: Order > Order Status = “Shipped” Amazon Account > Upload Vendor Invoices? = “yes” (New Control Flag) Amazon Account > Account Type = “Vendor” And there is no generated invoice for the order (no records in Invoices)
API: /vendor/payments/v1/invoices
Docs: https://developer-docs.amazon.com/sp-api/docs/vendor-invoices-api-v1-reference#submitinvoices
<v1.1>We want to push only 1 invoice in a single request.</v1.1>
Sample Request:
POST /vendor/payments/v1/invoices
Body:
{
"invoices":[
{
"invoiceType":"Invoice",
"id":"0136981234",
"date":"2019-07-24T21:17:59.821Z",
"remitToParty":{
"partyId":"XYZ12345",
"address":{
"name":"ANYCOMPANY MANUFACTURING",
"addressLine1":"123 ANY STREET",
"city":"ANYTOWN",
"stateOrRegion":"AZ",
"postalOrZipCode":"12345",
"countryCode":"USA"
},
"taxRegistrationDetails":[
{
"taxRegistrationType":"VAT",
"taxRegistrationNumber":"VENDORVATID"
}
]
},
"shipToParty":{
"partyId":"XYZ12345",
"address":{
"name":"ANYCOMPANY MANUFACTURING",
"addressLine1":"123 ANY STREET",
"city":"ANYTOWN",
"stateOrRegion":"AZ",
"countryCode":"USA"
}
},
"shipFromParty":{
"partyId":"XYZ12345",
"address":{
"name":"ANYCOMPANY MANUFACTURING",
"addressLine1":"123 ANY STREET",
"city":"ANYTOWN",
"stateOrRegion":"AZ",
"postalOrZipCode":"12345",
"countryCode":"USA"
}
},
"billToParty":{
"partyId":"XYZ12345",
"address":{
"name":"ANYCOMPANY MANUFACTURING",
"addressLine1":"123 ANY STREET",
"addressLine2":"",
"city":"ANYTOWN",
"stateOrRegion":"AZ",
"postalOrZipCode":"12345",
"countryCode":"USA"
},
"taxRegistrationDetails":[
{
"taxRegistrationType":"VAT",
"taxRegistrationNumber":"AMAZONVATNUMBER"
}
]
},
"paymentTerms":{
"type":"Basic",
"discountPercent":"5",
"discountDueDays":15,
"netDueDays":30
},
"invoiceTotal":{
"currencyCode":"INR",
"amount":"259678.39"
},
"taxDetails":[
{
"taxType":"SGST",
"taxRate":"9",
"taxAmount":{
"currencyCode":"INR",
"amount":"19697.98"
},
"taxableAmount":{
"currencyCode":"INR",
"amount":"218866.43"
}
},
{
"taxType":"CGST",
"taxRate":"9",
"taxAmount":{
"currencyCode":"INR",
"amount":"19697.98"
},
"taxableAmount":{
"currencyCode":"INR",
"amount":"218866.43"
}
}
],
"chargeDetails":[
{
"type":"Freight",
"description":"Freight Charges",
"chargeAmount":{
"currencyCode":"INR",
"amount":"1200.00"
},
"taxDetails":[
{
"taxType":"CGST",
"taxRate":"9",
"taxAmount":{
"currencyCode":"INR",
"amount":"108.00"
},
"taxableAmount":{
"currencyCode":"INR",
"amount":"1200.00"
}
},
{
"taxType":"SGST",
"taxRate":"9",
"taxAmount":{
"currencyCode":"INR",
"amount":"108.00"
},
"taxableAmount":{
"currencyCode":"INR",
"amount":"1200.00"
}
}
]
}
],
"items":[
{
"itemSequenceNumber":1,
"amazonProductIdentifier":"ABC123434",
"vendorProductIdentifier":"809281-5100",
"invoicedQuantity":{
"amount":2,
"unitOfMeasure":"Eaches"
},
"netCost":{
"currencyCode":"INR",
"amount":"21060.34"
},
"purchaseOrderNumber":"3DY3TK6T",
"hsnCode":"76.06.92.99.00",
"taxDetails":[
{
"taxType":"SGST",
"taxRate":"9",
"taxAmount":{
"currencyCode":"INR",
"amount":"1895.43"
},
"taxableAmount":{
"currencyCode":"INR",
"amount":"21060.34"
}
},
{
"taxType":"CGST",
"taxRate":"9",
"taxAmount":{
"currencyCode":"INR",
"amount":"1895.43"
},
"taxableAmount":{
"currencyCode":"INR",
"amount":"21060.34"
}
}
],
"chargeDetails":[
{
"type":"Freight",
"description":"Freight Charges",
"chargeAmount":{
"currencyCode":"INR",
"amount":"600.00"
}
}
]
},
{
"itemSequenceNumber":2,
"amazonProductIdentifier":"ABC123435",
"vendorProductIdentifier":"795000-0001",
"invoicedQuantity":{
"amount":3,
"unitOfMeasure":"Eaches"
},
"netCost":{
"currencyCode":"INR",
"amount":"58915.25"
},
"purchaseOrderNumber":"3DY3TK6T",
"taxDetails":[
{
"taxType":"SGST",
"taxRate":"9",
"taxAmount":{
"currencyCode":"INR",
"amount":"5302.37"
},
"taxableAmount":{
"currencyCode":"INR",
"amount":"58915.25"
}
},
{
"taxType":"CGST",
"taxRate":"9",
"taxAmount":{
"currencyCode":"INR",
"amount":"5302.37"
},
"taxableAmount":{
"currencyCode":"INR",
"amount":"58915.25"
}
}
],
"chargeDetails":[
{
"type":"Freight",
"description":"Freight Charges",
"chargeAmount":{
"currencyCode":"INR",
"amount":"600.00"
}
}
]
}
]
}
]
}Mapping: Please note everything with Hemi Field = N/A we exclude from the payload.
| Amazon Field | Required | Hemi Field | Comment | |||||
|---|---|---|---|---|---|---|---|---|
| invoices | ||||||||
| invoiceType | Yes | “Invoice” | Hardcoded as “Invoice” | |||||
| id | Yes | Order > Id | ||||||
| referenceNumber | No | |||||||
| date | Yes | We want to send the date now for the invoice date. | ||||||
| Defines a date and time according to ISO8601. | ||||||||
| remitToParty | Yes | |||||||
| partyId | Yes | Order Amazon >Purchase Order Selling Party | New field under new tab “Amazon Vendor” |
| Additional mapping will be introduced and we want to try and map Order Amazon >Purchase Order Selling Party against Seller > Vendor ID (new field) and if we have a match we want to get the address from the Seller and push it in the invoice. SInce this node is required if there is not match we want to return an error in order Error table | address | No | name | Yes | Seller > Name | addressLine1 | Yes | Seller >Street1 | If Seller >Street1 is missing try to get Seller >Street2 else return an error | addressLine2 | No | Seller >Street2 | addressLine3 | No | N/A | city | No | Seller >City | county | No | N/A | district | No | N/A | stateOrRegion | No | Seller > Country | postalOrZipCode | No | Seller >Postal Code | countryCode | Yes | Seller >Country 2 char code | phone | No | Seller >Phone | TaxRegistrationDetails | No | taxRegistrationType | Yes | N/A | taxRegistrationNumber | Yes | N/A | shipToParty | No | partyId | Yes | Order > Shipping Address ID | Additional mapping will be introduced here if for some reason we are not receiving the address in the payload we want to get it from a new table called “Amazon Delivery Locations” where we want to try and map Order > Shipping Address ID against Amazon Delivery Locations > Location Id and if we have a match we want to get the address from the Amazon Delivery Locations and store it in the order as Shipping Address. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| address | No | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| name | Yes | Order > Shipping Buyer Name |
OR Amazon Delivery Locations > Name | | | | | | addressLine1 | | | Yes | Order > Shipping Street 1 OR Amazon Delivery Locations >Street1 | | | | | | addressLine2 | | | No | Order > Shipping Street 2 OR Amazon Delivery Locations >Street2 | | | | | | addressLine3 | | | No | N/A | | | | | | city | | | No | Order > Shipping City OR Amazon Delivery Locations >City | | | | | | county | | | No | N/A | | | | | | district | | | No | N/A | | | | | | stateOrRegion | | | No | Order > Shipping State Province OR Amazon Delivery Locations > County | | | | | | postalOrZipCode | | | No | Order > Shipping Postal Code OR Amazon Delivery Locations >Postal Code | | | | | | countryCode | | | Yes | Order > Shipping Country Code OR Amazon Delivery Locations >Country 2 char code | | | | | | phone | | | No | Order > Shipping Phone OR Amazon Delivery Locations >Phone | | | | | TaxRegistrationDetails | | | | No | | | | | | | taxRegistrationType | | | Yes | N/A | | | | | | taxRegistrationNumber | | | Yes | N/A | | | | shipFromParty | | | | | No | | | | | | partyId | | | | No | Location > Vendor ID | New Field - In order to control the ship from location we want to use our Locations structure and use the Location address. We want to push this node only if we have default Account Location set. | | | | address | | | | No | | | | | | | name | | | Yes | Location > Name | | | | | | addressLine1 | | | Yes | Location > Street1 | | | | | | addressLine2 | | | No | Location > Street2 | | | | | | addressLine3 | | | No | N/A | | | | | | city | | | No | Location > City | | | | | | county | | | No | N/A | | | | | | district | | | No | N/A | | | | | | stateOrRegion | | | No | Location > State Province | | | | | | postalOrZipCode | | | No | Location > Post Code | | | | | | countryCode | | | Yes | Location > Country 2 char code | | | | | | phone | | | No | Location > Phone | | | | | TaxRegistrationDetails | | | | No | | | | | | | taxRegistrationType | | | Yes | N/A | | | | | | taxRegistrationNumber | | | Yes | N/A | | | | billToParty | | | | | No | | | | | | partyId | | | | Yes | N/A | | | | | address | | | | No | | | | | | | name | | | Yes | N/A | | | | | | addressLine1 | | | Yes | N/A | | | | | | addressLine2 | | | No | N/A | | | | | | addressLine3 | | | No | N/A | | | | | | city | | | No | N/A | | | | | | county | | | No | N/A | | | | | | district | | | No | N/A | | | | | | stateOrRegion | | | No | N/A | | | | | | postalOrZipCode | | | No | N/A | | | | | | countryCode | | | Yes | N/A | | | | | | phone | | | No | N/A | | | | | TaxRegistrationDetails | | | | No | | | | | | | taxRegistrationType | | | Yes | N/A | | | | | | taxRegistrationNumber | | | Yes | N/A | | | | paymentTerms | | | | | No | | | | | | type | | | | No | N/A | | | | | discountPercent | | | | No | N/A | | | | | discountDueDays | | | | No | N/A | | | | | netDueDays | | | | No | N/A | | | | invoiceTotal | | | | | Yes | | | | | | currencyCode | | | | Yes | Order > Order Currency | | | | | amount | | | | Yes | | The total /amount should be calculated for all accepted Product In Orders. The calculation should be the SUM of all Product in Order > Item Price * Product In Order > Quantity | | | taxDetails | | | | | No | | | | | | taxType | | | | Yes | N/A | | | | | taxRate | | | | No | N/A | | | | | taxAmount | | | | Yes | | | | | | | currencyCode | | | Yes | N/A | | | | | | amount | | | Yes | N/A | | | | | taxableAmount | | | | No | | | | | | | currencyCode | | | Yes | N/A | | | | | | amount | | | Yes | N/A | | | | AdditionalDetails | | | | | No | | | | | | type | | | | Yes | N/A | | | | | detail | | | | No | N/A | | | | | languageCode | | | | No | N/A | | | | chargeDetails | | | | | No | | | | | | type | | | | Yes | N/A | | | | | description | | | | No | N/A | | | | | chargeAmount | | | | Yes | | | | | | | currencyCode | | | Yes | N/A | | | | | | amount | | | Yes | N/A | | | | | taxDetails | | | | No | | | | | | | taxType | | | Yes | N/A | | | | | | taxRate | | | No | N/A | | | | | | taxAmount | | | Yes | | | | | | | | currencyCode | | Yes | N/A | | | | | | | amount | | Yes | N/A | | | | | | taxableAmount | | | No | | | | | | | | currencyCode | | Yes | N/A | | | | | | | amount | | Yes | N/A | | | | AllowanceDetails | | | | | No | | | | | | type | | | | Yes | N/A | | | | | description | | | | No | N/A | | | | | allowanceAmount | | | | Yes | | | | | | | currencyCode | | | Yes | N/A | | | | | | amount | | | Yes | N/A | | | | | taxDetails | | | | No | | | | | | | taxType | | | Yes | N/A | | | | | | taxRate | | | No | N/A | | | | | | taxAmount | | | Yes | | | | | | | | currencyCode | | Yes | N/A | | | | | | | amount | | Yes | N/A | | | | | | taxableAmount | | | No | | | | | | | | currencyCode | | Yes | N/A | | | | | | | amount | | Yes | N/A | | | | items | | | | | No | | | | | | itemSequenceNumber | | | | Yes | | We need to count the number of items starting from 1 and incrementing the number with each item. Please note each Product In Order > Id are different numbers. | | | | amazonProductIdentifier | | | | No | Product In Order > Channel Item ID | | | | | vendorProductIdentifier | | | | No | <v1.2>Product In Order > Item Transaction ID</v1.2> | | | | | invoicedQuantity | | | | Yes | Product In Order > Quantity | Please note we want to calculate only the accepted order item lines | | | | netCost | | | | Yes | | | | | | | currencyCode | | | Yes | Orders > Order Currency | | | | | | amount | | | Yes | Product In Order > Item Price | Unit Price | | | | purchaseOrderNumber | | | | Yes | Order > Marketplace Order Id | | | | | hsnCode | | | | No | N/A | | | | | creditNoteDetails | | | | No | | | | | | | referenceInvoiceNumber | | | No | N/A | | | | | | debitNoteNumber | | | No | N/A | | | | | | returnsReferenceNumber | | | No | N/A | | | | | | goodsReturnDate | | | No | N/A | | | | | | rmaId | | | No | N/A | | | | | | coopReferenceNumber | | | No | N/A | | | | | | consignorsReferenceNumber | | | No | N/A | | | | | taxDetails | | | | No | | | | | | | taxType | | | Yes | N/A | | | | | | taxRate | | | No | N/A | | | | | | taxAmount | | | Yes | | | | | | | | currencyCode | | Yes | N/A | | | | | | | amount | | Yes | N/A | | | | | | taxableAmount | | | No | | | | | | | | currencyCode | | Yes | N/A | | | | | | | amount | | Yes | N/A | | | | | ChargeDetails | | | | No | | | | | | | type | | | Yes | N/A | | | | | | description | | | No | | | | | | | chargeAmount | | | Yes | | | | | | | | currencyCode | | No | N/A | | | | | | | amount | | Yes | N/A | | | | | | taxDetails | | | No | | | | | | | | taxType | | Yes | N/A | | | | | | | taxRate | | No | N/A | | | | | | | taxAmount | | Yes | | | | | | | | | currencyCode | No | N/A | | | | | | | | amount | Yes | | | | | | | | taxableAmount | | No | | | | | | | | | currencyCode | No | N/A | | | | | | | | amount | Yes | N/A | | | | | AllowanceDetails | | | | No | | | | | | | type | | | Yes | N/A | | | | | | description | | | No | N/A | | | | | | allowanceAmount | | | Yes | | | | | | | | currencyCode | | No | N/A | | | | | | | amount | | Yes | N/A | | | | | | taxDetails | | | No | | | | | | | | taxType | | Yes | N/A | | | | | | | taxRate | | No | N/A | | | | | | | taxAmount | | Yes | | | | | | | | | currencyCode | No | N/A | | | | | | | | amount | Yes | N/A | | | | | | | taxableAmount | | No | | | | | | | | | currencyCode | No | N/A | | | | | | | | amount | Yes | N/A | |
Once we submit an invoice for an order we want to add a new record in the Invoice table with the following details: Invoice > Status = “Pending” Invoice > Number = Order > Id Invoice > Sent By Integration = Sent Invoice > Generated file = “N/A”
Sample Response:
Status: 202
{
"payload": {
"transactionId": "fd621aac-8dab-4885-b38e-21143679942e-20250409091213"
}
}Response Mapping:
Since the invoice creation is asynchronous we will have to store a new feed in Marketplace Feed table.
| Amazon Field | Hemi Field | Comment |
|---|---|---|
| transactionId | Marketplace Feed > External ID | |
| Marketplace Feed > Type | Hardcoded as “Order Invoice” | |
| Marketplace Feed >Status | “Processing” | |
| Marketplace Feed >Submitted Date | Current Date | |
| Marketplace Feed >Sent Objects Count | Number of invoice sent |
Once we read the response using the Get Transaction Status If we receive success we want to set: Invoice > Status = “Sent” Invoice > Sent By Integration = “Uploaded”
If we receive error we want to set” Invoice > Status = “Error” Invoice > Sent By Integration = “Error” Invoice > Integration Error = store the relevant error from the response Store the relevant error in Order Error Table
Limits:
| Rate (requests per second) | Burst |
|---|---|
| 10 | 10 |