Creating subscriptions

Create a subscription by attaching a customer, one or more prices, and a payment method, with optional trial and proration behavior. Once created, the subscription becomes the engine that generates invoices each cycle — so getting the first call right means recurring revenue collects itself.

What you need firstAskCopy

A subscription ties three things together. Have each ready before you call the API:

Create your first subscriptionAskCopy

The minimal call attaches a customer to a price. VINR uses the customer's default payment method and anchors the billing cycle to the creation time.

import { Vinr } from '@vinr/sdk';
const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const subscription = await vinr.subscriptions.create({
  customer: 'cust_8Hk2pQ',
  items: [{ price: 'price_pro_monthly', quantity: 1 }],
});

console.log(subscription.id);     // "sub_..."
console.log(subscription.status); // "active"

If the customer has no default payment method, pass one explicitly. The method is attached to the customer and set as default for future cycles:

const subscription = await vinr.subscriptions.create({
  customer: 'cust_8Hk2pQ',
  items: [{ price: 'price_pro_monthly' }],
  default_payment_method: 'pm_card_visa',
});

What happens on creationAskCopy

Adding a trialAskCopy

A trial delays the first charge. The subscription is trialing until the trial ends, then VINR collects the first real invoice automatically. Use either a duration or an explicit end timestamp.

const subscription = await vinr.subscriptions.create({
  customer: 'cust_8Hk2pQ',
  items: [{ price: 'price_pro_monthly' }],
  trial_period_days: 14,
});
// status: "trialing" — no invoice collected yet

const subscription = await vinr.subscriptions.create({
  customer: 'cust_8Hk2pQ',
  items: [{ price: 'price_pro_monthly' }],
  trial_end: 1751328000, // Unix seconds; first charge lands here
});

Key parametersAskCopy

Aligning the billing cycleAskCopy

By default each subscription bills on its own creation date. To align many customers to a single date (for example, everyone on the 1st), set an explicit billing_cycle_anchor. VINR prorates the partial first period unless you pass proration_behavior: 'none'.

const subscription = await vinr.subscriptions.create({
  customer: 'cust_8Hk2pQ',
  items: [{ price: 'price_pro_monthly' }],
  billing_cycle_anchor: 1751328000, // first day of next month, 00:00 UTC
  proration_behavior: 'create_prorations',
});

React with webhooks, not the responseAskCopy

The create call returns the subscription, but collection can complete asynchronously (SCA, bank delays). Provision access on the event, not the API return value.

const event = vinr.webhooks.verify(payload, request.headers['x-vinr-signature']);

switch (event.type) {
  case 'subscription.created':
    // subscription exists — may still be collecting its first invoice
    break;
  case 'invoice.paid':
    grantAccess(event.data.object.customer); // safe to fulfil here
    break;
  case 'invoice.payment_failed':
    // dunning has begun; surface a recovery prompt
    break;
}

Edge casesAskCopy

Next stepsAskCopy