--- title: "Mark a collection instruction item as complete" method: PATCH path: "/api/items/complete/" tags: ["Collection Instructions (Brazil)"] --- # Mark a collection instruction item as complete `PATCH /api/items/complete/` ## Request - Base URL: `https://sandbox.belvo.com` - URL: `https://sandbox.belvo.com/api/items/complete/` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) 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. ## Request body - union: Identifies the collection instruction item to mark as complete. Send exactly one of `item_id` or `external_id`. - object - `item_id` string, uuid, required: The `id` of the collection instruction item to mark as complete. We recommend this option. - `external_id` string: The `external_id` you sent when you created the item. Belvo searches all the items of your organization, including items of older instructions. If more than one item has this `external_id`, the request fails. Use `item_id` if your `external_id` values can repeat. - object - `item_id` string, uuid: The `id` of the collection instruction item to mark as complete. We recommend this option. - `external_id` string, required: The `external_id` you sent when you created the item. Belvo searches all the items of your organization, including items of older instructions. If more than one item has this `external_id`, the request fails. Use `item_id` if your `external_id` values can repeat. ## Response `200` Ok - CollectionItemResponse: An amount to collect within a collection instruction, with its status and collection windows. - `id` string, 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. - `amount` string, required: The amount to collect, in BRL, as a decimal string with two decimal places. - `external_id` string, 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_at` string, date-time, required: The date and time, in ISO-8601 format (UTC), when Belvo created the item. - `updated_at` string, 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. - `collection_policies` CollectionPolicyResponse[], required: The collection windows of the item. - `id` string, uuid, required: The unique identifier of the collection window. - `start_date` string, date, required: The first day of the window (`YYYY-MM-DD`). The window opens at 00:00 UTC on this date. - `end_date` string, date, required: The last day of the window (`YYYY-MM-DD`), inclusive. The window closes at the end of this date, in UTC. - `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`. - `created_at` string, date-time, required: The date and time, in ISO-8601 format (UTC), when Belvo created the window. ## Other responses - `400`: Bad request error - `401`: Unauthorized - `403`: Permission denied - `408`: Request Timeout - `500`: Server error ## Changes - **2026-10-21** `acb784e42ca0`: 1 info - endpoint added [Operation history](https://skmtc.dev/belvo/apis/belvo-api-docs/changes/api/items/complete/patch.md) --- [API](https://skmtc.dev/belvo/apis/belvo-api-docs.md) - [All operations](https://skmtc.dev/belvo/apis/belvo-api-docs/llms.txt) - [OpenAPI document](https://skmtc.dev/belvo/apis/belvo-api-docs/revisions/acb784e42ca0?raw)