List the items of an income invoice batch

curl --request GET \
  --url https://api.gigstack.io/v2/invoices/income/batch/{id}/items \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.gigstack.io/v2/invoices/income/batch/{id}/items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gigstack.io/v2/invoices/income/batch/{id}/items"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "success": true,
  "data": {
    "data": [
      {
        "index": 0,
        "idempotency_key": "order-2026-09-000123",
        "status": "stamped",
        "invoice_id": "B0C3E4F2-1A2B-4C5D-9E8F-0123456789AB",
        "uuid": "B0C3E4F2-1A2B-4C5D-9E8F-0123456789AB",
        "error": null,
        "attempts": 1
      },
      {
        "index": 1,
        "idempotency_key": "order-2026-09-000124",
        "status": "duplicate",
        "invoice_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "uuid": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "error": null,
        "attempts": 1
      },
      {
        "index": 2,
        "idempotency_key": "order-2026-09-000125",
        "status": "failed",
        "invoice_id": null,
        "uuid": null,
        "error": {
          "code": "CFDI40147",
          "message": "Error al timbrar la factura: CFDI40147 - El campo UsoCFDI no es válido [pcs_8f2a1c]"
        },
        "attempts": 1
      },
      {
        "index": 3,
        "idempotency_key": "order-2026-09-000126",
        "status": "queued",
        "invoice_id": null,
        "uuid": null,
        "error": null,
        "attempts": 2
      }
    ],
    "next": "3",
    "has_more": true
  },
  "timestamp": 1790781000000
}

Invoices

List the items of an income invoice batch

One entry per accepted item, in request order (ascending index), with its status and, once issued, its invoice. Items rejected up front are not listed; they are in the batch’s rejected.

Cursor pagination: pass data.next back as next while data.has_more is true. The cursor is the last index of the page, so pages never overlap or skip items while statuses change. Filter with status, for example status=failed to list only what needs fixing.

GET

invoices

income

batch

{id}

items

List the items of an income invoice batch

curl --request GET \
  --url https://api.gigstack.io/v2/invoices/income/batch/{id}/items \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.gigstack.io/v2/invoices/income/batch/{id}/items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gigstack.io/v2/invoices/income/batch/{id}/items"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "success": true,
  "data": {
    "data": [
      {
        "index": 0,
        "idempotency_key": "order-2026-09-000123",
        "status": "stamped",
        "invoice_id": "B0C3E4F2-1A2B-4C5D-9E8F-0123456789AB",
        "uuid": "B0C3E4F2-1A2B-4C5D-9E8F-0123456789AB",
        "error": null,
        "attempts": 1
      },
      {
        "index": 1,
        "idempotency_key": "order-2026-09-000124",
        "status": "duplicate",
        "invoice_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "uuid": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "error": null,
        "attempts": 1
      },
      {
        "index": 2,
        "idempotency_key": "order-2026-09-000125",
        "status": "failed",
        "invoice_id": null,
        "uuid": null,
        "error": {
          "code": "CFDI40147",
          "message": "Error al timbrar la factura: CFDI40147 - El campo UsoCFDI no es válido [pcs_8f2a1c]"
        },
        "attempts": 1
      },
      {
        "index": 3,
        "idempotency_key": "order-2026-09-000126",
        "status": "queued",
        "invoice_id": null,
        "uuid": null,
        "error": null,
        "attempts": 2
      }
    ],
    "next": "3",
    "has_more": true
  },
  "timestamp": 1790781000000
}

Authorizations

Authorization

string

header

required

Authentication Method: HTTP Bearer token.

The runtime requires the literal Bearer prefix — a bare token in the Authorization header is rejected with 401 unauthorized.

Header Format: Authorization: Bearer YOUR_API_KEY

Your API key is a JWT. Live keys operate on live data (livemode: true); test keys operate on isolated test data (livemode: false).

Get your key at: app.gigstack.pro/settings?tab=api

Errors: credential failures are answered by the authentication layer with a raw { "message": … } body, not the standardized envelope — 401 for a missing, malformed or expired token, 403 for a revoked key or a plan without API access. See the Unauthorized and AuthForbidden responses.

Path Parameters

string

required

Batch id.

Query Parameters

team

string

gigstack Connect: Target team ID for multi-team access.

Requires gigstack Connect enabled on your team and shared billing account.

Also requires the multipleIssuerAccounts feature on your plan. Requests targeting a team other than the one your API key belongs to return 403 without it.

Only API keys can use it: an OAuth access token sent with another team's id is rejected with 403 Team mismatch with OAuth token.

Optional — omit it entirely unless you are acting on another team. It deliberately carries no example value so generated snippets do not emit ?team=undefined; when the parameter is absent, the team is derived from your API key.

Example: ?team=team_xyz789

limit

integer

default:100

Items per page (default 100, 1-500). Anything else is 400 invalid_limit.

Required range: 1 <= x <= 500

string

Cursor from the previous page's data.next. Omit for the first page. An invalid one is 400 invalid_cursor.

status

enum<string>

Only items in this status. queued covers every item still in flight. Any other value is 400 invalid_status. Omit for all items.

queued: waiting for, or in, a stamping attempt. An attempt that failed for a temporary reason (PAC unavailable, its answer lost) keeps the item queued and is retried, up to 6 attempts.
stamped: the invoice was issued by this batch. uuid and invoice_id are set.
failed: no invoice was issued. error says why.
duplicate: an invoice already existed under this idempotency_key (an earlier batch, a single POST /invoices/income, or a redelivery of this item). uuid names it; nothing was issued or charged again.
needs_review: the PAC could not confirm whether the invoice was stamped. It is never retried automatically, so it cannot be issued twice; contact support with the batch id and index.

Available options:

queued,

stamped,

failed,

duplicate,

needs_review

Example:

"stamped"

Response

A page of items. Note the nesting: the array is at data.data, the cursor at data.next.

Standardized success envelope emitted by sendSuccessResponse.

success

enum<boolean>

required

Available options:

true

Example:

true

data

object

required

The operation payload.

Show child attributes

timestamp

integer<int64>

required

Server time in epoch milliseconds (Luxon.now().toMillis()).

Example:

1767225600000

message

string

Human-readable summary. Present only when the handler supplies one.

Example:

"Operation completed successfully"

Clients

Services

Descarga Masiva SAT

Invoices

Payments

Receipts

Retentions

Teams

Users

Webhooks

Catalogs

Auth

SAT Lists

Documents

Platform Payouts

List the items of an income invoice batch

Authorizations

Path Parameters

Query Parameters

Response