Trouble ticket holds and hold type entries

A hold is a lock associated with a trouble ticket that stops a specific type of automated processing related to the account, policy period, or producer. When managing the holds on a ticket through Cloud API, there are two objects to be aware of:

Trouble ticket hold: a thin object used to track the status of a hold placed on a trouble ticket. There is exactly one trouble ticket hold per trouble ticket, and it is created automatically when the trouble ticket is created. The trouble ticket hold serves as a parent object to the hold type entries.
Hold type entry: an object used to track and manage individual hold items and their release dates. Hold type entries are managed independent of holds. A trouble ticket hold can have multiple hold type entries, such as a hold type entry for delinquency, a hold type entry for commission payments, and so on. For more information, see Hold type entries.

For more information on the business functionality of trouble tickets, see the Application Guide.

Querying for trouble ticket holds

Use the following endpoints to query for the hold on a trouble ticket.

GET /billing/v1/trouble-tickets/{troubleTicketId}/holds
GET /billing/v1/trouble-tickets/{troubleTicketId}/holds/{holdId}

Both endpoints return the same thing: the single hold on the the trouble ticket.

Querying for holds on a trouble ticket

Use the following endpoint to retrieve all holds for a trouble ticket:

GET /billing/v1/trouble-tickets/{troubleTicketId}/holds

Because each trouble ticket has exactly one hold, the response contains a list containing a single hold record.

Command

GET /billing/v1/trouble-tickets/bc:Si7zQ9G3vglqY7kpxhEM3/holds

Response

{
    "count": 1,
    "data": [
        {
            "attributes": {
                "assignmentStatus": {
                    "code": "unassigned",
                    "name": "Unassigned"
                },
                "id": "bc:Si7zQ9G3vglqY7kpxhEM3"
            },
            ...
        }
    }
}

Hold type entries

A hold type entry defines a specific type of hold that is in effect for a trouble ticket hold in BillingCenter. Each hold type entry specifies the category of hold (such as delinquency or invoice sending) and optionally the date on which that hold is scheduled to be released. In the BillingCenter user interface, these are called hold items.

A single hold can have multiple hold type entries, but each hold type must appear only once per hold.

The fields of a hold type entry are:

id – The unique identifier of the hold type entry.
holdType – The category of hold. This is a typekey reference to the HoldType typelist. Examples include Delinquency and InvoiceSending.
releaseDate – The date on which this hold type is scheduled for release. Nullable.

The following endpoints are available for hold type entries:

POST /billing/v1/trouble-tickets/{troubleTicketId}/holds/{holdId}/hold-type-entries
GET /billing/v1/trouble-tickets/{troubleTicketId}/holds/{holdId}/hold-type-entries
GET /billing/v1/trouble-tickets/{troubleTicketId}/holds/{holdId}/hold-type-entries/{holdTypeEntryId}
PATCH /billing/v1/trouble-tickets/{troubleTicketId}/holds/{holdId}/hold-type-entries/{holdTypeEntryId}
DELETE /billing/v1/trouble-tickets/{troubleTicketId}/holds/{holdId}/hold-type-entries/{holdTypeEntryId}

For more information on the business functionality of trouble tickets, see the Application Guide.

Querying for hold type entries

Use the following endpoints to query for the hold type entries on a trouble ticket hold:

GET /billing/v1/trouble-tickets/{troubleTicketId}/holds/{holdId}/hold-type-entries
GET /billing/v1/trouble-tickets/{troubleTicketId}/holds/{holdId}/hold-type-entries/{holdTypeEntryId}

Querying for a list of hold type entries

Use the following endpoint to retrieve all hold type entries for a hold:

GET /billing/v1/trouble-tickets/{troubleTicketId}/holds/{holdId}/hold-type-entries

You can also retrieve hold type entries inline when querying the parent hold by using ?include=hold-type-entries on GET /billing/v1/trouble-tickets/{troubleTicketId}/holds/{holdId}.

Command

GET /billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/holds/bc:SZMT7M4Z6MaW5fXe95OVT/hold-type-entries

Response

{
    "count": 2,
    "data": [
        {
            "attributes": {
                "holdType": {
                    "code": "Delinquency",
                    "name": "Delinquency"
                },
                "id": "bc:SJ-yl_PZS1ggNyqyh8ELN",
                "releaseDate": "2026-06-01"
            },
            "checksum": "0",
            "links": {
                "self": {
                    "href": "/billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/holds/bc:SZMT7M4Z6MaW5fXe95OVT/hold-type-entries/bc:SJ-yl_PZS1ggNyqyh8ELN",
                    "methods": [
                        "delete",
                        "get",
                        "patch"
                    ]
                }
            }
        },
        {
            "attributes": {
                "holdType": {
                    "code": "InvoiceSending",
                    "name": "Invoice Sending"
                },
                "id": "bc:SKCrV65WAcc2LNS-5cdgR",
                "releaseDate": "2026-06-15"
            },
            "checksum": "0",
            "links": {
                "self": {
                    "href": "/billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/holds/bc:SZMT7M4Z6MaW5fXe95OVT/hold-type-entries/bc:SKCrV65WAcc2LNS-5cdgR",
                    "methods": [
                        "delete",
                        "get",
                        "patch"
                    ]
                }
            }
        }
    ],
    "links": {
        "self": {
            "href": "/billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/holds/bc:SZMT7M4Z6MaW5fXe95OVT/hold-type-entries",
            "methods": [
                "get"
            ]
        }
    }
}

Querying for a specific hold type entry

Use the following endpoint to retrieve a specific hold type entry by its ID:

GET /billing/v1/trouble-tickets/{troubleTicketId}/holds/{holdId}/hold-type-entries/{holdTypeEntryId}

The holdTypeEntryId must belong to the specified hold and trouble ticket.

Command

GET /billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/holds/bc:SZMT7M4Z6MaW5fXe95OVT/hold-type-entries/bc:SJ-yl_PZS1ggNyqyh8ELN

Response

{
    "data": {
        "attributes": {
            "holdType": {
                "code": "Delinquency",
                "name": "Delinquency"
            },
            "id": "bc:SJ-yl_PZS1ggNyqyh8ELN",
            "releaseDate": "2026-06-01"
        },
        "checksum": "0",
        "links": {
            "self": {
                "href": "/billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/holds/bc:SZMT7M4Z6MaW5fXe95OVT/hold-type-entries/bc:SJ-yl_PZS1ggNyqyh8ELN",
                "methods": [
                    "delete",
                    "get",
                    "patch"
                ]
            }
        }
    }
}

Creating hold type entries

To add a hold type entry to a trouble ticket hold, use the following endpoint:

POST /billing/v1/trouble-tickets/{troubleTicketId}/holds/{holdId}/hold-type-entries

Minimum creation criteria

The following field is required to create a hold type entry:


Field	Description	Note
`holdType`	The category of hold to apply. Specify a typekey reference to the `HoldType` typelist.	Each hold type can appear only once per trouble ticket. Examples: `Delinquency`, `InvoiceSending`.

The following optional field can also be set at creation:

releaseDate – The date on which this hold type is scheduled to be released, in the date-time format YYYY-MM-DD.

Important: Each hold type can appear only once per hold.

Example of creating a hold type entry

The following example creates a hold type entry with a hold type and release date.

Command

POST /billing/v1/trouble-tickets/bc:SiEr6uiqxEgw6UrHqs_HJ/holds/bc:Si7zQ9G3vglqY7kpxhEM3/hold-type-entries

Request body

{
    "data": {
        "attributes": {
            "holdType": {
                "code": "CommissionPolicyEarn"
            },
            "releaseDate": "2222-10-10"
        }
    }
}

Response

{
    "data": {
        "attributes": {
            "holdType": {
                "code": "CommissionPolicyEarn",
                "name": "Commission Policy Earnings"
            },
            "id": "bc:S_l3hCF1HOc_6b6o61UtI",
            "releaseDate": "2222-10-10T00:00:00.000Z"
        },
        ...
    }
}

To create a hold type entry without a release date, omit releaseDate or set it to null:

{
    "data": {
        "attributes": {
            "holdType": {
                "code": "InvoiceSending"
            }
        }
    }
}

Modifying hold type entries

To modify a hold type entry, use the following endpoint:

PATCH /billing/v1/trouble-tickets/{troubleTicketId}/holds/{holdId}/hold-type-entries/{holdTypeEntryId}

Modifiable fields

The following field can be modified on a hold type entry:

releaseDate – The date on which this hold type is scheduled to be released. Set to null to clear a previously set release date.

The holdType field cannot be changed after a hold type entry is created.

Example of modifying a hold type entry

The following example updates the release date on a hold type entry.

Command

PATCH /billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/holds/bc:SZMT7M4Z6MaW5fXe95OVT/hold-type-entries/bc:SJ-yl_PZS1ggNyqyh8ELN

Request body

{
    "data": {
        "attributes": {
            "releaseDate": "2026-07-01"
        }
    }
}

To clear the release date, set releaseDate to null:

{
    "data": {
        "attributes": {
            "releaseDate": null
        }
    }
}

Deleting hold type entries

To remove a hold type entry from a trouble ticket hold, use the following endpoint:

DELETE /billing/v1/trouble-tickets/{troubleTicketId}/holds/{holdId}/hold-type-entries/{holdTypeEntryId}

Deleting a hold type entry removes that hold category from the hold. The hold itself and any remaining hold type entries are not affected.

Example of deleting a hold type entry

The following example deletes a hold type entry.

DELETE /billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/holds/bc:SZMT7M4Z6MaW5fXe95OVT/hold-type-entries/bc:SJ-yl_PZS1ggNyqyh8ELN

A successful DELETE returns HTTP 204 No Content. To confirm deletion, a subsequent GET on the same hold type entry path returns HTTP 404.