Subscriptions

The Easy-native subscription engine. Covers the full lifecycle: create / list / retrieve, cancel / pause / resume, item CRUD, discount application, one-time charges, metered usage reporting, and proration preview.

Accessed via client.subscriptions. The largest resource in the SDK (~14 endpoints).

Top-level methods

`list(limit: nil, offset: nil, ids: nil)`

GET /subscriptions.

client.subscriptions.list(limit: 50)

`retrieve(id)`

GET /subscriptions/:id.

`create(**body)`

POST /subscriptions. Minimum required fields: identity_id:, items:, instrument_id:.

sub = client.subscriptions.create(
  identity_id:   customer[:id],
  items:         [{ price_id: "price_…" }],
  instrument_id: card[:id]
)

`update(id, **body)`

PATCH /subscriptions/:id. Update top-level fields like cancel_at_period_end: or default payment method.

client.subscriptions.update("sub_…", cancel_at_period_end: true)

`cancel(id, at_period_end: nil)`

DELETE /subscriptions/:id?at_period_end=…. With no argument the server's default applies; pass true / false explicitly to override.

client.subscriptions.cancel("sub_…")                       # server default
client.subscriptions.cancel("sub_…", at_period_end: true)  # cancel at end of period
client.subscriptions.cancel("sub_…", at_period_end: false) # cancel immediately

Pause / resume

`pause(id, behavior:, resumes_at: nil)`

POST /subscriptions/:id/pause. behavior controls how the API treats unpaid invoices during the pause ("void", "keep_as_draft", …).

client.subscriptions.pause("sub_…", behavior: "void", resumes_at: "2026-06-01T00:00:00Z")

`resume(id)`

POST /subscriptions/:id/resume.

Items

`add_item(id, price_id:, quantity: nil)`

POST /subscriptions/:id/items.

client.subscriptions.add_item("sub_…", price_id: "price_addon", quantity: 2)

`update_item(id, item_id, quantity:)`

PATCH /subscriptions/:id/items/:item_id.

client.subscriptions.update_item("sub_…", "si_…", quantity: 5)

`remove_item(id, item_id)`

DELETE /subscriptions/:id/items/:item_id.

Discounts

`apply_discount(id, **body)`

POST /subscriptions/:id/discounts. Pass exactly one of coupon_id: or promotion_code:; optionally scope to a single item with subscription_item_id:. The XOR is enforced server-side.

client.subscriptions.apply_discount("sub_…", promotion_code: "SUMMER25")

`list_discounts(id)`

GET /subscriptions/:id/discounts.

`remove_discount(id, discount_id)`

DELETE /subscriptions/:id/discounts/:discount_id.

One-time charges

`create_one_time_charge(id, **body)`

POST /subscriptions/:id/one-time-charges. Adds a non-recurring line to the next invoice — useful for usage overages, setup fees, etc.

client.subscriptions.create_one_time_charge(
  "sub_…", price_id: "price_setup_fee", quantity: 1
)

Metered usage

`report_usage(id, **body)`

POST /subscriptions/:id/usage. Report a usage delta against a metered subscription item.

client.subscriptions.report_usage("sub_…", subscription_item_id: "si_…", quantity: 100)

`usage_summary(id, **query)`

GET /subscriptions/:id/usage/summary.

`usage_reconciliation(id, **query)`

GET /subscriptions/:id/usage/reconciliation.

Proration preview

`proration_preview(id, items: nil, remove_items: nil, proration_date: nil)`

GET /subscriptions/:id/proration-preview. Preview the charge that would result from a planned change before applying it.

items: accepts the same shape as add_item — array of { price_id:, quantity: } hashes. The SDK encodes them as the comma-joined price_id:quantity shape the API expects.

preview = client.subscriptions.proration_preview(
  "sub_…",
  items:        [{ price_id: "price_addon", quantity: 2 }],
  remove_items: ["si_old_addon"]
)

sub = client.subscriptions.create(
  identity_id:   customer[:id],
  items:         [{ price_id: "price_base" }],
  instrument_id: card[:id]
)

preview = client.subscriptions.proration_preview(
  sub[:id],
  items: [{ price_id: "price_addon", quantity: 2 }]
)

if preview[:total] <= max_acceptable_charge
  client.subscriptions.add_item(sub[:id], price_id: "price_addon", quantity: 2)
end

Cancel at the end of the current period

client.subscriptions.cancel("sub_…", at_period_end: true)

Apply a coupon, then remove it

discount = client.subscriptions.apply_discount("sub_…", coupon_id: "cpn_holiday")
client.subscriptions.remove_discount("sub_…", discount[:id])