--- title: "Get a collection instruction's details" method: GET path: "/api/collection-instructions/{instruction_id}/" tags: ["Collection Instructions (Brazil)"] --- # Get a collection instruction's details `GET /api/collection-instructions/{instruction_id}/` ## Request - Base URL: `https://sandbox.belvo.com` - URL: `https://sandbox.belvo.com/api/collection-instructions/{instruction_id}/` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) Get a collection instruction with all of its items and their collection windows. Use it to check each item's `status`, for example when you miss an `item_ready_to_charge` webhook or to find items that ended as `POLICY_EXPIRED`, `CHARGE_REJECTED`, or `FAILED` (Belvo sends no webhook for these statuses). The instruction's own `status` stays `PROCESSING` until you cancel it, even after every item reaches a final status. **Errors:** An `instruction_id` that doesn't exist or doesn't belong to your organization returns a `500` error. An `instruction_id` that is not a UUID returns a `404` error. ## Path parameters - `instruction_id` string, uuid, required ## Response `200` Ok - CollectionInstructionResponse: A collection instruction, with all of its items and their collection windows. - `id` string, uuid, required: The unique identifier of the collection instruction. Use it to get or cancel the instruction. - `link_id` string, uuid, required: The `link.id` whose accounts Belvo monitors for this instruction. - `status` 'PROCESSING' | 'COMPLETED' | 'CANCELLED', required: The status of the collection instruction. Can be one of: - `PROCESSING`: The instruction was created. It stays in this status until you cancel it, even after every item has reached a final status. Check each item's `status` to see how monitoring ended. - `COMPLETED`: Reserved for future use. Belvo does not currently set this status. - `CANCELLED`: You cancelled the instruction. Any items that were still `PENDING` or `PROCESSING` were cancelled too. - `created_at` string, date-time, required: The date and time, in ISO-8601 format (UTC), when Belvo created the instruction. - `updated_at` string, date-time, required: The date and time, in ISO-8601 format (UTC), when the instruction's status last changed. - `items` CollectionItemResponse[], required: The items of this instruction. The order of the items is not guaranteed. - `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 - `401`: Unauthorized - `403`: Permission denied - `404`: Not found - `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/collection-instructions/:instruction_id/get.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)