BEbelvo
Collection Instructions (Brazil)

Get a collection instruction's details

Changed on

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.

get/api/collection-instructions/{instruction_id}/

Request

Path parameters

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

The id of the collection instruction you want to get.

Response

Ok

idstring uuid required

The unique identifier of the collection instruction. Use it to get or cancel the instruction.

link_idstring 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_atstring date-time required

The date and time, in ISO-8601 format (UTC), when Belvo created the instruction.

updated_atstring date-time required

The date and time, in ISO-8601 format (UTC), when the instruction's status last changed.

Example response

{
  "id": "c2a6f1d4-7b3e-4f5a-9c8d-1e2f3a4b5c6d",
  "link_id": "3b979abb-fd60-4d15-a655-8f462ca4ea8f",
  "status": "PROCESSING",
  "created_at": "2026-11-04T14:30:12.418230Z",
  "updated_at": "2026-11-04T14:30:12.418230Z",
  "items": [
    {
      "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