Querying for disbursements

To query for disbursements, use the following endpoints:
  • GET /billing/v1/disbursements
  • GET billing/v1/disbursements/{disbursementId}

The GET /billing/v1/disbursements endpoint is "potentially large". Cloud API returns an error if you attempt to sort on this endpoint and the sort cannot be accomplished efficiently. For more information, see Potentially large endpoints.

Filtering results

Because the /disbursements endpoint returns all the disbursements in an instance of BillingCenter, you might want to add query parameters to the request. You can use query parameters to customize the retrieved disbursements by targeting properties such as disbursementNumber, dueDate, mailTo, payTo, status, and so on.

For example, to return only the disbursements where the payee is "John Smith", you could add the following query parameter: ?filter=payTo:eq:John%20Smith.

You can also use the custom filter assignedUserId to retrieve only disbursements which have open approval activities assigned to a user. The following example uses this filter to retrieve all the open disbursements assigned to a user with id bc:SO9ElvEWDSCxZnSw1orIc.

Command
GET /billing/v1/disbursements/?filter=assignedUserId:eq:bc::SO9ElvEWDSCxZnSw1orIc
Response
{
    "count": 3,
    "data": [
        {
            "attributes": {
                "account": {
                    "displayName": "PA-12345",
                    "id": "bc:S3dlt88iFMLiifyjVakna",
                    "type": "Account",
                    "uri": "/billing/v1/accounts/bc:S3dlt88iFMLiifyjVakna"
                },
                "address": "111 Address Lane Suite 1, City, CO 12345",
                "amount": {
                    "amount": "200.00",
                    "currency": "usd"
                },
                "assignedUser": {
                    "displayName": "Super Visor",
                    "id": "bc:SO9ElvEWDSCxZnSw1orIc",
                    "type": "User",
                    "uri": "/admin/v1/users/bc:SO9ElvEWDSCxZnSw1orIc"
                },
                "disbursementNumber": "1000000006",
                "dueDate": "2024-06-06",
                "id": "bc:Sizn9c0btX8QDLB_binMq",
                "mailTo": "John Smith",
                "payTo": "John Smith",
                "paymentInstrument": {
                    "displayName": "Responsive",
                    "id": "bc:SfArXUmegPWi04CvYNyFk",
                    "type": "UniversalPaymentInstrument",
                    "uri": "/billing/v1/universal-payment-instruments/bc:SfArXUmegPWi04CvYNyFk"
                },
                "reason": {
                    "code": "Cancellation",
                    "name": "Cancellation"
                },
                "status": {
                    "code": "AwaitingApproval",
                    "name": "Awaiting Approval"
                },
                "unappliedFund": {
                    "displayName": "Default",
                    "id": "bc:S7ErFtlGkK4U1XLK7it_M",
                    "type": "UnappliedFund",
                    "uri": "/billing/v1/accounts/bc:S3dlt88iFMLiifyjVakna/unapplied-funds/bc:S7ErFtlGkK4U1XLK7it_M"
                }
            },
            ...
        },
        {
            "attributes": {
                "account": {
                    "displayName": "GL-12345",
                    "id": "bc:SgAtMMpK2-ck3ig6Tmj7P",
                    "type": "Account",
                    "uri": "/billing/v1/accounts/bc:SgAtMMpK2-ck3ig6Tmj7P"
                },
                "address": "111 Address Lane Suite 1, City, CO 12345",
                "amount": {
                    "amount": "150.00",
                    "currency": "usd"
                },
                "assignedUser": {
                    "displayName": "Super Visor",
                    "id": "bc:SO9ElvEWDSCxZnSw1orIc",
                    "type": "User",
                    "uri": "/admin/v1/users/bc:SO9ElvEWDSCxZnSw1orIc"
                },
                "disbursementNumber": "1000000009",
                "dueDate": "2024-03-13",
                "id": "bc:S3MnVHtdy-oalJWExYhEf",
                "mailTo": "Jane Smith",
                "payTo": "Jane Smith",
                "paymentInstrument": {
                    "displayName": "Responsive",
                    "id": "bc:SfArXUmegPWi04CvYNyFk",
                    "type": "UniversalPaymentInstrument",
                    "uri": "/billing/v1/universal-payment-instruments/bc:SfArXUmegPWi04CvYNyFk"
                },
                "reason": {
                    "code": "Cancellation",
                    "name": "Cancellation"
                },
                "status": {
                    "code": "AwaitingApproval",
                    "name": "Awaiting Approval"
                },
                "unappliedFund": {
                    "displayName": "Default",
                    "id": "bc:SPzPyau2t_GsPpVXiALYq",
                    "type": "UnappliedFund",
                    "uri": "/billing/v1/accounts/bc:SgAtMMpK2-ck3ig6Tmj7P/unapplied-funds/bc:SPzPyau2t_GsPpVXiALYq"
                }
            },
            ...
        },
        ...
    ],
    ...
}