Subscriptions

Subscriptions bill a customer on a cadence — monthly, annual, usage- based, or any combination. The Python SDK exposes the full lifecycle: create, pause, resume, change items, apply discounts, report usage, and cancel.

Namespace: client.subscriptions. The list of methods is large because the resource models a real-world billing system; the Subscription System example shows how the pieces fit together.

Core CRUD

`create`

sub = client.subscriptions.create(
    identity_id="ident_123",
    items=[{"price_id": "price_monthly", "quantity": 1}],
    payment_instrument_id="pi_abc",
    idempotency_key="sub-ident_123-2025-01-01",
)

Returns: Subscription. All fields go through **kwargs.

`retrieve`

sub = client.subscriptions.retrieve("sub_123")

`update`

sub = client.subscriptions.update(
    "sub_123",
    proration_behavior="create_prorations",
    metadata={"upgraded": True},
)

`list`

subs = client.subscriptions.list(limit=50, offset=0)

For per-customer lists, use client.customers.subscriptions(customer_id, status="active", ...) — that endpoint returns a paginated envelope (see Pagination).

`cancel`

# Cancel immediately
client.subscriptions.cancel("sub_123")

# Cancel at the end of the current billing period
client.subscriptions.cancel("sub_123", at_period_end=True)

Pause, resume, preview

`pause`

client.subscriptions.pause(
    "sub_123",
    behavior="mark_uncollectible",         # or "keep_as_draft" / "void"
    resumes_at="2026-06-01T00:00:00Z",
)

`resume`

client.subscriptions.resume("sub_123")

`proration_preview`

preview = client.subscriptions.proration_preview(
    "sub_123",
    items=[{"price_id": "price_pro", "quantity": 1}],
    remove_items=["si_old"],
    proration_date="2026-05-01T00:00:00Z",
)

Returns a dict with the calculated proration line items. Useful for showing a "you'll be charged $X today" confirmation before applying the change.

Items

`add_item`

item = client.subscriptions.add_item(
    "sub_123",
    price_id="price_addon_seats",
    quantity=5,
)

`update_item`

item = client.subscriptions.update_item("sub_123", "si_456", quantity=10)

`remove_item`

client.subscriptions.remove_item("sub_123", "si_456")

Discounts

`apply_discount`

discount = client.subscriptions.apply_discount(
    "sub_123",
    coupon_id="cou_25_off",                # XOR with promotion_code
    subscription_item_id="si_456",         # optional scope
)

# Or via promotion code
discount = client.subscriptions.apply_discount(
    "sub_123",
    promotion_code="SUMMER2026",
)

Pass exactly one of coupon_id or promotion_code. Returns: SubscriptionDiscount.

`list_discounts`

discounts = client.subscriptions.list_discounts("sub_123")

`remove_discount`

client.subscriptions.remove_discount("sub_123", "sd_789")

One-time charges & usage

`create_one_time_charge`

charge = client.subscriptions.create_one_time_charge(
    "sub_123",
    amount=500,
    currency="USD",
    description="Setup fee",
    idempotency_key="otc-sub_123-setup",
)

Adds a one-off line item to the subscription's next invoice. Returns the raw data dict.

`report_usage`

client.subscriptions.report_usage(
    "sub_123",
    subscription_item_id="si_metered",
    quantity=42,
    timestamp="2026-05-01T12:00:00Z",
    action="increment",                    # or "set"
    idempotency_key="usage-sub_123-2026-05-01-12",
)

`usage_summary`

summary = client.subscriptions.usage_summary(
    "sub_123",
    subscription_item_id="si_metered",
    from_="2026-05-01T00:00:00Z",
    to="2026-06-01T00:00:00Z",
)

The keyword is from_ (with trailing underscore) because from is a Python reserved word; the SDK rewrites it to from on the wire.

`usage_reconciliation`

recon = client.subscriptions.usage_reconciliation(
    "sub_123",
    period_start="2026-05-01T00:00:00Z",
    period_end="2026-06-01T00:00:00Z",
)

Object shape

Subscription:

Field	Notes
`id`	Always present.
`identity_id`	The customer.
`status`	`"trialing"`, `"active"`, `"past_due"`, etc.
`items`	`list[SubscriptionItem] \| None`
`current_period_start` / `current_period_end`	ISO-8601.
`cancel_at_period_end`	`bool \| None`
`pause_collection`	`dict \| None`
`latest_invoice_id`	The invoice driving the current billing cycle.
`pending_update`	Scheduled changes not yet applied.
`trial_end`	ISO-8601 if in trial.
`metadata`, `created_at`, `updated_at`	Standard.

Related models: SubscriptionItem (id, price_id, quantity), SubscriptionDiscount (id, coupon_id or promotion_code_id, start, end), SubscriptionPlan (legacy Finix engine).

Examples

See the Subscription System recipe for an end-to-end walkthrough — checkout → create → upgrade with proration → cancel at period end.

Subscriptions

On this page