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 |
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 |
---|---|---|---|
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 |
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 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 |
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 |
---|---|---|---|
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 |
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 |
---|---|---|---|
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 |
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 | 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 |
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 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 19 days ago