Invoices API v2024-06-19 Use Case Guide
Learn how to use the Invoices API.
API Version: 2024-06-19
What is the Invoices API?
You can use the Selling Partner API for Invoices to retrieve and manage a variety of invoice-related operations that can help selling partners manage their bookkeeping.
❗Important
This API is only able to retrieve Brazilian FBA invoices. You cannot use this API for any other invoice types.
Key features
- Search invoices by their attributes
- Export and download invoices
Terminology
- Sefaz: Brazilian State Tax Administration (Secretaria da Fazenda).
Tutorial: Export invoice files
Learn how to export and download invoice files.
Prerequisites
To complete this tutorial, you must have:
- Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API applications.
- The Tax Invoicing role assigned to your developer profile.
- The Tax Invoicing role selected on the App registration page for your application.
Step 1. Create an invoice export
Call the createInvoicesExport
operation and specify the marketplace, date range, and any optional parameters you want to include.
If the request is successful, the response includes an exportId
value.
Body parameters
Name | Description | Required |
---|---|---|
marketplaceId | The returned invoices match the marketplace that you specify. Type: string | Yes |
dateStart | The earliest invoice creation date for invoices that you want to include in the response. Dates are in ISO 8601 format. Type: string (date) | No |
dateEnd | The latest invoice creation date for invoices that you want to include in the response. Dates are in ISO 8601 format. Type: string (date) | No |
Tip
To reduce export processing time, use short date intervals for
dateStart
anddateEnd
. The optimal range is one day.
Request example
POST https://sellingpartnerapi-na.amazon.com/invoices/v1/exports?marketplaceId=A2Q3Y263D00KWC&dateStart=2024-07-09T00:00:00Z&dateEnd=2024-07-10T00:00:00Z
Response
Name | Description |
---|---|
exportId | The export identifier. Type: string |
Response example
{
"exportId": "4bdd8293-0cd7-4208-bed5-78b2c6ecefef"
}
Step 2. Verify that export processing is complete
Periodically call the getInvoicesExport
operation--passing the exportId
value that you received in Step 1--until processing is complete (processingStatus
is CANCELLED
, DONE
, or FATAL
). At this point, the response includes an exportDocumentId
value if invoice data is available.
Path parameters
Name | Description | Required |
---|---|---|
exportId | The identifier for the export. Type: string | Yes |
Request example
GET https://sellingpartnerapi-na.amazon.com/invoices/v1/exports/4bdd8293-0cd7-4208-bed5-78b2c6ecefef
Response
Name | Description |
---|---|
errorMessage | When the export generation fails, this attribute contains a description of the error. Type: string |
exportDocumentIds | A list with the identifiers of each export document. Type: array |
exportId | The export identifier. Type: string |
generateExportFinished | The date and time when the export generation finished, in ISO 8601 date-time format. Type: string |
generateExportStarted | The date and time when the export generation started, in ISO 8601 date-time format. Type: string |
status | The processing status. Type: enum ( REQUESTED , PROCESSING , DONE , ERROR ) |
Response example
{
"export": {
"errorMessage": "",
"exportDocumentIds": [
"18c598f5-75db-4c1a-bd3e-4c64b36781c5"
],
"exportId": "4bdd8293-0cd7-4208-bed5-78b2c6ecefef",
"generateExportFinished": "2024-07-10T16:00:00.000Z",
"generateExportStarted": "2024-07-10T15:00:00.000Z",
"status": "DONE"
}
}
Step 3. Get the invoice document URL
Call the getInvoicesDocument
operation, passing the exportDocumentId
value from Step 2.
The response contains a pre-signed URL that you can use to access the invoice export. If the contents are compressed, the compressional algorithm is provided. The URL expires after 30 seconds.
Path parameters
Name | Description | Required |
---|---|---|
invoicesDocumentId | The identifier for the export document. Type: string | Yes |
Request example
GET https://sellingpartnerapi-na.amazon.com/invoices/v1/documents/18c598f5-75db-4c1a-bd3e-4c64b36781c5
Response
Name | Description |
---|---|
invoicesDocumentId | The export document identifier. Type: string |
invoicesDocumentUrl | A pre-signed URL that you can use to download the invoices (in ZIP format). Type: string |
Response example
{
"exportDocumentId": "18c598f5-75db-4c1a-bd3e-4c64b36781c5",
"url": "https://d34o8swod1owfl.cloudfront.net/SampleResult%2BKey%3DSample%2BINITVEC%3D58+fa+bf+a7+08+11+95+0f+c1+a8+c6+e0+d5+6f+ae+c8"
}
Updated about 1 month ago