HomeDocumentationCode SamplesAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

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
11

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

TypeNameDescriptionSchema
QuerymarketplaceId
required
The marketplace identifier.string

Responses

HTTP CodeDescriptionSchema
200Success.
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.01671

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

TypeNameDescriptionSchema
PathinvoicesDocumentId
required
The export document identifier.string

Responses

HTTP CodeDescriptionSchema
200Success.
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.120

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

TypeNameDescriptionSchema
QuerymarketplaceId
required
The returned exports match the specified marketplace.string
QuerydateStart
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)
QuerynextToken
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
QuerypageSize
optional
The maximum number of invoices to return in a single call.

Minimum: 1

Maximum: 100
integer
QuerydateEnd
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)
Querystatus
optional
Return exports matching the status specified.enum (Status)

Responses

HTTP CodeDescriptionSchema
200Success.
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.1671

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

TypeNameDescriptionSchema
Bodybody
required
Information required to create the export request.ExportInvoicesRequest

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

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

TypeNameDescriptionSchema
PathexportId
required
The unique identifier for the export.string

Responses

HTTP CodeDescriptionSchema
200Success.
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.120

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

TypeNameDescriptionSchema
QuerytransactionIdentifierName
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
QuerypageSize
optional
The maximum number of invoices you want to return in a single call.

Minimum: 1

Maximum: 200
integer
QuerydateEnd
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)
QuerymarketplaceId
required
The response includes only the invoices that match the specified marketplace.string
QuerytransactionType
optional
The marketplace-specific classification of the transaction type for which the invoice was created. Use the getInvoicesAttributes operation to check transactionType options.string
QuerytransactionIdentifierId
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
QuerydateStart
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)
Queryseries
optional
Return invoices with the specified series number.string
QuerynextToken
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
QuerysortOrder
optional
Sort the invoices in the response in ascending or descending order.enum (SortOrder)
QueryinvoiceType
optional
The marketplace-specific classification of the invoice type. Use the getInvoicesAttributes operation to check invoiceType options.string
Querystatuses
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)
QueryexternalInvoiceId
optional
Return invoices that match this external ID. This is typically the Government Invoice ID.string
QuerysortBy
optional
The attribute by which you want to sort the invoices in the response.enum (SortBy)

Responses

HTTP CodeDescriptionSchema
200Success.
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
215

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

TypeNameDescriptionSchema
QuerymarketplaceId
required
The marketplace from which you want the invoice.string
PathinvoiceId
required
The invoice identifier.string

Responses

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

Definitions

AttributeOption

The definition of the attribute option.

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

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

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

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

ExportInvoicesResponse

Success.

NameDescriptionSchema
exportId
optional
The export identifier.string

ExportStatus

The current status of the request.

Type : enum

ValueDescription
REQUESTEDThe export request was created, but has not yet started.
PROCESSINGThe export request is being processed.
DONEThe export request has finished successfully. Use the document IDs to download the output documents.
ERRORThe export request resulted in an error. Refer to the errorMessage attribute for more information.

FileFormat

Supported invoice file extensions.

Type : enum

ValueDescription
XMLThe invoice file is in XML format.

GetInvoiceResponse

Success.

NameDescriptionSchema
invoice
optional
Provides detailed information about an invoice.Invoice

GetInvoicesAttributesResponse

Success.

NameDescriptionSchema
invoicesAttributes
optional
An object that contains the invoice attributes definition.InvoicesAttributes

GetInvoicesDocumentResponse

Success.

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

NameDescriptionSchema
export
optional
Detailed information about the export.Export

GetInvoicesExportsResponse

Success.

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

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

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

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

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

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

NameDescriptionSchema
errors
required
List of errors.< Error > array

Status

Return exports matching the status specified.

Type : enum

ValueDescription
REQUESTEDThe export request was created, but has not started yet.
PROCESSINGThe export request is being processed
DONEThe export request is finished with success. Use the document IDs to download the output documents.
ERRORThe 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

ValueDescription
START_DATE_TIMESort by date time.

SortOrder

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

Type : enum

ValueDescription
DESCSort in descending order.
ASCSort in ascending order.