The subscription object

Fields

Field	Type	Always present	What it means
id	string	Yes
tenant_id	string	No
code	string	Yes
display_name	string	Yes
customer_id	string	Yes
items	array of Subscription item	No	The subscription’s priced lines. Each item names its plan.
status	enum	Yes	One of: draft, trialing, active, canceled.
billing_time	enum	Yes	One of: calendar, anniversary.
trial_start_at	string (date-time)	No
trial_end_at	string (date-time)	No
started_at	string (date-time)	No
activated_at	string (date-time)	No
canceled_at	string (date-time)	No	When the subscription was canceled. Absent until then.
cancel_at	string (date-time)	No	A scheduled cancel time, if one is set.
cancel_at_period_end	boolean	Yes	True when the subscription cancels at the end of the current period.
cancel_effective_at	string (date-time)	No	When a scheduled cancel takes effect. Absent when no cancel is scheduled.
pause_collection	Subscription pause collection	No	Present on a subscription while collection is paused. New invoices are still created, but stay drafts and are not charged.
billing_thresholds	Subscription billing thresholds	No	Limits that make Hardcount invoice before the period ends. A threshold invoice bills the period’s usage so far, and no base fee. The period keeps its dates, the base fee is billed as it would be with no threshold, and the period’s next invoice bills the rest of the usage.
current_billing_period_start	string (date-time)	No
current_billing_period_end	string (date-time)	No	End of the current period (exclusive).
current_billing_period_display	string	No	The current period as text, with the last day included, in the tenant’s billing time zone.
next_billing_at	string (date-time)	No
billing_anchor_day	integer	No	Day of the month the subscription bills on (1-31). Absent for calendar-monthly subscriptions.
test_clock_id	string	No
billing_failure	Billing failure	No	Present on a subscription while the billing run is failing on the work that subscription has due now (a period close, or a scheduled mid-period cancel). Absent otherwise: a subscription that bills cleanly, or whose due work changed, carries no billing_failure. After each failed attempt the billing run waits before the next one: 15 minutes, 1 hour, 4 hours, 12 hours, then 24 hours three times. The eighth failure parks the subscription (parked: true, no next_attempt_at). A parked subscription is not attempted again until POST /v1/subscriptions/{id}/retry-billing is called. Never set on a subscription attached to a test clock.
created_at	string (date-time)	Yes
updated_at	string (date-time)	Yes

Subscription item

One priced line of a subscription. It pairs a plan with a quantity.

Field	Type	Always present	What it means
id	string	Yes
tenant_id	string	No
subscription_id	string	Yes
plan_id	string	Yes
quantity	integer (int64)	Yes
metadata	object	No	The item’s stored metadata. Absent when empty.
pending_plan_id	string	No	Plan the item moves to at pending_plan_effective_at. Absent when no change is scheduled.
pending_plan_effective_at	string (date-time)	No
plan_changed_at	string (date-time)	No	When the plan was last changed immediately. Absent until the first such change.
created_at	string (date-time)	Yes
updated_at	string (date-time)	Yes

Subscription pause collection

Present on a subscription while collection is paused. New invoices are still created, but stay drafts and are not charged.

Field	Type	Always present	What it means
behavior	enum	Yes	One of: keep_as_draft.
resumes_at	string (date-time)	No	When collection resumes. Absent when the pause lasts until it is cleared. On a pause set by dunning, it is when Hardcount recorded the payment of the invoice the pause was set for.
set_by	enum	Yes	Who paused collection. operator: you, through the API or the dashboard; the pause lasts until you resume it or until resumes_at. dunning: a dunning policy’s pause final action. A dunning pause lifts by itself once the invoice whose dunning set it is paid, even if another invoice is still owed. Periods that ended during the pause keep their draft invoices. One of: operator, dunning.

Subscription billing thresholds

Limits that make Hardcount invoice before the period ends. A threshold invoice bills the period’s usage so far, and no base fee. The period keeps its dates, the base fee is billed as it would be with no threshold, and the period’s next invoice bills the rest of the usage.

Field	Type	Always present	What it means
amount_gte	integer (int64)	No	Usage threshold in cents, compared with the period’s usage so far (the base fee is not counted). Absent when not set.
item_thresholds	array of Subscription item threshold	Yes

Billing failure

Present on a subscription while the billing run is failing on the work that subscription has due now (a period close, or a scheduled mid-period cancel). Absent otherwise: a subscription that bills cleanly, or whose due work changed, carries no billing_failure. After each failed attempt the billing run waits before the next one: 15 minutes, 1 hour, 4 hours, 12 hours, then 24 hours three times. The eighth failure parks the subscription (parked: true, no next_attempt_at). A parked subscription is not attempted again until POST /v1/subscriptions/{id}/retry-billing is called. Never set on a subscription attached to a test clock.

Field	Type	Always present	What it means
attempts	integer	Yes	Failed attempts on the work that is due now. At least 1.
max_attempts	integer	Yes	The attempt at which the subscription parks (8).
last_error	string	Yes	Why the latest attempt failed: a sentence an operator can act on, or a generic line carrying the subscription id as the reference to search the server log for. Never raw error text.
failed_at	string (date-time)	Yes	When the latest attempt failed.
next_attempt_at	string (date-time)	No	The billing run does not attempt the subscription before this instant. The attempt happens on the first run at or after it, so on an hourly schedule it can be up to an hour later. Absent when parked.
parked	boolean	Yes	True when automatic attempts have stopped.

Subscription item threshold

Field	Type	Always present	What it means
subscription_item_id	string	Yes
usage_gte	string	Yes	Usage quantity threshold, as a decimal string.