Subscriptions
Create, retrieve, update, cancel, and list recurring subscriptions.
A subscription bills a customer a recurring amount on a schedule. For most integrations you attach a customer to a price and VINR handles the rest — the billing cycle, proration, invoicing, and automatic collection. If you operate at scale and need to control proration, billing anchors, metered usage, or invoice collection yourself, see Advanced below each section.
Illustrative content. Hand-authored to demonstrate the Standard/Advanced pattern; the production page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.
The subscription objectAsk
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier, e.g. sub_9Kpw1Vd. |
customer | string | The cust_ this subscription bills. Expandable. |
status | enum | active, trialing, past_due, canceled. |
price | string | The price_ charged each cycle. Expandable. |
current_period_end | timestamp | Unix timestamp when the next invoice is generated. |
latest_invoice | string | Most recent inv_. Expandable. |
created | timestamp | Unix timestamp when the subscription was created. |
Create a subscriptionAsk
Attach a customer to a price. VINR bills immediately, then on each cycle, collecting automatically from the customer's default payment method.
Retrieve a subscriptionAsk
Update a subscriptionAsk
Swap the price (an upgrade or downgrade) or schedule a cancellation at the end of the current period. By default a price change prorates and takes effect immediately.
Cancel a subscriptionAsk
Cancels the subscription immediately. The customer loses access at once and no further invoices are
generated. To cancel at the end of the current period, use cancel_at_period_end on the update
endpoint instead.
List subscriptionsAsk
Returns a paginated list of subscriptions. Filter by customer, status, or both.
Related eventsAsk
subscription.created, subscription.updated, subscription.canceled, and
invoice.payment_succeeded / invoice.payment_failed for each billing cycle. See
Events.
