Export invoices using the API

Steps

1. Export invoices

Initiates the export invoices process by calling POST /invoices/exports with the desired set of filters to apply. This endpoint will initiate an asynchronous process that will result in a report generation.

The response will include the id of the export. You can use it in order to check the status of the export process.

Request

POST invoices/exports

{
  "filters": {
    "issued_at": {
      "from": "2023-09-01T22:05:48.479Z",
      "to": "2023-09-01T22:05:48.479Z"
    },
    "seller": {
      "id": "acc_44678r08jtm8zbt227tzhc4nw5"
    },
    "buyer": {
      "id": "acc_44678r08jtm8zbt227tzhc4nw5"
    },
    "reference": "634533f5-1050-4f30-b2a1-4aab2401a78b",
    "code": "INV-2024-0001",
    "due_at": {
      "from": "2023-09-01T22:05:48.479Z",
      "to": "2023-09-01T22:05:48.479Z"
    },
    "statuses": [
      "issued"
    ],
    "types": [
      "standard"
    ]
  }
}

Reponse

202 Accepted

{
  "id": "xpt_4ehg1mkv3mvt3256vcn8dspb4h",
  "status": "pending",
  [...]
}

2. Get export status

Make a request to GET /invoices/exports/{export_id} in order to check the status of the export process.

The generation of the report may take some time, so you may need to poll this endpoint until the status is completed (in case of successs) or error (in case of unexpected failure). In the meantime, the status will be pending.

Response of pending export

200 Ok

{
  "id": "xpt_4ehg1mkv3mvt3256vcn8dspb4h",
  "status": "pending",
  [...]
}

Response of failed export

200 Ok

{
  "id": "xpt_4ehg1mkv3mvt3256vcn8dspb4h",
  "status": "error",
  [...]
}

Response of completed export

200 Ok

{
  "id": "xpt_4ehg1mkv3mvt3256vcn8dspb4h",
  "status": "completed",
  "report": {
    "id": "rpt_47g1mkv3mvt3256vcn8dspb4h",
    "url": "https://api.getpaid.io/v2alpha1/invoices/reports/rpt_47g1mkv3mvt3256vcn8dspb4h",
    "expires_at": "2023-09-01T22:05:48.479Z"
  },
  [...]
}

Once the status is completed, a new report field is available in the response. This includes the id of the report, the url to download it and the expires_at date and time.

3. Get report

warning

Please note that the report will be available to be downloaded for a limited time, as indicated by the expires_at file.

Once the export process is completed, you can download the report by making a request to the url provided in the response from step 2, which will be GET /invoices/reports/{report_id}.

The generated report will be returned as a byte array in CSV format, and it will contain the following data - please find in parentheses the associated header in the CSV file:

• The series prefix (series_prefix)
• The invoice code (code)
• The invoice reference (reference)
• The invoice status (status)
• The invoice type (type)
• The invoice issued at date (issued_at)
• The invoice due at date (due_at)
• The seller's registration number (seller_registration_number)
• The seller's legal name (seller_legal_name)
• The buyer's registration number (buyer_registration_number)
• The buyer's legal name (buyer_legal_name)
• The invoice total amount - including taxes (total)
• The invoice base amount - excluding taxes (base)
• The invoice taxes total amount (tax)
• The invoice amounts currency (currency)
• The invoice taxes.
  • If the tax reference is not exempted. For each percentage:
    • The tax reference (taxes_{index}_type)
    • The tax reference (taxes_{index}_reference)
    • The tax percent (taxes_{index}_percent)
    • The tax base (taxes_{index}_base)
    • The tax amount (taxes_{index}_tax)
  • If the tax reference is exempted:
    • The tax reference (taxes_{index}_type)
    • The tax reference (taxes_{index}_reference)
    • The tax base (taxes_{index}_base)
• The invoice metadata. For every field in the metadata:
  • The metadata field name (metadata_{index}_key)
  • The metadata field value (metadata_{index}_value)

Feel free to download a sample of an exported report in order to understand the structure of the CSV file.