Vendor Invoices API v1 reference

Overview

The Selling Partner API for Retail Procurement Payments provides programmatic access to vendors payments data.

Version information

Version : v1

Operations

submitInvoices

Paths

submitInvoices

POST /vendor/payments/v1/invoices

Description

Submit new invoices to Amazon.

Usage Plans:

Plan type	Rate (requests per second)	Burst
Default	10	10
Selling partner specific	Variable	Variable

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation. Rate limits for some selling partners will vary from the default rate and burst shown in the table above. For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

Parameters

Type	Name	Description	Schema
Body	body required	The request schema for the submitInvoices operation.	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-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string):Unique request reference identifier.	SubmitInvoicesResponse
415	The request payload is in an unsupported format. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string):Unique request reference identifier.	SubmitInvoicesResponse
429	The frequency of requests was greater than allowed. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. 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-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string):Unique request reference identifier.	SubmitInvoicesResponse
503	Temporary overloading or maintenance of the server. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. 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

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	Schema
invoices optional	< Invoice > array

Invoice

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	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.	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 or 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	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.	Decimal
taxAmount required	Total tax amount applied on invoice total or an 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 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 ISO8601.

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.