# Cancel a collection instruction item

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.

Endpoint: PATCH /api/collection-instructions/{instruction_id}/items/{item_id}/
Version: 1.223.0
Security: basicAuth

## Path parameters:

  - `instruction_id` (string, required)
    The id of the collection instruction that the item belongs to.
    Example: "c2a6f1d4-7b3e-4f5a-9c8d-1e2f3a4b5c6d"

  - `item_id` (string, required)
    The id of the item you want to cancel.
    Example: "6512bd43-d9ca-4e6f-8a1b-c3d2e1f0a9b8"

## Response 200 fields (application/json):

  - `id` (string, 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.
    Example: "8f14e45f-ceea-4e67-a3f2-2a1b9c3d7e10"

  - `amount` (string, required)
    The amount to collect, in BRL, as a decimal string with two decimal places.
    Example: "150.00"

  - `external_id` (string,null, required)
    The reference you sent when you created the item. null if you didn't send one.
    Example: "invoice-2026-11-0042"

  - `status` (string, 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.
    Enum: "PENDING", "PROCESSING", "CHARGE_SETTLED", "POLICY_EXPIRED", "CHARGE_REJECTED", "FAILED", "COMPLETED", "CANCELLED"

  - `created_at` (string, required)
    The date and time, in ISO-8601 format (UTC), when Belvo created the item.
    Example: "2026-11-04T14:30:12.418230Z"

  - `updated_at` (string, 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: "2026-11-04T14:30:12.418230Z"

  - `collection_policies` (array, required)
    The collection windows of the item.

  - `collection_policies.id` (string, required)
    The unique identifier of the collection window.
    Example: "5d41402a-bc4b-4a76-b971-9d911017c592"

  - `collection_policies.start_date` (string, required)
    The first day of the window (YYYY-MM-DD). The window opens at 00:00 UTC on this date.
    Example: "2026-11-05"

  - `collection_policies.end_date` (string, required)
    The last day of the window (YYYY-MM-DD), inclusive. The window closes at the end of this date, in UTC.
    Example: "2026-11-10"

  - `collection_policies.amount` (string, required)
    The amount you sent for this window, in BRL, as a decimal string. Belvo does not use this value yet; the balance check uses the item's amount.
    Example: "150.00"

  - `collection_policies.created_at` (string, required)
    The date and time, in ISO-8601 format (UTC), when Belvo created the window.
    Example: "2026-11-04T14:30:12.418230Z"

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code (permission_denied) that allows you to classify and handle the error programmatically.
    Example: "permission_denied"

  - `message` (string)
    A short description of the error. For permission_denied errors, the description is:

  - You do not have permission to perform this action.
    Example: "You do not have permission to perform this action."

  - `request_id` (string)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    Un código de error único (not_found) que te permite clasificar y manejar el error de manera programática.
    Example: "not_found"

  - `message` (string)
    A short description of the error. For this error, the description is:

  - Not found (404)
    Example: "Not found (404)"

  - `request_id` (string)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    Un código de error único (request_timeout) que te permite clasificar y manejar el error de manera programática.

ℹ️ Consulta nuestro DevPortal para obtener más información sobre cómo manejar errores 408 request_timeout.
    Example: "request_timeout"

  - `message` (string)
    Una breve descripción del error.

Para los errores de request_timeout, la descripción es:

  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code (server_error) that allows you to classify and handle the error programmatically.
    Example: "server_error"

  - `message` (string)
    A short description of the error. For server_error errors, the description is:

  - Server error (500)
    Example: "Server error (500)"

  - `request_id` (string)
    Un ID único de 32 caracteres de la solicitud (que coincide con un patrón regex de: [a-f0-9]{32}). Proporcione este ID al contactar al equipo de soporte de Belvo para acelerar las investigaciones.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"