Retrieve the Dunning State of a Billing Account

You can retrieve the dunning state of a billing account using the following endpoint:

GET https://example-gotransverse.com/billing/2/billing-accounts/{billing_account_id}/dunning-state

Learn what you need to know to successfully retrieve the dunning state of a billing account in the Considerations, Before You Start, Response, and Next Steps sections below.

Considerations

Consider the following when retrieving the dunning state of a billing account:

• The fields returned as part of the dunning state entity are determined by the dunning strategy of the assigned dunning plan and if the billing account is in dunning. Response examples:

  • Dunning State Entity with Dunning Enabled and not In Dunning

  • Dunning State Entity with Dunning Enabled and In Dunning

• A billing account that has never had dunning enabled does not have a dunning state. When a billing account does not have a dunning state, the API response will return the error 404: dunning_state for the specified billing_account was not found.

Before You Start

You will need the following when retrieving the dunning state of a billing account:

• The id of the billing account entity for use as the {billing_account_id} path parameter.

Response

When successful, the dunning state entity of a billing account is returned.

Dunning State Entity with Dunning Enabled and Not In Dunning

The dunning state entity response example below is for a billing account with dunning enabled but no invoices that meet the criteria of the assigned dunning plan. The last dunning evaluation placed the dunning state in the No Dunning tier.

1
2
3
4
5
6
7
8
{
    "id": "64",
    "enabled": true,
    "plan_code": "123",
    "plan_name": "Standard Dunning",
    "tier_code": "default_no_dunning",
    "tier_name": "No Dunning"
}

The following fields are returned when a dunning state with dunning enabled and not actively in dunning is successfully retrieved:

• id — The ID of the dunning state entity.

• enabled — Specifies whether dunning is enabled for this billing account.

• plan_code — The unique code of the assigned dunning plan.

• plan_name — The name of the assigned dunning plan.

• tier_code — The code of the dunning plan tier assigned after the last dunning evaluation.

• tier_name — The name of the dunning plan tier assigned after the last dunning evaluation.

Dunning State Entity with Dunning Enabled and In Dunning

The dunning state entity response example below is for a billing account with dunning enabled, is assigned a dunning plan with the overdue account balance dunning strategy, and has invoices that meet the criteria of the assigned dunning plan. The most recent dunning evaluation placed the dunning state in tier 3.

1
2
3
4
5
6
7
8
9
10
11
12
{
    "id": "114",
    "enabled": true,
    "plan_code": "123",
    "plan_name": "Standard Dunning",
    "tier_code": "Tier #3",
    "tier_name": "Suspension Warning",
    "effective_date": "2024-10-09T12:58:35-05:00",
    "previous_tier_code": "default_no_dunning",
    "previous_tier_name": "No Dunning",
    "anchor_date": "2023-11-09T00:00:00-06:00"
}

The following fields are returned when a dunning state with dunning enabled and in dunning is successfully retrieved:

• id — The ID of the dunning state entity.

• enabled — Specifies whether dunning is enabled for this billing account.

• plan_code — The unique code of the assigned dunning plan.

• plan_name — The name of the assigned dunning plan.

• tier_code — The code of the dunning plan tier assigned after the last dunning evaluation.

• tier_name — The name of the dunning plan tier assigned after the last dunning evaluation.

• effective_date — The date and time of the last dunning evaluation.

• previous_tier_code — The code of the dunning plan tier before the current tier.

• previous_tier_name — The name of the dunning plan tier before the current tier.

• anchor_date — The date and time used to calculate the number of days past due during the dunning evaluation. This field is only returned when the assigned dunning plan uses the overdue account balance dunning strategy.

Next Steps

After the dunning state is retrieved, you can do the following:

• Update Dunning Anchor Date

Topic Updated: 10/2024.