Vendor Invoices API v1 Reference
Access vendor payment data.
Overview
The Selling Partner API for Retail Procurement Payments provides programmatic access to vendors payments data.
Version information
Version : v1
Contact information
Contact : Selling Partner API Developer Support
Contact URL : https://sellercentral.amazon.com/gp/mws/contactus.html
License information
License : Apache License 2.0
License URL : http://www.apache.org/licenses/LICENSE-2.0
URI scheme
Host : sellingpartnerapi-na.amazon.com
Schemes : HTTPS
Consumes
application/json
Produces
application/json
Operations
Paths
POST /vendor/payments/v1/invoices
Operation: submitInvoices
Description
Submit new invoices to Amazon.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 10 | 10 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, refer to Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Body | body required | The request body containing the invoice data to submit. | SubmitInvoicesRequest |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 202 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | SubmitInvoicesResponse |
For error status codes, descriptions and schemas, see Error responses and schemas.
Error Responses and Schemas
This table contains HTTP status codes and associated information for error responses.
| HTTP Code | Description | Schema |
|---|---|---|
| 400 | Request has missing or invalid parameters and cannot be parsed. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-RequestId (string):Unique request reference identifier. | SubmitInvoicesResponse |
| 403 | Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature. Headers: x-amzn-RequestId (string):Unique request reference identifier. | SubmitInvoicesResponse |
| 404 | The resource specified does not exist. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-RequestId (string):Unique request reference identifier. | SubmitInvoicesResponse |
| 413 | The request size exceeded the maximum accepted size. Headers: x-amzn-RequestId (string):Unique request reference identifier. | SubmitInvoicesResponse |
| 415 | The request payload is in an unsupported format. Headers: x-amzn-RequestId (string):Unique request reference identifier. | SubmitInvoicesResponse |
| 429 | The frequency of requests was greater than allowed. Headers: x-amzn-RequestId (string):Unique request reference identifier. | SubmitInvoicesResponse |
| 500 | An unexpected condition occurred that prevented the server from fulfilling the request. Headers: x-amzn-RequestId (string):Unique request reference identifier. | SubmitInvoicesResponse |
| 503 | Temporary overloading or maintenance of the server. Headers: x-amzn-RequestId (string):Unique request reference identifier. | SubmitInvoicesResponse |
Definitions
SubmitInvoicesResponse
The response schema for the submitInvoices operation.
| Name | Description | Schema |
|---|---|---|
| payload optional | The response payload for the submitInvoices operation. | TransactionId |
| errors optional | A list of error responses returned when a request is unsuccessful. | ErrorList |
TransactionId
Response containing the transaction ID.
| Name | Description | Schema |
|---|---|---|
| transactionId optional | GUID to identify this transaction. This value can be used with the Transaction Status API to return the status of this transaction. | string |
ErrorList
A list of error responses returned when a request is unsuccessful.
Type : < Error > array
Error
Error response returned when the request is unsuccessful.
| Name | Description | Schema |
|---|---|---|
| code required | An error code that identifies the type of error that occurred. | string |
| message required | A message that describes the error condition. | string |
| details optional | Additional details that can help the caller understand or fix the issue. | string |
SubmitInvoicesRequest
The request schema for the submitInvoices operation.
| Name | Description | Schema |
|---|---|---|
| invoices optional | An array of Invoice objects representing the invoices or credit notes to be submitted. | < Invoice > array |
Invoice
Represents an invoice or credit note document with details about the transaction, parties involved, and line items.
| Name | Description | Schema |
|---|---|---|
| invoiceType required | Identifies the type of invoice. | enum (InvoiceType) |
| id required | Unique number relating to the charges defined in this document. This will be invoice number if the document type is Invoice or CreditNote number if the document type is Credit Note. Failure to provide this reference will result in a rejection. | string |
| referenceNumber optional | An additional unique reference number used for regulatory or other purposes. | string |
| date required | Date when the invoice/credit note information was generated in the origin's accounting system. The invoice date should be on or after the purchase order creation date. | DateTime |
| remitToParty required | Name, address, and tax details of the party receiving the payment of this invoice. | PartyIdentification |
| shipToParty optional | Name, address, and tax details of the party receiving a shipment of products. | PartyIdentification |
| shipFromParty optional | Name, address, and tax details of the party sending a shipment of products. | PartyIdentification |
| billToParty optional | Name, address, and tax details of the party to whom this invoice is issued. | PartyIdentification |
| paymentTerms optional | The payment terms for the invoice. | PaymentTerms |
| invoiceTotal required | Total monetary amount charged in the invoice or full value of credit note to be paid including all relevant taxes. It is the total amount of invoice (including charges, less allowances) before terms discount (if discount is applicable). | Money |
| taxDetails optional | Total tax amount details for all line items. | < TaxDetails > array |
| additionalDetails optional | Additional details provided by the selling party, for tax related or other purposes. | < AdditionalDetails > array |
| chargeDetails optional | Total charge amount details for all line items. | < ChargeDetails > array |
| allowanceDetails optional | Total allowance amount details for all line items. | < AllowanceDetails > array |
| items optional | The list of invoice items. | < InvoiceItem > array |
PartyIdentification
Name, address, and tax details of a party.
| Name | Description | Schema |
|---|---|---|
| partyId required | Assigned identification for the party. | string |
| address optional | Identification of the party by address. | Address |
| taxRegistrationDetails optional | Tax registration details of the party. | < TaxRegistrationDetails > array |
TaxRegistrationDetails
Tax registration details of the entity.
| Name | Description | Schema |
|---|---|---|
| taxRegistrationType required | The tax registration type for the entity. | enum (TaxRegistrationType) |
| taxRegistrationNumber required | The tax registration number for the entity. For example, VAT ID, Consumption Tax ID. | string |
Address
A physical address.
| Name | Description | Schema |
|---|---|---|
| name required | The name of the person, business or institution at that address. | string |
| addressLine1 required | First line of street address. | string |
| addressLine2 optional | Additional address information, if required. | string |
| addressLine3 optional | Additional address information, if required. | string |
| city optional | The city where the person, business, or institution is located. | string |
| county optional | The county where person, business, or institution is located. | string |
| district optional | The district where person, business, or institution is located. | string |
| stateOrRegion optional | The state or region where person, business, or institution is located. | string |
| postalOrZipCode optional | The postal or zip code of that address. It contains a series of letters, digits, or both, sometimes including spaces or punctuation. | string |
| countryCode required | The two digit country code. In ISO 3166-1 alpha-2 format. maxLength : 2 | string |
| phone optional | The phone number of the person, business or institution located at that address. | string |
InvoiceItem
Details of the item being invoiced.
| Name | Description | Schema |
|---|---|---|
| itemSequenceNumber required | Unique number related to this line item. | integer |
| amazonProductIdentifier optional | Amazon Standard Identification Number (ASIN) of an item. | string |
| vendorProductIdentifier optional | The vendor selected product identifier of the item. Should be the same as was provided in the purchase order. | string |
| invoicedQuantity required | Invoiced quantity of this item. Quantity must be greater than zero. | ItemQuantity |
| netCost required | The item cost to Amazon, which should match the cost on the order. Price information should not be zero or negative. It indicates net unit price. Net cost means VAT is not included in cost. | Money |
| purchaseOrderNumber optional | The Amazon purchase order number for this invoiced line item. Formatting Notes: 8-character alpha-numeric code. This value is mandatory only when invoiceType is Invoice, and is not required when invoiceType is CreditNote. | string |
| hsnCode optional | The HSN Tax code. The HSN number cannot contain alphabets. | string |
| creditNoteDetails optional | Details required in order to process a credit note. This information is required only if invoiceType is CreditNote. | CreditNoteDetails |
| taxDetails optional | Individual tax details per line item. | < TaxDetails > array |
| chargeDetails optional | Individual charge details per line item. | < ChargeDetails > array |
| allowanceDetails optional | Individual allowance details per line item. | < AllowanceDetails > array |
TaxDetails
Details of tax amount applied.
| Name | Description | Schema |
|---|---|---|
| taxType required | Type of the tax applied. | enum (TaxType) |
| taxRate optional | Tax percentage applied. Percentage must be expressed in decimal format. | Decimal |
| taxAmount required | Total tax amount applied on an invoice total or item total. | Money |
| taxableAmount optional | The invoice amount that is taxable at the rate specified in the tax rate field. | Money |
Money
An amount of money, including units in the form of currency.
| Name | Description | Schema |
|---|---|---|
| currencyCode optional | Three-digit currency code in ISO 4217 format. | string |
| amount optional | A decimal number with no loss of precision. Useful when precision loss is unacceptable, as with currencies. Follows RFC7159 for number representation. Pattern : ^-?(0|([1-9]\d*))(\.\d+)?([eE][+-]?\d+)?$. | Decimal |
AdditionalDetails
Additional information provided by the selling party for tax-related or any other purpose.
| Name | Description | Schema |
|---|---|---|
| type required | The type of the additional information provided by the selling party. | enum (Type) |
| detail required | The detail of the additional information provided by the selling party. | string |
| languageCode optional | The language code of the additional information detail. | string |
ChargeDetails
Monetary and tax details of the charge.
| Name | Description | Schema |
|---|---|---|
| type required | Type of the charge applied. | enum (Type) |
| description optional | Description of the charge. | string |
| chargeAmount required | Total monetary amount related to this charge. | Money |
| taxDetails optional | Tax amount details applied on this charge. | < TaxDetails > array |
AllowanceDetails
Monetary and tax details of the allowance.
| Name | Description | Schema |
|---|---|---|
| type required | Type of the allowance applied. | enum (Type) |
| description optional | Description of the allowance. | string |
| allowanceAmount required | Total monetary amount related to this allowance. | Money |
| taxDetails optional | Tax amount details applied on this allowance. | < TaxDetails > array |
PaymentTerms
Terms of the payment for the invoice. The basis of the payment terms is the invoice date.
| Name | Description | Schema |
|---|---|---|
| type optional | The payment term type for the invoice. | enum (Type) |
| discountPercent optional | The discount percent value, which is good until the discount due date. | Decimal |
| discountDueDays optional | The number of calendar days from the base date (Invoice date) until the discount is no longer valid. | number |
| netDueDays optional | The number of calendar days from the base date (invoice date) until the total amount on the invoice is due. | number |
CreditNoteDetails
References required in order to process a credit note. This information is required only if InvoiceType is CreditNote.
| Name | Description | Schema |
|---|---|---|
| referenceInvoiceNumber optional | Original invoice number when sending a credit note relating to an existing invoice. One invoice only to be processed per credit note. This is mandatory for AP credit notes. | string |
| debitNoteNumber optional | Debit note number as generated by Amazon. Recommended for returns and COOP credit notes. | string |
| returnsReferenceNumber optional | Identifies the returns notice number. Mandatory for all returns credit notes. | string |
| goodsReturnDate optional | Date that a return is received by the vendor. It is mandatory for the returns credit note. | DateTime |
| rmaId optional | Identifies the Returned Merchandise Authorization ID, if generated. | string |
| coopReferenceNumber optional | Identifies the COOP reference used for COOP agreement. Failure to provide the COOP reference number or the debit note number may lead to a rejection of the credit note. | string |
| consignorsReferenceNumber optional | Identifies the consignor reference number (VRET number), if generated by Amazon. | string |
ItemQuantity
Details of quantity.
| Name | Description | Schema |
|---|---|---|
| amount required | Quantity of an item. This value should not be zero. | integer |
| unitOfMeasure required | Unit of measure for the quantity. | enum (UnitOfMeasure) |
| unitSize optional | The case size, if the unit of measure value is Cases. | integer |
Decimal
A decimal number with no loss of precision. Useful when precision loss is unacceptable, as with currencies. Follows RFC7159 for number representation.
Pattern : ^-?(0|([1-9]\d*))(\.\d+)?([eE][+-]?\d+)?$.
Type : string
DateTime
Defines a date and time according to ISO 8601.
Type : string (date-time)
TaxType
Type of the tax applied.
Type : enum
| Value | Description |
|---|---|
| CGST | Central Goods and Services Tax (CGST) is levied by the Indian government for intrastate movement of goods and services. |
| SGST | State Goods and Services Tax (SGST) is an indirect tax levied and collected by a State Government in India on the intra-state supplies. |
| CESS | A CESS is a form of tax levied by the government on tax with specific purposes till the time the government gets enough money for that purpose. |
| UTGST | Union Territory Goods and Services Tax in India. |
| IGST | Integrated Goods and Services Tax (IGST) is a tax levied on all Inter-State supplies of goods and/or services in India. |
| MwSt. | Mehrwertsteuer, MwSt, is German for value-added tax. |
| PST | A provincial sales tax (PST) is imposed on consumers of goods and particular services in many Canadian provinces. |
| TVA | Taxe sur la Valeur Ajoutée (TVA) is French for value-added tax. |
| VAT | Value-added tax. |
| GST | Tax levied on most goods and services sold for domestic consumption. |
| ST | Sales tax. |
| Consumption | Tax levied on consumption spending on goods and services. |
| MutuallyDefined | Tax component that was mutually agreed upon between Amazon and vendor. |
| DomesticVAT | Domestic value-added tax. |
UnitOfMeasure
Unit of measure for the quantity.
Type : enum
| Value | Description |
|---|---|
| Cases | Packing of individual items into a case. |
| Eaches | Individual items. |
TaxRegistrationType
The tax registration type for the entity.
Type : enum
| Value | Description |
|---|---|
| VAT | Value-added tax. |
| GST | Goods and services tax. |
InvoiceType
Identifies the type of invoice.
Type : enum
| Value | Description |
|---|---|
| Invoice | A commercial document issued by a seller to a buyer, relating to a sale transaction and indicating the products, quantities, and agreed prices for products or services the seller had provided the buyer. |
| CreditNote | A commercial document issued by a seller to a buyer. It is evidence of the reduction in sales. |
Type
Type : enum
For use with the definition(s): PaymentTerms
The payment term type for the invoice.
| Value | Description |
|---|---|
| Basic | Payment term that buyer and seller have agreed to. |
| EndOfMonth | Payment term where seller gets paid end of month. |
| FixedDate | Payment term where seller gets paid on a fixed date as agreed with buyer. |
| Proximo | Payment term where seller gets paid end of following month. |
| PaymentDueUponReceiptOfInvoice | Payment term where seller gets paid upon receipt of the invoice by the buyer. |
| LetterofCredit | A payment undertaking given by a bank to the seller and is issued on behalf of the applicant i.e. the buyer. |
For use with the definition(s): AdditionalDetails
The type of the additional information provided by the selling party.
| Value | Description |
|---|---|
| SUR | An additional tax on something already taxed, such as a higher rate of tax on incomes above a certain level. |
| OCR | OCR. |
| CartonCount | The total number of cartons invoiced. |
For use with the definition(s): AllowanceDetails
Type of the allowance applied.
| Value | Description |
|---|---|
| Discount | Discount allowance. |
| DiscountIncentive | Discount incentive allowance. |
| Defective | Allowance applied for defective item. |
| Promotional | Promotional allowance. |
| UnsaleableMerchandise | Allowance applied due to unsaleable merchandise. |
| Special | Special allowances. |
For use with the definition(s): ChargeDetails
Type of the charge applied.
| Value | Description |
|---|---|
| Freight | Freight charges. |
| Packing | Packing fee. |
| Duty | Duty charges. |
| Service | Service fee. |
| SmallOrder | Small order fee. |
| InsurancePlacementCost | Insurance placement cost. |
| InsuranceFee | Insurance fee. |
| SpecialHandlingService | Special handling service fee. |
| CollectionAndRecyclingService | Collection and recycling service fee. |
| EnvironmentalProtectionService | Environmental protection service fee. |
| TaxCollectedAtSource | Tax collected at source. |
Updated 4 months ago