Payment mismatch exceptions

Agency bill payments are typically more complex to process than direct bill payments. For example, a producer may provide a net amount that is less than or greater than the amount of the invoice item, or the producer might withhold more commission than is on the invoice item.

To reduce the complexity of agency bill payments and to help manage the distribution process, BillingCenter uses payment mismatch exceptions. A payment mismatch exception is a record of a mismatch between the amount of payment expected for a specific invoice item and the amount of payment received.

Retrieve payment mismatch exceptions

Use the following endpoint to retrieve all of a producer’s agency bill exceptions:
  • GET /billing/v1/producers/{producerId}/agency-bill-payment-exceptions

This retrieves all exceptions that have been created for a producer. For example, the following retrieves all exceptions on producer bc:372. In this case, there are two agency bill exceptions.

Command
GET /billing/v1/producers/bc:372/agency-bill-payment-exceptions

Response

{
    "count": 2,
    "data": [
        {
            "attributes": {
                "commissionDifference": {
                    "amount": "-1.94",
                    "currency": "usd"
                },
                "createDate": "2024-12-08T15:57:13.618Z",
                "grossDifference": {
                    "amount": "-19.38",
                    "currency": "usd"
                },
                "invoiceItem": {
                    "displayName": "12/08/2024 ($81.82)",
                    "id": "bc:476",
                    "type": "InvoiceItem",
                    "uri": "/billing/v1/charges/bc:SZzxc-1k8_xRc5qP5HBVQ/invoice-items/bc:SMNTjPJNZmRU53vhF0xvW"
                },
                "issueDescription": "Gross and Commission Mismatch"
            },
            "checksum": "5"
        },
        {
            "attributes": {
                "commissionDifference": {
                    "amount": "1.33",
                    "currency": "usd"
                },
                "createDate": "2025-02-08T16:03:24.312Z",
                "grossDifference": {
                    "amount": "0.00",
                    "currency": "usd"
                },
                "invoiceItem": {
                    "displayName": "01/08/2025 ($77.73)",
                    "id": "bc:477",
                    "type": "InvoiceItem",
                    "uri": "/billing/v1/charges/bc:SA-4CuOhZNRTuFrX9sXat/invoice-items/bc:SwizKDk04b-8tDMWHvw14"
                },
                "issueDescription": "Commission Mismatch"
            },
            "checksum": "3"
        }
    ...
    }
}

To return additional fields on the exception, such as information on the policy and statement, add the query parameter ?fields=*detail.

Resolve payment mismatch exceptions

There are a variety of ways that payment mismatches can be resolved. The full list can be found in Application Guide.

Cloud API supports the following options for resolving payment mismatch exceptions:
  • Write off - Write off the gross amount, the commission amount, or both.
  • Carry forward - BillingCenter removes the exception status from the invoice item, even if the invoice item remains unsettled. No other exceptions are raised on that invoice item, except if another distribution is made or modified against that invoice item. (Note that this option does not entail moving the invoice item to another statement invoice.)

Payment mismatch exception endpoint structure

From a data model perspective, exceptions are not stored in the BillingCenter databases as entities. Instead, they are calculated from a filtered set of invoice items and related objects and are generated at runtime when retrieved. This is why there is no ability to GET a single exception.

You must resolve payment mismatch exceptions by targeting the unsettled invoice items themselves. After retrieving a producer’s exceptions, you can use the URI in the exception’s invoiceItem field to access the related invoice item, and then call the relevant endpoint to resolve that item’s exception.

Write off exceptions

You can write off a payment mismatch exception to resolve it. This means that the amount owed will not be collected, or the amount due will not be paid out.

Write off exceptions using the following endpoint:
  • POST /charges/{chargeId}/invoice-items/{invoiceItemId}/agency-bill-exception-write-off

Payment mismatch exceptions can be related to a commission mismatch, a gross mismatch, or both. When writing off payment mismatch exceptions, all mismatches (both commission and gross) must be resolved for the exception to be resolved.

You can specify which values are written off in the POST request body. The following fields are required:
  • agencyWriteoffType - Which difference to write off, as a typekey reference. Can be commission, gross, or both.
  • writeOffReason - Typekey reference to the WriteOffReason typelist.

For example, the following request writes off both the gross and the commission difference for the invoice item bc:476.

Command
POST /billing/v1/charges/bc:349/invoice-items/bc:476/agency-bill-exception-write-off
Request body
{
    "data": {
        "attributes": {
            "agencyWriteoffType": {
                "code": "Both"
            },
            "writeoffReason": {
                "code": "Negotiation"
            }
        }
    }
}

Carry forward exceptions

You can also resolve a payment mismatch exception by carrying it forward. Carrying forward an exception essentially means that BillingCenter removes the exception for that invoice item and places a “lock” on the invoice item. This means that another exception is not raised on it, unless another distribution is made or modified against that invoice item and the amount remains unsettled.

It is important to note that carrying forward an exception does not move the invoice item in question to another statement invoice.

Carry forward an exception using the following endpoint:
  • POST /charges/{chargeId}/invoice-items/{invoiceItemId}/agency-bill-exception-carry-forward
No request body is required.
Command
POST /billing/v1/charges/bc:349/invoice-items/bc:476/agency-bill-exception-carry-forward
Request body
<empty>