HomeDocumentationCode SamplesAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

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

NameDescriptionRequired
marketplaceIdThe returned invoices match the marketplace that you specify.
Type: string
Yes
dateStartThe earliest invoice creation date for invoices that you want to include in the response. Dates are in ISO 8601 format.
Type: string (date)
No
dateEndThe 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 and dateEnd. 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

NameDescription
exportIdThe 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

NameDescriptionRequired
exportIdThe identifier for the export.
Type: string
Yes

Request example

GET https://sellingpartnerapi-na.amazon.com/invoices/v1/exports/4bdd8293-0cd7-4208-bed5-78b2c6ecefef

Response

NameDescription
errorMessageWhen the export generation fails, this attribute contains a description of the error.
Type: string
exportDocumentIdsA list with the identifiers of each export document.
Type: array
exportIdThe export identifier.
Type: string
generateExportFinishedThe date and time when the export generation finished, in ISO 8601 date-time format.
Type: string
generateExportStartedThe date and time when the export generation started, in ISO 8601 date-time format.
Type: string
statusThe 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

NameDescriptionRequired
invoicesDocumentIdThe 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

NameDescription
invoicesDocumentIdThe export document identifier.
Type: string
invoicesDocumentUrlA 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"
}