Customers & payment methods

Billing does not own a separate notion of "who pays" — it reuses the exact customer and stored payment method objects you already created in Payments. This page covers the billing-specific fields layered on top of that shared model: which method a subscription charges, how addresses drive tax, and what happens when the method on file stops working.

One customer, two pillarsAskCopy

A customer created for a one-off payment is the same record a subscription bills. There is no migration step and no "billing customer" — a cust_ id is portable across both pillars. Billing simply reads extra fields from it.

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

// Same object Payments uses — billing fields are just additional properties.
const customer = await vinr.customers.create({
  email: 'ops@northwind.example',
  name: 'Northwind GmbH',
  billingAddress: {
    line1: 'Friedrichstrasse 12',
    city: 'Berlin',
    postalCode: '10117',
    country: 'DE',
  },
  taxIds: [{ type: 'eu_vat', value: 'DE123456789' }],
});                               // "cust_..."

Default payment methodAskCopy

Every recurring invoice is collected against a single method. VINR resolves it in priority order:

// Pin a specific stored method to one subscription, overriding the customer default.
await vinr.subscriptions.update('sub_4Qe1...', {
  defaultPaymentMethod: 'pm_9Hh2...',
});

Billing details & addressesAskCopy

The billing_address is the input to tax calculation, so keep it current. Changing it on the customer affects future invoices only; already-finalized invoices keep the address that was in effect when they locked. The tax_ids array determines whether VINR applies a reverse charge (B2B cross-border) or treats the sale as taxable in the customer's country.

await vinr.customers.update('cust_8Tg3...', {
  billingAddress: { line1: 'Rue de la Loi 100', city: 'Brussels', postalCode: '1000', country: 'BE' },
});

Updating the method on fileAskCopy

Customers update cards through a hosted update flow or by saving a new method in your own UI. The common pattern is: collect and tokenize the new method in Payments, then point the customer's default at it.

// 1. New method tokenized client-side (returns "pm_...").
// 2. Promote it to the customer default — the next invoice uses it automatically.
await vinr.customers.update('cust_8Tg3...', {
  defaultPaymentMethod: 'pm_NewK4...',
});

Failed-method handlingAskCopy

When collection fails, VINR distinguishes a transient failure (insufficient funds, soft decline) from a permanent one (expired or revoked card). Both emit invoice.payment_failed, but they route differently:

• Transient — dunning retries the same method on its schedule. No action needed unless retries exhaust.
• Permanent — VINR flags the method as requires_action; retrying it will never succeed, so dunning prompts the customer to add a new card.

Subscribe to the event to drive your own recovery emails or in-app banners.

// In your webhook handler. Signature header: x-vinr-signature.
const event = vinr.webhooks.verify(payload, signature);

if (event.type === 'invoice.payment_failed') {
  const invoice = event.data.object;            // "inv_..."
  if (invoice.lastPaymentError?.type === 'permanent') {
    await sendUpdateCardEmail(invoice.customer);
  }
}

Next stepsAskCopy