Modify agency bill promises and distributions

How BillingCenter handles agency bill promise modification

When you modify an agency bill promise, BillingCenter does not update values on the existing promise. Instead, it creates a new version of the promise with a new id. Unlike agency bill payment modification, promise modification creates new versions of the promise and all items on the promise, even if some items are not changed. This includes all promise items and all suspense promise items on the promise.

How BillingCenter handles distribution modification

To modify promise items and suspense promise items, include the agencyCyclePromise object in the request body. When agencyCyclePromise is included in the request, it creates a new distribution on the modified agency bill promise.

When modifying a promise, BillingCenter requires that you include references for all existing agency promise items and suspense promise items in the relevant arrays, including items that are not being modified. This is explained in the following sections.

You can add new agency promise items or suspense promise items. You cannot remove agency promise items or suspense promise items. To change the amount of an item, update the relevant amount field on the item.

Modifying agency promise items

If there are agency promise items on the promise, then the agencyPromiseItems array must be included in the agencyCyclePromise object. All the distribution items on the promise must be included in the agencyPromiseItems array.

For distribution items, the id of the target invoice item is used to identify the distribution item. For example, if there is an agency promise item that targets invoice item bc:invoiceItem1, include the following object in the agencyPromiseItems array:

{
  "invoiceItem": {
    "id": "bc:invoiceItem1"
  }
}

If you include only the invoice item id, BillingCenter keeps the item values unchanged in the modified promise.

Modifying suspense promise items

You can modify suspense promise items when modifying an agency bill promise.

{
    "id": "bc:suspItem1"
}

If you include only the suspense promise item id, BillingCenter keeps the item values unchanged in the modified promise.

Detailed agency bill promise modification example

Suppose that you have created a direct bill payment and distribution as specified in Create an agency bill promise with distribution. The promise has two agency promise items: one with a $77.73 gross and one with a $95.00 gross.

You want to make the following changes to that distribution:

• Add an additional agency promise item with a gross of 105.00 to the distribution

• Change the disposition of the promise item with 77.73 gross

• Leave the item with 95.00 gross unchanged

Additionally, you want to update the amount and the received date.

The following example demonstrates this:

Command

POST /billing/v1/producers/bc:112938/ab-promised-monies/bc:12993390/modify

Request body

{
    "data": {
        "attributes": {
            "agencyCyclePromise": {
                "agencyPromiseItems": [
                    {
                        "invoiceItem": {
                            "id": "bc:105invoiceitem"
                        },
                        "commissionAmountToApply": {
                            "amount": "10.50",
                            "currency": "usd"
                        },
                        "disposition": {
                            "code": "writeoff"
                        },
                        "currency": {
                            "code": "usd"
                        },
                        "grossAmountToApply": {
                            "amount": "105.00",
                            "currency": "usd"
                        },
                        "paymentComments": "Updated payment"
                    },
                    {
                        "invoiceItem": {
                            "id": "bc:77invoiceitem"
                        },
                        "disposition": {
                            "code": "autoexception"
                        }
                    },
                    {
                        "invoiceItem": {
                            "id": "bc:95invoiceitem"
                        }
                    }
                ]
            },
            "amount": {
                "amount": "219.96",
                "currency": "usd"
            },
            "receivedDate": "2026-03-18"
        }
    }
}

The request returns the modified promise and a 200 response. The modified promise has a different id than the original promise, because it is a different entity in the database.

As a result of this modification, there are five agency promise items in the database: two reversed items from the original promise and three new items created as part of the modified promise. We can understand the agency promise items through the invoice items they target:

• bc:95invoiceitem: There are two distribution items that target this invoice item. One is reversed and preserved only for record keeping. The other one, created as a result of the promise modification above, has the same values as the reversed distribution item, but it has a different id.

• bc:77invoiceitem: There are two distribution items that target this invoice item. One is reversed and preserved only for record keeping. The other one, created as a result of the promise modification above, has the same values as the reversed invoice item, except for it has a different id and a new disposition of autoexception.

• bc:105invoiceitem: There is only one distribution item that targets this invoice item. It has the fields specified in the promise modification above.