BEbelvo
Collection Instructions (Brazil)

Mark a collection instruction item as complete

Changed on

Mark an item as complete when you no longer need Belvo to monitor it, for example because the user paid the amount outside Belvo. Belvo sets the item to COMPLETED and stops checking balances for it.

Identify the item with exactly one of item_id or external_id. We recommend item_id: Belvo searches external_id across all the items of your organization, and the request fails if more than one item has the same value.

You can only mark an item as complete while it is PENDING. An item that is PROCESSING (a balance check is running) or already in a final status, including CHARGE_SETTLED, can't be marked as complete.

Errors: Belvo returns a 400 error only when the body is not valid JSON. It returns a 500 error when you send both or neither of item_id and external_id, when no item of your organization matches, when more than one item has the external_id, or when the item isn't in a status that allows this operation.

patch/api/items/complete/

Request

Request body

OR

Example request

{
  "item_id": "8f14e45f-ceea-4e67-a3f2-2a1b9c3d7e10",
  "external_id": "invoice-2026-11-0042"
}

Response

Ok

idstring uuid required

The unique identifier of the item. Belvo sends it in the item_ready_to_charge webhook, and you use it to cancel the item or mark it as complete.

amountstring required

The amount to collect, in BRL, as a decimal string with two decimal places.

external_idstring nullable required

The reference you sent when you created the item. null if you didn't send one.

status'PENDING' | 'PROCESSING' | 'CHARGE_SETTLED' | 'POLICY_EXPIRED' | 'CHARGE_REJECTED' | 'FAILED' | 'COMPLETED' | 'CANCELLED' required

The status of the collection instruction item. Can be one of:

  • PENDING: The item is waiting for its next scheduled balance check. Every new item starts in this status.
  • PROCESSING: A balance check for the item is in progress. After the check, the item returns to PENDING if no account had enough balance and a collection window is still open.
  • CHARGE_SETTLED: One of the user's accounts had enough balance, and Belvo sent you the item_ready_to_charge webhook. Monitoring stops. This status does not mean that a payment was made: you create the Charge yourself, using Payments (Brazil). If Belvo can't deliver the webhook, the item still moves to this status, so also check the instruction's details regularly.
  • POLICY_EXPIRED: All of the item's collection windows ended before any account had enough balance. Belvo does not send a webhook for this status.
  • CHARGE_REJECTED: Belvo could not read the balance of any of the user's accounts (for example, because the data consent is no longer valid). Belvo does not send a webhook for this status.
  • FAILED: An internal error stopped monitoring. Belvo does not send a webhook for this status.
  • COMPLETED: You marked the item as complete (for example, because you collected the amount outside Belvo), so Belvo stopped monitoring it.
  • CANCELLED: You cancelled the item, or the whole collection instruction.

CHARGE_SETTLED, POLICY_EXPIRED, CHARGE_REJECTED, FAILED, COMPLETED, and CANCELLED are final statuses.

created_atstring date-time required

The date and time, in ISO-8601 format (UTC), when Belvo created the item.

updated_atstring date-time required

The date and time, in ISO-8601 format (UTC), when Belvo last updated the item. Belvo updates the item at every balance check, so for a PENDING item this is usually the time of its last check.

Example response

{
  "id": "8f14e45f-ceea-4e67-a3f2-2a1b9c3d7e10",
  "amount": "150.00",
  "external_id": "invoice-2026-11-0042",
  "status": "PENDING",
  "created_at": "2026-11-04T14:30:12.418230Z",
  "updated_at": "2026-11-04T14:30:12.418230Z",
  "collection_policies": [
    {
      "id": "5d41402a-bc4b-4a76-b971-9d911017c592",
      "start_date": "2026-11-05",
      "end_date": "2026-11-10",
      "amount": "150.00",
      "created_at": "2026-11-04T14:30:12.418230Z"
    }
  ]
}

Changes