# Collection Instructions (Brazil) {% admonition type="info" name="Beta" %} Smart Collections is currently in Beta. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %} A collection instruction tells Belvo which amounts you want to collect from a user, and when. It is the first phase of Smart Collections in Brazil. You create an instruction for a user's Open Finance Data Aggregation Link, with one or more **items**. Each item has an `amount` and one or more **collection windows** (`collection_policies`). While a window is open, Belvo checks the balances of the user's accounts several times a day. When one account has enough balance for an item, Belvo sends you the `item_ready_to_charge` webhook, and you create the Charge yourself using Payments (Brazil). These endpoints use your Belvo API keys (`secretId` and `secretPassword`), like the rest of the aggregation API. They don't require a version header. For the statuses, the webhook, and the full flow, see the Smart Collections statuses and webhooks article. ## Crear una instrucción de colección - [POST /api/collection-instructions/](https://developers.belvo.com/es/apis/belvoopenapispec/collection-instructions-(brazil)/createcollectioninstructionbrazil.md): Create a collection instruction for a user's Link. While an item's collection window is open, Belvo checks the balances of the user's accounts several times a day. When one account has at least the item's amount plus BRL 0.01, Belvo sets the item to CHARGE_SETTLED and sends you the item_ready_to_charge webhook. You then create the Charge yourself, using Payments (Brazil). For every item status and the webhook payload, see the Smart Collections statuses and webhooks article. Before you send the request, check that: - The link_id is an active, confirmed Link of your organization, with exactly one data consent. - Every item has at least one collection window that ends in the future. If one item doesn't, Belvo rejects the whole request. - Each policy amount is the same as its item's amount. Belvo doesn't use the policy amount yet. This request is not idempotent, and external_id is not checked for uniqueness. If you retry after a timeout, first list your collection instructions to check whether the first request created one. Errors: Belvo returns a 400 error only for problems with link_id or a body that is not valid JSON. Any other problem returns a 500 error, including a body that doesn't match the schema, an item with no window that ends in the future, a Link that doesn't have exactly one data consent, and a failure to read the Link's accounts. ## List collection instructions - [GET /api/collection-instructions/](https://developers.belvo.com/es/apis/belvoopenapispec/collection-instructions-(brazil)/listcollectioninstructionsbrazil.md): List the collection instructions of your organization. The response is an array of summaries without the items. To see the items and their statuses, get the instruction's details. The response is not paginated: it returns every instruction that matches your filters, in no guaranteed order. Use status, consent_id, created_after, and created_before to keep the response small. Belvo ignores any other query parameter. Errors: A filter value that is not valid (for example, an unknown status or a date that is not YYYY-MM-DD) returns a 500 error. ## Get a collection instruction's details - [GET /api/collection-instructions/{instruction_id}/](https://developers.belvo.com/es/apis/belvoopenapispec/collection-instructions-(brazil)/detailcollectioninstructionbrazil.md): 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. ## Cancel a collection instruction - [PATCH /api/collection-instructions/{instruction_id}/](https://developers.belvo.com/es/apis/belvoopenapispec/collection-instructions-(brazil)/patchcollectioninstructionbrazil.md): Cancel a collection instruction. Send the request without a body. Belvo sets the instruction to CANCELLED and cancels every item that is still PENDING or PROCESSING. Items that already reached a final status, such as CHARGE_SETTLED or COMPLETED, keep their status. Cancelling cannot be undone. To stop monitoring only one item, cancel the item instead (PATCH /api/collection-instructions/{instruction_id}/items/{item_id}/). Belvo doesn't check the instruction's current status, so cancelling an instruction that is already CANCELLED returns 200 again. 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. ## Cancel a collection instruction item - [PATCH /api/collection-instructions/{instruction_id}/items/{item_id}/](https://developers.belvo.com/es/apis/belvoopenapispec/collection-instructions-(brazil)/patchcollectioninstructionitembrazil.md): 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. ## Mark a collection instruction item as complete - [PATCH /api/items/complete/](https://developers.belvo.com/es/apis/belvoopenapispec/collection-instructions-(brazil)/patchcollectioninstructionitemcompletebrazil.md): 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.