Add items to a draft Boleto Charge batch

PUT

https://tenant.api.corpx.com/v1/accounts/:accountId/boleto/charge/batches/:batchId/items

PUT

/v1/accounts/:accountId/boleto/charge/batches/:batchId/items

curl -X PUT https://tenant.api.corpx.com/v1/accounts/accountId/boleto/charge/batches/batchId/items \
     -H "X-Tenant-Id: X-Tenant-Id" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "items": [
    {
      "identifier": "pedido-1001",
      "dueDate": "2026-10-23",
      "amount": {
        "nominal": 150.75,
        "currency": "BRL"
      },
      "payer": {
        "name": "Maria da Silva",
        "personType": "person",
        "taxNumber": "52998224725"
      }
    },
    {
      "identifier": "pedido-1002",
      "dueDate": "2026-10-24",
      "amount": {
        "nominal": 89.9,
        "currency": "BRL"
      },
      "payer": {
        "name": "Empresa Exemplo Ltda",
        "personType": "company",
        "taxNumber": "12345678000190"
      }
    }
  ]
}'

{
  "batchId": "bcb_01J8Y7C8D9E0F1G2H3J4",
  "name": "Cobranças de setembro",
  "status": "DRAFT",
  "totalItems": 102,
  "quotaReserved": 0,
  "statistics": {
    "generation": {
      "total": 102,
      "pending": 102,
      "processing": 0,
      "issued": 0,
      "failed": 0,
      "progressPercentage": 0
    },
    "payment": {
      "issued": 0,
      "paid": 0,
      "unpaid": 0,
      "overdue": 0,
      "paidAmount": 0,
      "conversionRate": 0
    }
  },
  "createdAt": "2026-09-24T14:08:12Z",
  "updatedAt": "2026-09-24T14:09:00Z",
  "items": [],
  "page": 1,
  "pageSize": 50,
  "totalPages": 3,
  "hasNext": true
}

Atomically appends 1–50 JSON items to a DRAFT batch. Every item uses the same request shape as single issuance and therefore requires its own identifier. A batch can contain at most 5,000 items.

Validation or an identifier conflict rejects the entire chunk: no item from that request is stored. Adding items consumes no issuance quota.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequired

Account identifier.

batchIdstringRequired

Boleto Charge batch identifier returned by the create endpoint.

Request

This endpoint expects an object.

itemslist of objectsRequired

Atomic chunk of boleto issuance requests.

Response

Entire chunk appended

batchIdstring

Batch identifier.

namestring

Optional operator-facing name; empty when omitted.

statusenum

Batch lifecycle. Only DRAFT is editable. COMPLETED, PARTIAL_FAILED, and FAILED are terminal for issuance attempts; individual boleto registration and payment continue afterwards.

totalItemsinteger0-5000

Number of staged items.

quotaReservedinteger0-5000

Slots permanently reserved when dispatch was admitted.

statisticsobject

Current generation progress and payment conversion.

createdAtdatetime

Draft creation instant, in UTC.

updatedAtdatetime

Last persisted batch/statistics update, in UTC.

itemslist of objects

Current page of staged items and issuance results.

pageinteger

Current item page.

pageSizeinteger

Requested item page size.

totalPagesinteger

Number of item pages.

hasNextboolean

Whether another item page exists.

dispatchedAtdatetime or nullOptional

Instant quota was reserved and the batch was queued.

completedAtdatetime or nullOptional

Instant every issuance attempt reached an outcome.

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

Authentication

Path parameters

Headers

Request

Response

Errors