Create an agency bill promise with distribution

Use the following endpoint to create an agency bill promise:
  • POST /billing/v1/producers/{producerId}/ab-promised-monies

Whenever you create an agency bill promise, you must also specify the distribution of the agency bill promise. This means you must specify the allocation of the funds to invoice items or suspense items.

Fields required for creating the promise

The following fields are required:

Field Type Description
amount MonetaryAmount object The net amount of the agency bill promise.
currency Typekey reference to the Currency typelist The currency of the promise.
agencyCyclePromise Object Specifies the distribution of the promise.
receivedDate String The date the agency bill promise was received, in the format YYYY-MM-DD.

Fields required for creating the distribution

You must include a distribution in the agencyCyclePromise object in the POST request. This object has the following required fields:

  • agencyPromiseItems or agencySuspPromiseItems or both—both are arrays of objects
  • currency: the currency of the distribution
Note: This topic only discusses agency promise items, which are used to specify how promise funds are distributed to invoice items. You can also include agency suspense promise items using the agencySuspPromiseItems object. For information on agency bill suspense items in Cloud API, see Agency suspense promise items.

Each object in the agencyPromiseItems array specifies the promise distribution for a single invoice item. The following fields are required for each object in the agencyPromiseItems array:

Field Type Description
invoiceItem Object containing a simple reference to an invoice item’s id The id of the target invoice item.
commissionAmountToApply Monetary amount object The commission that the producer intends to withhold for that invoice item.
grossAmountToApply Monetary amount object The gross amount that the producer intends to apply to that invoice item.
currency Typekey reference to the Currency typelist The currency of the promise distribution for the invoice item.
disposition Typekey reference to the DistItemDisposition typelist The action BillingCenter takes to address invoice items that have been underpaid or overpaid, such as creating exceptions or writing off the difference. See Underpaying invoice items in the Cloud API Developer Guide for an overview of how the different values affect behavior.

Finding the gross and commission amounts due for an invoice item

You can find the gross and commission due on an invoice item using the GET /billing/v1/charges/{chargeId}/invoice-items/{invoiceItemId} endpoint.

The following fields on invoice items are useful when calculating promised distribution amounts:

  • amount - the gross amount on that invoice item
  • primaryCommissionAmount - the commission amount that the producer is expected to retain
  • grossSettled - the gross amount on the invoice item that has been settled (when subtracted from the gross amount, can be used to calculate the unpaid gross for the invoice item)
  • primaryCommissionReserve - the unpaid commission for the invoice

For more, see Working with invoice items.

Example promise and distribution

The following creates an agency bill promise and includes two agency promise items, each specifying how the promised money is to be distributed to an invoice item.

Command
POST /billing/v1/producers/bc:112938/ab-promised-monies
Request body
{
    "data": {
        "attributes": {
            "agencyCyclePromise": {
                "agencyPromiseItems": [
                    {
                        "invoiceItem": {
                            "id": "bc:95invoiceitem"
                        },
                        "commissionAmountToApply": {
                            "amount": "9.50",
                            "currency": "usd"
                        },
                        "currency": {
                            "code": "usd"
                        },
                        "disposition": {
                            "code": "autoexception"
                        },
                        "grossAmountToApply": {
                            "amount": "95.00",
                            "currency": "usd"
                        },
                        "paymentComments": "Positive gross"
                    },
                    {
                        "invoiceItem": {
                            "id": "bc:77invoiceitem"
                        },
                        "commissionAmountToApply": {
                            "amount": "7.77",
                            "currency": "usd"
                        },
                        "currency": {
                            "code": "usd"
                        },
                        "disposition": {
                            "code": "autoexception"
                        },
                        "grossAmountToApply": {
                            "amount": "77.73",
                            "currency": "usd"
                        },
                        "paymentComments": "Positive gross"
                    }
                ],
                "currency": {
                    "code": "usd"
                }
            },
            "name": "promisedemo",
            "amount": {
                "amount": "155.46",
                "currency": "usd"
            },
            "currency": {
                "code": "usd"
            },
            "receivedDate": "2026-03-18"
        }
    }
}

Creating a saved agency bill promise

A saved promise is a set of information pertaining to the draft of a promise. When you save a promise, BillingCenter stores information about the promise, including any distribution information. But BillingCenter does not distribute the promise.

To create a saved promise, set saved to true in the payload:

{
    "data": {
        "attributes": {
        "saved": true,
            "agencyCyclePromise": {
                "agencyPromiseItems": [
                    {
                        "invoiceItem": {
                            "id": "bc:SsojqlbQ-EOUlmOtrjTdv"
                        },
                        "commissionAmountToApply": {
                            "amount": "9.50",
                            "currency": "usd"
                        },
                        "currency": {
                            "code": "usd"
                        },
                        "disposition": {
                            "code": "autoexception"
                        },
                        "grossAmountToApply": {
                            "amount": "95.00",
                            "currency": "usd"
                        },
                        "paymentComments": "Positive gross"
                    },
                    {
                        "invoiceItem": {
                            "id": "bc:SW8ZlNJnlKBZb24Xq3g-v"
                        },
                        "commissionAmountToApply": {
                            "amount": "7.77",
                            "currency": "usd"
                        },
                        "currency": {
                            "code": "usd"
                        },
                        "disposition": {
                            "code": "autoexception"
                        },
                        "grossAmountToApply": {
                            "amount": "77.73",
                            "currency": "usd"
                        },
                        "paymentComments": "Positive gross"
                    }
                ],
                "currency": {
                    "code": "usd"
                }
            },
            "name": "promisedemo",
            "amount": {
                "amount": "155.46",
                "currency": "usd"
            },
            "currency": {
                "code": "usd"
            },
            "receivedDate": "2026-03-18"
        }
    }
}

Retrieve promise distribution information

After a promise has been distributed, you can retrieve information about the distribution. This information is captured in agency cycle promise objects and agency promise items.
  • An agency cycle promise object, used to record the total funds distributed for the promise. The BillingCenter user interface uses the term agency bill distribution.
  • Agency promise item objects, which are children of agency cycle promises, used to record the funds distributed to each invoice item in the agency cycle promise. These objects are sometimes called promise distribution items or just distribution items.

The terms agency cycle promise and agency promise item do not appear in the user interface. Rather, they reflect the names of the entities in the data model. The information contained in these objects can be found in the agency bill promise distribution information in BillingCenter.

Retrieve agency cycle promises

Retrieve an agency cycle promise using one of the following endpoints:
  • GET /billing/v1/producers/{producerId}/ab-promised-monies/{abPromisedMoneyId}/agency-cycle-promises
  • GET /billing/v1/producers/{producerId}/ab-promised-monies/{abPromisedMoneyId}/agency-cycle-promises/{agencyCyclePromiseId}
Note: Typically, there is no more than one agency cycle promise for an agency bill promise, so the two endpoints often return the same agency cycle promise object (if the promise was distributed). Both the collection GET and the element GET are provided for data model consistency with other Cloud API endpoints.

The following is an example of retrieving the agency cycle promise on an agency bill promise. It uses the collection GET endpoint, so it retrieves an array with only one item in it.

Command
GET /billing/v1/producers/bc:Soa-8C6B6P5nX_Okwwz3q/ab-promised-monies/bc:S6dekhxcM2ksOBbBzeH3A/agency-cycle-promises

Response

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "currency": {
                    "code": "usd",
                    "name": "USD"
                },
                "distributedDate": "2026-03-21T00:41:13.957Z",
                "frozenByArchiving": false,
                "id": "bc:S4q6Bjh-6NHqrYV5UrWO4",
                "netDistributedToInvoiceItems": {
                    "amount": "73.64",
                    "currency": "usd"
                },
                "netInSuspense": {
                    "amount": "0.00",
                    "currency": "usd"
                }
            },
            "checksum": "0",
            "links": {
                "self": {
                    "href": "/billing/v1/producers/bc:Soa-8C6B6P5nX_Okwwz3q/ab-promised-monies/bc:S6dekhxcM2ksOBbBzeH3A/agency-cycle-promises/bc:S4q6Bjh-6NHqrYV5UrWO4",
                    "methods": [
                        "get"
                    ]
                }
            }
        }
    ],
    ...
}

Retrieving agency promise items

Retrieve agency promise items using the following endpoints:

  • GET /billing/v1/producers/{producerId}/ab-promised-monies/{abPromisedMoneyId}/agency-cycle-promises/{agencyCyclePromiseId}/agency-promise-items
  • GET /billing/v1/producers/{producerId}/ab-promised-monies/{abPromisedMoneyId}/agency-cycle-promises/{agencyCyclePromiseId}/agency-promise-items/{agencyPromiseItemId}

The following example retrieves a collection of promise items for an agency cycle promise.

Command
GET /billing/v1/producers/bc:SzxS3sNd-8fS7xtjDhHWY/ab-promised-monies/bc:SASghiV2-OBXvOXaWezcT/agency-cycle-promises/bc:SP-VBplQFTA-or-1z0liD/agency-promise-items

Response

{
    "count": 2,
    "data": [
        {
            "attributes": {
                "appliedDate": "2026-03-21T05:04:46.605Z",
                "commissionAmountToApply": {
                    "amount": "7.77",
                    "currency": "usd"
                },
                "currency": {
                    "code": "usd",
                    "name": "USD"
                },
                "disposition": {
                    "code": "autoexception",
                    "name": "Automatic"
                },
                "executedDate": "2026-03-21",
                "grossAmountToApply": {
                    "amount": "77.73",
                    "currency": "usd"
                },
                "id": "bc:S9GSY5qBWUGMLfUmalIV3",
                "invoiceItem": {
                    "displayName": "03/21/2026 ($100.00)",
                    "id": "bc:Sp6NvSxjoHhYe0R5SUfpW",
                    "type": "InvoiceItem",
                    "uri": "/billing/v1/charges/bc:Sg8JJcrGK-iwYCrDB_zeh/invoice-items/bc:Sp6NvSxjoHhYe0R5SUfpW"
                },
                "paymentComments": "Positive gross"
            },
            ...
        },
        {
            "attributes": {
                "appliedDate": "2026-03-21T05:04:46.606Z",
                "commissionAmountToApply": {
                    "amount": "9.50",
                    "currency": "usd"
                },
                "currency": {
                    "code": "usd",
                    "name": "USD"
                },
                "disposition": {
                    "code": "autoexception",
                    "name": "Automatic"
                },
                "executedDate": "2026-03-21",
                "grossAmountToApply": {
                    "amount": "95.00",
                    "currency": "usd"
                },
                "id": "bc:S8yGjgU5mt7Y3_X-FiHYx",
                "invoiceItem": {
                    "displayName": "03/21/2026 ($95.00)",
                    "id": "bc:SBx2TZKEV9KB_IbgkVP1u",
                    "type": "InvoiceItem",
                    "uri": "/billing/v1/charges/bc:SybqgiVzcQiN5TxXOqdZO/invoice-items/bc:SBx2TZKEV9KB_IbgkVP1u"
                },
                "paymentComments": "Positive gross"
            },
            ...
        }
    }
}

In some cases, you may want to filter out reversed agency promise items. Use the query parameter ?filter=reversedDate:eq:null when you execute the GET to exclude reversed agency promise items.