Modify agency bill payments and distributions

After an agency bill payment has been executed, you can update the payment and its distribution, including any distribution items and suspense items. You can modify agency bill payments using Cloud API.

Use the following endpoint to modify agency bill payments.
  • POST /billing/v1/producers/{producerId}/ab-money-rcvds/{agencyBillMoneyRcvdId}/modify

For information about modifying agency bill payments in the BillingCenter user interface, see Agency bill payments.

How BillingCenter handles agency bill payment modification

Agency bill payments must be executed to be modified, and they cannot have been previously modified.

When you modify an agency bill payment, BillingCenter does not update values on the existing payment. Instead, it creates a brand new agency bill payment based on the original. Therefore, modifying a payment results in two payments in the BillingCenter database:
  • The original payment, with the modified field set to true. The original payment cannot be modified again, and BillingCenter preserves it only for record keeping.
  • The modifying payment, created as a new payment with values from the original payment and new values set during the modification. In Cloud API, modifying payments include a moneyBeingModified field, which associates the modifying payment with the original payment.

The BillingCenter user interface only shows the modifying payment, not the original payment. However, BillingCenter Cloud API returns both modifying and original payments when you call the GET /billing/v1/producers/{producerId}/ab-money-rcvds endpoint. See Query for agency bill payments for more.

How BillingCenter handles distribution modification

To modify distribution items and suspense items, include the agencyCyclePayment object in the request body. When agencyCyclePayment is included in the request, it creates a new agency bill distribution on the modifying agency bill payment. You can specify new data for existing distribution items and suspense items in the new agency bill distribution.

Like agency bill payments, when a distribution item or a suspense item is modified, the item itself is not updated. Instead, BillingCenter creates a brand new item based on the original. This results in two items in the BillingCenter database:

  • The original item, with the reversedDate field populated. This item does not appear in the user interface, but it can be retrieved using Cloud API.
  • The modifying item, which has relevant values from the original item and the request. This item appears in the user interface and can be retrieved using Cloud API

When modifying a payment, BillingCenter requires that an id be included for all distribution items and all suspense items, including items that are not being modified. This is explained in the following sections.

Modifying distribution items

If there are distribution items on the distribution, then the agencyPaymentItems array must be included in the agencyCyclePayment object. All the distribution items on the payment must be included in the agencyPaymentItems array. When distribution items are modified, funds are moved in the T-accounts to account for amount differences.

For distribution items, the id of the target invoice item is used to identify the distribution item. For example, if there is a distribution item which targets the invoice item bc:invoiceItem1, the following object must be included in the agencyPaymentItems array:
{
    "invoiceItem": {
        "id": "bc:invoiceItem1"
    }
}

When modifying distribution items, BillingCenter searches for an existing distribution item targeting the specified invoice item. If there is not a matching distribution item, BillingCenter attempts to create a new distribution item. If there is not an appropriate invoice item with the id specified on the modifying distribution item, BillingCenter throws an error. Because there are no other fields specified in this example, BillingCenter does not modify the distribution item.

BillingCenter attempts to match modifying distribution and suspense items to existing items.

Modifying suspense items

If there are suspense items on the distribution, then the agencySuspPmntItems array must be included in the agencyCyclePayment object. All the suspense items on the payment must be included in the array. When a suspense item is modified, no T-accounts are updated, as items in suspense do not have T-accounts.

For suspense items, the id of the suspense item itself is used to identify the suspense item. For example, if the distribution includes a suspense item which targets the suspense item bc:suspItem1, the following entry must be included in the agencySuspPmntItems array:
{
    "id": "bc:suspItem1"
}

Because there are no other fields specified in this example, BillingCenter does not modify the suspense item.

When modifying suspense items, BillingCenter searches for an existing suspense item with the id of the modifying suspense item. If there is not a matching suspense item, BillingCenter attempts to create a new suspense item with the information on the modifying suspense item. If there is not sufficient information to create a new suspense item, BillingCenter throws an error.

Modifying an agency bill distribution example

The following example illustrates modifying distribution items and suspense items on a distribution.

Suppose there is an agency bill payment with two distribution items and two suspense items. The distribution items were distributed to invoice items with ids bc:invoiceItem1 and bc:invoiceItem2. The suspense items have ids bc:suspItem1 and bc:suspItem2.

A caller wants to modify the distribution item targeting invoice item bc:invoiceItem1 and the suspense item bc:suspItem1. No other fields of the agency bill payment are modified. The request looks like this:

Command

POST /billing/v1/producers/bc:433/ab-money-rcvds/bc:698/modify

Request body

{
    "data": {
        "attributes": {       
            "agencyCyclePayment": {
                "agencyPaymentItems": [
                    {
                        "invoiceItem": {
                            "id": "bc:invoiceItem1"
                        },
                        "commissionAmountToApply": {
                            "amount": "10",
                            "currency": "usd"
                        },
                        "disposition": {
                            "code": "autoexception"
                        },
                        "grossAmountToApply": {
                            "amount": "100",
                            "currency": "usd"
                        }
                    },
                    {
                        "invoiceItem": {
                            "id": "bc:invoiceItem2" 
                        }
                    }
                ],
                "agencySuspPmntItems": [
                    {
                        "id": "bc:suspItem1",
                        "commissionAmountToApply": {
                            "amount": "5.00",
                            "currency": "usd"
                        },
                        "currency": {
                            "code": "usd"
                        },
                        "grossAmountToApply": {
                            "amount": "50.00",
                            "currency": "usd"
                        }
                    }, 
                    {
                        "id": "bc:suspItem2"                      
                    }
                ]
            }
        }
    }
}

As a result of the modification, there are now three distribution items and three suspense items:

  • Distribution item for invoice item bc:invoiceItem1 (reversed)
  • Distribution item for invoice item bc:invoiceItem1 (the modifying item)
  • Distribution item for invoice item bc:invoiceItem2 (unchanged by the modification)
  • Suspense item bc:suspItem1 (reversed)
  • Suspense item bc:suspItem1 (the modifying item)
  • Suspense item bc:suspItem2 (unchanged by the modification)

Detailed agency bill payment modification example

Select fields on the payment can be modified, such as amount, name, and payment instrument.

The following call demonstrates the fields you can modify on an agency bill payment. It also modifies the distribution of the payment, including one modifying distribution item, five unmodified distribution items, one modifying suspense item, and one unmodified suspense item.

Command
POST /billing/v1/producers/bc:48/ab-money-rcvds/bc:1091/modify
Request body
{
    "data": {
        "attributes": {
            "agencyCyclePayment": {
                "agencyPaymentItems": [
                    {
                        "invoiceItem": {
                            "id": "bc:Stzu1GOy9QWr1TForCR8r"
                        },
                        "commissionAmountToApply": {
                            "amount": "10",
                            "currency": "usd"
                        },
                        "disposition": {
                            "code": "autoexception"
                        },
                        "grossAmountToApply": {
                            "amount": "100",
                            "currency": "usd"
                        }
                    },
                    {
                        "invoiceItem": {
                            "id": "bc:SDHrGwNQ-znIhsdqvHaIq" 
                        }
                    },
                    {
                        "invoiceItem": {
                            "id": "bc:S5f1peqGipO9il_dxbiUH" 
                        }
                    },
                    {
                        "invoiceItem": {
                            "id": "bc:SM5n1fVX-Fxkne2DqdfVn" 
                        }
                    },
                    {
                        "invoiceItem": {
                            "id": "bc:Sp56RT7qo90ZxbeduF-fc" 
                        }
                    },
                    {
                        "invoiceItem": {
                            "id": "bc:Svs_gl8sbQwgmIf-Skma3" 
                        }
                    }
                ],
                "agencySuspPmntItems": [
                    {
                        "id": "bc:Sc7WCO5jODIttDN6cZijb",
                        "commissionAmountToApply": {
                            "amount": "5.00",
                            "currency": "usd"
                        },
                        "currency": {
                            "code": "usd"
                        },
                        "grossAmountToApply": {
                            "amount": "100.00",
                            "currency": "usd"
                        },
                        "policyNumber": "bc:192843"
                    }, 
                    {
                        "id": "bc:Swx2POATmF9BJutS2DUmZ"                        
                    }
                ]
            }, 
            "amount": {
                "amount": "300",
                "currency": "usd"
            },
            "name": "Updated January payment",
            "description": "Updated January payment and distribution",
            "paymentInstrument": {
                "id": "bc:SqHIzlOLI89qiZMapbZGf"
            },
            "receivedDate": "2025-06-12",
            "referenceNumber": "bc:434923408"
        }
    }
}

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

As a result of the modification, the modified payment has:
  • Seven distribution items - One of them is reversed, and does not appear in the user interface. The other six are not reversed. One of the six items is a modifying distribution item.
  • Three suspense items - One of them is reversed, and does not appear in the user interface. The other two are not reversed. One of the six items is a modifying distribution item.
  • An amount of $300.
  • A new name, description, payment instrument, received date, and reference number.

Modifying saved agency bill payments

If a payment is in the saved state, modifying it does not create a new payment entity in the database, and it does not create new distribution items or suspense items. Instead, BillingCenter modifies the original payment entity and any of its distribution or suspense items directly. This is because no transactions have occurred for the saved payment, and therefore no new transactions must be created to offset the original payment transactions.