Trouble ticket join entities

A trouble ticket join entity is a database entity that associates a trouble ticket with a related billing entity in BillingCenter. Join entities provide context for a trouble ticket by identifying the specific accounts, policies, policy periods, producers, or transactions that are involved in the issue being tracked. In the BillingCenter user interface, related billing entities are sometimes referred to as related entities.

There can be multiple entities associated with a trouble ticket, and there is one join entity per related entity.

The following endpoints are available for trouble ticket join entities:

GET /billing/v1/trouble-tickets/{troubleTicketId}/join-entities
POST /billing/v1/trouble-tickets/{troubleTicketId}/join-entities
GET /billing/v1/trouble-tickets/{troubleTicketId}/join-entities/{joinEntityId}
DELETE /billing/v1/trouble-tickets/{troubleTicketId}/join-entities/{joinEntityId}

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

Querying for trouble ticket join entities

To find out the billing entities associated with a trouble ticket, you need to GET the trouble ticket join entities. Use the following endpoints to query for the join entities on a trouble ticket:

GET /billing/v1/trouble-tickets/{troubleTicketId}/join-entities
GET /billing/v1/trouble-tickets/{troubleTicketId}/join-entities/{joinEntityId}

Querying for all join entities on a trouble ticket

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

GET /billing/v1/trouble-tickets/{troubleTicketId}/join-entities

The response returns one join entity record per related billing entity. Each record identifies the entity type and provides a reference with the entity's display name, ID, type, and URI.

The following is a truncated example response for a trouble ticket with five join entities:

Command

GET /billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/join-entities

Response

{
    "count": 5,
    "data": [
        {
            "attributes": {
                "account": {
                    "displayName": "Standard Account",
                    "id": "bc:S7usdlwusg1UGDJ62wEvu",
                    "type": "Account",
                    "uri": "/billing/v1/accounts/bc:S7usdlwusg1UGDJ62wEvu"
                },
                "createTime": "2026-05-14T22:55:40.989Z",
                "id": "bc:SZMT7M4Z6MaW5fXe95OVT"
            },
            "checksum": "0",
            "links": {
                "self": {
                    "href": "/billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/join-entities/bc:SZMT7M4Z6MaW5fXe95OVT",
                    "methods": [
                        "delete",
                        "get"
                    ]
                }
            }
        },
        {
            "attributes": {
                "createTime": "2026-05-14T22:55:40.989Z",
                "id": "bc:SJ-yl_PZS1ggNyqyh8ELN",
                "transaction": {
                    "displayName": "Premium Charged",
                    "id": "bc:SKCrV65WAcc2LNS-5cdgR",
                    "type": "Transaction",
                    "uri": "/billing/v1/transactions/bc:SKCrV65WAcc2LNS-5cdgR"
                }
            },
            "checksum": "0",
            "links": {
                "self": {
                    "href": "/billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/join-entities/bc:SJ-yl_PZS1ggNyqyh8ELN",
                    "methods": [
                        "delete",
                        "get"
                    ]
                }
            }
            ...
        },
    }
}

Note: If a trouble ticket is related to a transaction which is attached to an archived policy period, information about the transaction is not provided as a transaction object. Instead, the ID of the archived transaction is provided using the archivedTransactionPublicID field.

Querying for a specific join entity

Use the following endpoint to retrieve a specific join entity by its ID:

GET /billing/v1/trouble-tickets/{troubleTicketId}/join-entities/{joinEntityId}

The joinEntityId must belong to the specified trouble ticket.

Example response:

Command

GET /billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/join-entities/bc:SZMT7M4Z6MaW5fXe95OVT

Response

{
    "data": {
        "attributes": {
            "account": {
                "displayName": "Standard Account",
                "id": "bc:S7usdlwusg1UGDJ62wEvu",
                "type": "Account",
                "uri": "/billing/v1/accounts/bc:S7usdlwusg1UGDJ62wEvu"
            },
            "createTime": "2026-05-14T22:55:40.989Z",
            "id": "bc:SZMT7M4Z6MaW5fXe95OVT"
        },
        "checksum": "0",
        "links": {
            "self": {
                "href": "/billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/join-entities/bc:SZMT7M4Z6MaW5fXe95OVT",
                "methods": [
                    "delete",
                    "get"
                ]
            }
        }
    }
}

Creating trouble ticket join entities

To link a trouble ticket to a related billing entity, use the following endpoint:

POST /billing/v1/trouble-tickets/{troubleTicketId}/join-entities

Minimum creation criteria

The request body must include exactly one entity reference in data.attributes. The following entity types are supported:


Field	Description	Note
`account`	Links the trouble ticket to an account. Provide the account `id`.	Specify exactly one entity type per request.
`policy`	Links the trouble ticket to a policy. Provide the policy `id`.	Specify exactly one entity type per request.
`policyPeriod`	Links the trouble ticket to a policy period. Provide the policy period `id`.	Specify exactly one entity type per request.
`producer`	Links the trouble ticket to a producer. Provide the producer `id`.	Specify exactly one entity type per request.
`transaction`	Links the trouble ticket to a transaction. Provide the transaction `id`.	Specify exactly one entity type per request.

Example of creating a trouble ticket join entity

The following example links a trouble ticket to an account.

Command

POST /billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/join-entities

Request body

{
    "data": {
        "attributes": {
            "account": {
                "id": "bc:SBLBXfs4-afSQtF1S5G5H"
            }
        }
    }
}

Response

{
    "data": {
        "attributes": {
            "account": {
                "displayName": "Maple-60-Katana",
                "id": "bc:SBLBXfs4-afSQtF1S5G5H",
                "type": "Account",
                "uri": "/billing/v1/accounts/bc:SBLBXfs4-afSQtF1S5G5H"
            },
            "createTime": "2026-05-14T22:59:53.933Z",
            "id": "bc:SWYwPzIfOc0bnaMr9d_Ou"
        },
        "checksum": "0",
        "links": {
            "self": {
                "href": "/billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/join-entities/bc:SWYwPzIfOc0bnaMr9d_Ou",
                "methods": [
                    "delete",
                    "get"
                ]
            }
        }
    }
}

To link the same trouble ticket to a policy instead, replace account with policy and provide the policy ID:

Command

POST /billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/join-entities

Request body

{
  "data": {
    "attributes": {
      "policy": {
        "id": "bc:SomePolicyId"
      }
    }
  }
}

Deleting trouble ticket join entities

To remove the association between a trouble ticket and a related billing entity, delete the join entity record using the following endpoint:

DELETE /billing/v1/trouble-tickets/{troubleTicketId}/join-entities/{joinEntityId}

Example of deleting a trouble ticket join entity

The following example removes a join entity from a trouble ticket.

DELETE /billing/v1/trouble-tickets/bc:Sr5GX83DlZ4PbayH18w2h/join-entities/bc:839ufJ3038Ke532K39

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