HomeDocumentationCode SamplesAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

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

submitInvoices

Paths

POST /vendor/payments/v1/invoices

Operation: submitInvoices

Description

Submit new invoices to Amazon.

Usage Plan:

Rate (requests per second)Burst
1010

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

TypeNameDescriptionSchema
Bodybody
required
The request body containing the invoice data to submit.SubmitInvoicesRequest

Responses

HTTP CodeDescriptionSchema
202Success.
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 CodeDescriptionSchema
400Request 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
403Indicates 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
404The 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
413The request size exceeded the maximum accepted size.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
SubmitInvoicesResponse
415The request payload is in an unsupported format.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
SubmitInvoicesResponse
429The frequency of requests was greater than allowed.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
SubmitInvoicesResponse
500An unexpected condition occurred that prevented the server from fulfilling the request.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
SubmitInvoicesResponse
503Temporary 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

NameDescriptionSchema
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

ValueDescription
CGSTCentral Goods and Services Tax (CGST) is levied by the Indian government for intrastate movement of goods and services.
SGSTState Goods and Services Tax (SGST) is an indirect tax levied and collected by a State Government in India on the intra-state supplies.
CESSA 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.
UTGSTUnion Territory Goods and Services Tax in India.
IGSTIntegrated 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.
PSTA provincial sales tax (PST) is imposed on consumers of goods and particular services in many Canadian provinces.
TVATaxe sur la Valeur Ajoutée (TVA) is French for value-added tax.
VATValue-added tax.
GSTTax levied on most goods and services sold for domestic consumption.
STSales tax.
ConsumptionTax levied on consumption spending on goods and services.
MutuallyDefinedTax component that was mutually agreed upon between Amazon and vendor.
DomesticVATDomestic value-added tax.

UnitOfMeasure

Unit of measure for the quantity.

Type : enum

ValueDescription
CasesPacking of individual items into a case.
EachesIndividual items.

TaxRegistrationType

The tax registration type for the entity.

Type : enum

ValueDescription
VATValue-added tax.
GSTGoods and services tax.

InvoiceType

Identifies the type of invoice.

Type : enum

ValueDescription
InvoiceA 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.
CreditNoteA 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.

ValueDescription
BasicPayment term that buyer and seller have agreed to.
EndOfMonthPayment term where seller gets paid end of month.
FixedDatePayment term where seller gets paid on a fixed date as agreed with buyer.
ProximoPayment term where seller gets paid end of following month.
PaymentDueUponReceiptOfInvoicePayment term where seller gets paid upon receipt of the invoice by the buyer.
LetterofCreditA 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.

ValueDescription
SURAn additional tax on something already taxed, such as a higher rate of tax on incomes above a certain level.
OCROCR.
CartonCountThe total number of cartons invoiced.

For use with the definition(s): AllowanceDetails
Type of the allowance applied.

ValueDescription
DiscountDiscount allowance.
DiscountIncentiveDiscount incentive allowance.
DefectiveAllowance applied for defective item.
PromotionalPromotional allowance.
UnsaleableMerchandiseAllowance applied due to unsaleable merchandise.
SpecialSpecial allowances.

For use with the definition(s): ChargeDetails
Type of the charge applied.

ValueDescription
FreightFreight charges.
PackingPacking fee.
DutyDuty charges.
ServiceService fee.
SmallOrderSmall order fee.
InsurancePlacementCostInsurance placement cost.
InsuranceFeeInsurance fee.
SpecialHandlingServiceSpecial handling service fee.
CollectionAndRecyclingServiceCollection and recycling service fee.
EnvironmentalProtectionServiceEnvironmental protection service fee.
TaxCollectedAtSourceTax collected at source.