Invoices API v2024-06-19 Reference

Retrieve and manage invoice-related operations for the Brazil marketplace.

Use the Selling Partner API for Invoices to retrieve and manage invoice-related operations, which can help selling partners manage their bookkeeping processes.

Version information

Version : 2024-06-19

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

getInvoicesAttributes
getInvoicesDocument
getInvoicesExports
createInvoicesExport
getInvoicesExport
getInvoices
getInvoice

Paths

GET /tax/invoices/2024-06-19/attributes

Operation: getInvoicesAttributes

Description

Returns marketplace-dependent schemas and their respective set of possible values.

Usage Plan:

Rate (requests per second)	Burst
1	1

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The preceding table indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may have 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
Query	marketplaceId required	The marketplace identifier.	string

Responses

HTTP Code	Description	Schema
200	Success. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	GetInvoicesAttributesResponse

For error status codes, descriptions and schemas, see Error responses and schemas.

Produces

application/json

GET /tax/invoices/2024-06-19/documents/{invoicesDocumentId}

Operation: getInvoicesDocument

Description

Returns the invoice document's ID and URL. Use the URL to download the ZIP file, which contains the invoices from the corresponding createInvoicesExport request.

Usage Plan:

Rate (requests per second)	Burst
0.0167	1

Parameters

Type	Name	Description	Schema
Path	invoicesDocumentId required	The export document identifier.	string

Responses

HTTP Code	Description	Schema
200	Success. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	GetInvoicesDocumentResponse

For error status codes, descriptions and schemas, see Error responses and schemas.

Produces

application/json

GET /tax/invoices/2024-06-19/exports

Operation: getInvoicesExports

Description

Returns invoice exports details for exports that match the filters that you specify.

Usage Plan:

Rate (requests per second)	Burst
0.1	20

Parameters

Type	Name	Description	Schema
Query	marketplaceId required	The returned exports match the specified marketplace.	string
Query	dateStart optional	The earliest export creation date and time for exports that you want to include in the response. Values are in ISO 8601 date-time format. The default is 30 days ago.	string (date-time)
Query	nextToken optional	The response includes `nextToken` when the number of results exceeds the specified `pageSize` value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until `nextToken` is null. Note that this operation can return empty pages.	string
Query	pageSize optional	The maximum number of invoices to return in a single call. Minimum: 1 Maximum: 100	integer
Query	dateEnd optional	The latest export creation date and time for exports that you want to include in the response. Values are in ISO 8601 date-time format. The default value is the time of the request.	string (date-time)
Query	status optional	Return exports matching the status specified.	enum (Status)

Responses

HTTP Code	Description	Schema
200	Success. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	GetInvoicesExportsResponse

For error status codes, descriptions and schemas, see Error responses and schemas.

Produces

application/json

POST /tax/invoices/2024-06-19/exports

Operation: createInvoicesExport

Description

Creates an invoice export request.

Usage Plan:

Rate (requests per second)	Burst
0.167	1

Parameters

Type	Name	Description	Schema
Body	body required	Information required to create the export request.	ExportInvoicesRequest

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

For error status codes, descriptions and schemas, see Error responses and schemas.

Consumes

application/json

Produces

application/json

Example HTTP request

Request body

{
  "body" : {
    "dateEnd" : "2024-07-30T23:59:59",
    "dateStart" : "2024-07-01T00:00:00",
    "externalInvoiceId" : "1283743",
    "fileFormat" : "XML",
    "invoiceType" : "SYMBOLIC_RETURN",
    "marketplaceId" : "A2Q3Y263D00KWC",
    "series" : "32",
    "statuses" : [ "AUTHORIZED" ],
    "transactionIdentifier" : {
      "name" : "BUSINESS_TRANSACTION_ID",
      "id" : "94cd4e1a-5cc5-486d-b592-045a95a168e1"
    },
    "transactionType" : "CUSTOMER_SALES"
  }
}

GET /tax/invoices/2024-06-19/exports/{exportId}

Operation: getInvoicesExport

Description

Returns invoice export details (including the exportDocumentId, if available) for the export that you specify.

Usage Plan:

Rate (requests per second)	Burst
2	15

Parameters

Type	Name	Description	Schema
Path	exportId required	The unique identifier for the export.	string

Responses

HTTP Code	Description	Schema
200	Success. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	GetInvoicesExportResponse

For error status codes, descriptions and schemas, see Error responses and schemas.

Produces

application/json

GET /tax/invoices/2024-06-19/invoices

Operation: getInvoices

Description

Returns invoice details for the invoices that match the filters that you specify.

Usage Plan:

Rate (requests per second)	Burst
0.1	20

Parameters

Type	Name	Description	Schema
Query	transactionIdentifierName optional	The name of the transaction identifier filter. If you provide a value for this field, you must also provide a value for the `transactionIdentifierId` field.Use the `getInvoicesAttributes` operation to check `transactionIdentifierName` options.	string
Query	pageSize optional	The maximum number of invoices you want to return in a single call. Minimum: 1 Maximum: 200	integer
Query	dateEnd optional	The latest invoice creation date for invoices that you want to include in the response. Dates are in ISO 8601 date-time format. The default is the current date-time.	string (date-time)
Query	marketplaceId required	The response includes only the invoices that match the specified marketplace.	string
Query	transactionType optional	The marketplace-specific classification of the transaction type for which the invoice was created. Use the `getInvoicesAttributes` operation to check `transactionType` options.	string
Query	transactionIdentifierId optional	The ID of the transaction identifier filter. If you provide a value for this field, you must also provide a value for the `transactionIdentifierName` field.	string
Query	dateStart optional	The earliest invoice creation date for invoices that you want to include in the response. Dates are in ISO 8601 date-time format. The default is 24 hours prior to the time of the request.	string (date-time)
Query	series optional	Return invoices with the specified series number.	string
Query	nextToken optional	The response includes `nextToken` when the number of results exceeds the specified `pageSize` value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until `nextToken` is null. Note that this operation can return empty pages.	string
Query	sortOrder optional	Sort the invoices in the response in ascending or descending order.	enum (SortOrder)
Query	invoiceType optional	The marketplace-specific classification of the invoice type. Use the `getInvoicesAttributes` operation to check `invoiceType` options.	string
Query	statuses optional	A list of statuses that you can use to filter invoices. Use the `getInvoicesAttributes` operation to check invoice status options. Min count: 1 Min count : 1	< string > array(csv)
Query	externalInvoiceId optional	Return invoices that match this external ID. This is typically the Government Invoice ID.	string
Query	sortBy optional	The attribute by which you want to sort the invoices in the response.	enum (SortBy)

Responses

HTTP Code	Description	Schema
200	Success. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	GetInvoicesResponse

For error status codes, descriptions and schemas, see Error responses and schemas.

Produces

application/json

GET /tax/invoices/2024-06-19/invoices/{invoiceId}

Operation: getInvoice

Description

Returns invoice data for the specified invoice. This operation returns only a subset of the invoices data; refer to the response definition to get all the possible attributes.
To get the full invoice, use the createInvoicesExport operation to start an export request.

Usage Plan:

Rate (requests per second)	Burst
2	15

Parameters

Type	Name	Description	Schema
Query	marketplaceId required	The marketplace from which you want the invoice.	string
Path	invoiceId required	The invoice identifier.	string

Responses

HTTP Code	Description	Schema
200	Success. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	GetInvoiceResponse

For error status codes, descriptions and schemas, see Error responses and schemas.

Produces

application/json

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.	ErrorList
401	A list of error responses returned when a request is unsuccessful. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
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.	ErrorList
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.	ErrorList
413	The request size exceeded the maximum accepted size. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
415	The request payload is in an unsupported format. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
429	The frequency of requests was greater than allowed. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
500	An unexpected condition occurred that prevented the server from fulfilling the request. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
503	Temporary overloading or maintenance of the server. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList

Definitions

AttributeOption

The definition of the attribute option.

Name	Description	Schema
description optional	The description of the attribute value.	string
value optional	The possible values for the attribute option.	string

Error

The error response that is returned when the request is unsuccessful.

Name	Description	Schema
code required	An error code that identifies the type of error that occurred.	string
details optional	Additional details that can help the caller understand or fix the issue.	string
message required	A message that describes the error condition.	string

Export

Detailed information about the export.

Name	Description	Schema
errorMessage optional	When the export generation fails, this attribute contains a description of the error.	string
exportId optional	The export identifier.	string
generateExportFinishedAt optional	The date and time when the export generation finished. Vales are in ISO 8601 date-time format.	string (date-time)
generateExportStartedAt optional	The date and time when the export generation started. Values are in ISO 8601 date-time format.	string (date-time)
invoicesDocumentIds optional	The identifier for the export documents. To get the information required to retrieve the export document's contents, pass each ID in the `getInvoicesDocument` operation. This list is empty until the status is `DONE`.	< string > array
status optional	The current status of the request.	ExportStatus

ExportInvoicesRequest

The information required to create the export request.

Name	Description	Schema
dateEnd optional	The latest invoice creation date for invoices that you want to include in the response. Dates are in ISO 8601 date-time format. The default is the time of the request.	string (date)
dateStart optional	The earliest invoice creation date for invoices that you want to include in the response. Dates are in ISO 8601 date-time format. The default is 24 hours prior to the time of the request.	string (date)
externalInvoiceId optional	The external ID of the invoices you want included in the response.	string
fileFormat optional	Supported invoice file extensions.	FileFormat
invoiceType optional	The marketplace-specific classification of the invoice type. Use the `getInvoicesAttributes` operation to check `invoiceType` options.	string
marketplaceId required	The ID of the marketplace from which you want the invoices.	string
series optional	The series number of the invoices you want included in the response.	string
statuses optional	A list of statuses that you can use to filter invoices. Use the `getInvoicesAttributes` operation to check invoice status options. Min count: 1	< string > array
transactionIdentifier optional	The identifier for a transaction.	TransactionIdentifier
transactionType optional	The marketplace-specific classification of the transaction type for which the invoice was created. Use the `getInvoicesAttributes` operation to check `transactionType` options	string

ExportInvoicesResponse

Success.

Name	Description	Schema
exportId optional	The export identifier.	string

ExportStatus

The current status of the request.

Type : enum

Value	Description
REQUESTED	The export request was created, but has not yet started.
PROCESSING	The export request is being processed.
DONE	The export request has finished successfully. Use the document IDs to download the output documents.
ERROR	The export request resulted in an error. Refer to the `errorMessage` attribute for more information.

FileFormat

Supported invoice file extensions.

Type : enum

Value	Description
XML	The invoice file is in XML format.

GetInvoiceResponse

Success.

Name	Description	Schema
invoice optional	Provides detailed information about an invoice.	Invoice

GetInvoicesAttributesResponse

Success.

Name	Description	Schema
invoicesAttributes optional	An object that contains the invoice attributes definition.	InvoicesAttributes

GetInvoicesDocumentResponse

Success.

Name	Description	Schema
invoicesDocument optional	An object that contains the `documentId` and an S3 pre-signed URL that you can use to download the specified file.	InvoicesDocument

GetInvoicesExportResponse

Success.

Name	Description	Schema
export optional	Detailed information about the export.	Export

GetInvoicesExportsResponse

Success.

Name	Description	Schema
exports optional	A list of exports.	< Export > array
nextToken optional	This token is returned when the number of results exceeds the specified `pageSize` value. To get the next page of results, call the `getInvoices` operation and include this token with the previous call parameters.	string

GetInvoicesResponse

Success.

Name	Description	Schema
invoices optional	A list of invoices.	< Invoice > array
nextToken optional	This token is returned when the number of results exceeds the specified `pageSize` value. To get the next page of results, call the `getInvoices` operation and include this token with the previous call parameters.	string

Invoice

Provides detailed information about an invoice.

Name	Description	Schema
date optional	The date and time the invoice is issued. Values are in ISO 8601 date-time format.	string (date-time)
errorCode optional	If the invoice is in an error state, this attribute displays the error code.	string
externalInvoiceId optional	The invoice identifier that is used by an external party. This is typically the government agency that authorized the invoice.	string
govResponse optional	The response message from the government authority when there is an error during invoice issuance.	string
id optional	The invoice identifier.	string
invoiceType optional	The classification of the invoice type. This varies across marketplaces. Use the `getInvoicesAttributes` operation to check `invoiceType` options.	string
series optional	Use this identifier in conjunction with `externalInvoiceId` to identify invoices from the same seller.	string
status optional	The invoice status classification. Use the `getInvoicesAttributes` operation to check invoice status options.	string
transactionIds optional	List with identifiers for the transactions associated to the invoice.	< TransactionIdentifier > array
transactionType optional	Classification of the transaction that originated this invoice. Use the `getInvoicesAttributes` operation to check `transactionType` options.	string

InvoicesAttributes

An object that contains the invoice attributes definition.

Name	Description	Schema
invoiceStatusOptions optional	A list of all the options that are available for the invoice status attribute.	< AttributeOption > array
invoiceTypeOptions optional	A list of all the options that are available for the invoice type attribute.	< AttributeOption > array
transactionIdentifierNameOptions optional	A list of all the options that are available for the transaction identifier name attribute.	< AttributeOption > array
transactionTypeOptions optional	A list of all the options that are available for the transaction type attribute.	< AttributeOption > array

InvoicesDocument

An object that contains the documentId and an S3 pre-signed URL that you can use to download the specified file.

Name	Description	Schema
invoicesDocumentId optional	The identifier of the export document.	string
invoicesDocumentUrl optional	A pre-signed URL that you can use to download the invoices document in zip format. This URL expires after 30 seconds.	string

TransactionIdentifier

The identifier for a transaction.

Name	Description	Schema
name optional	The transaction identifier name. Use the `getInvoicesAttributes` operation to check `transactionIdentifierName` options.	string
id optional	The transaction identifier.	string

ErrorList

A list of error responses that are returned when a request is unsuccessful.

Name	Description	Schema
errors required	List of errors.	< Error > array

Status

Return exports matching the status specified.

Type : enum

Value	Description
REQUESTED	The export request was created, but has not started yet.
PROCESSING	The export request is being processed
DONE	The export request is finished with success. Use the document IDs to download the output documents.
ERROR	The export request resulted in an error. Check the `errorMessage` attribute for more details.

SortBy

The attribute by which you want to sort the invoices in the response.

Type : enum

Value	Description
START_DATE_TIME	Sort by date time.

SortOrder

Sort the invoices in the response in ascending or descending order.

Type : enum

Value	Description
DESC	Sort in descending order.
ASC	Sort in ascending order.

Updated about 1 month ago