BEbelvo
Collection Instructions (Brazil)

Cancel a collection instruction item

Changed on

Cancel one item of a collection instruction. Send the request without a body. Belvo sets the item to CANCELLED and stops checking balances for it. The instruction and its other items are not changed, even if this was the last active item.

You can only cancel an item while it is PENDING or PROCESSING.

Errors: Belvo returns a 500 error when the instruction or the item doesn't exist, the item doesn't belong to the instruction, the instruction doesn't belong to your organization, or the item isn't in a status that allows this operation. An ID that is not a UUID returns a 404 error.

patch/api/collection-instructions/{instruction_id}/items/{item_id}/

Request

Path parameters

instruction_idstring uuid required
Example:c2a6f1d4-7b3e-4f5a-9c8d-1e2f3a4b5c6d

The id of the collection instruction that the item belongs to.

item_idstring uuid required
Example:6512bd43-d9ca-4e6f-8a1b-c3d2e1f0a9b8

The id of the item you want to cancel.

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