Billing quickstart

This walks the shortest path: install @easylabs/node, create a Product + Price, attach a Customer, and start a Subscription. The end state is an active subscription that will bill on its own going forward.

1. Get an API key

Sign in to the Easy Labs dashboard, go to Developers → API keys, and create a sandbox key (sk_sandbox_...). Sandbox keys hit a fully isolated test environment — real money never moves. Switch to a production key (sk_live_...) when you are ready to go live; the SDK routes based on the key prefix.

2. Install the SDK

npm install @easylabs/node
# pnpm add @easylabs/node
# yarn add @easylabs/node

Other languages: see SDKs.

3. Create a product, price, and subscription

This is server-side. It creates the catalog entry, attaches a recurring price, creates a customer, and starts a subscription against an existing payment instrument.

import { createClient } from "@easylabs/node";

const easy = await createClient({ apiKey: process.env.EASY_API_KEY! });

// 1. Catalog: a product and one recurring USD price ($29.00 / month).
const { data: product } = await easy.createProduct({
  name: "Pro plan",
  description: "Everything in Free, plus advanced analytics.",
  active: true,
});

const { data: price } = await easy.createPrice({
  product_id: product.id,
  active: true,
  recurring: true,
  currency: "USD",
  unit_amount: 2900,
  interval: "month",
  interval_count: 1,
  tax_behavior: "exclusive",
});

// 2. Customer + payment instrument.
const { data: customer } = await easy.createCustomer({
  first_name: "Ada",
  last_name: "Lovelace",
  email: "ada@example.com",
});

// In a real flow you'd collect card details client-side and pass the
// resulting tokenId here. See /docs/payments/concepts/payment-instrument.
const { data: instrument } = await easy.createPaymentInstrument({
  type: "PAYMENT_CARD",
  identityId: customer.id,
  name: "Ada Lovelace",
  tokenId: process.env.SANDBOX_CARD_TOKEN!,
  address: { line1: "1 Test St", city: "SF", region: "CA", postal_code: "94105", country: "USA" },
});

// 3. Subscription: charges the instrument now and on each renewal.
const { data: subscription } = await easy.createSubscription({
  identity_id: customer.id,
  instrument_id: instrument.id,
  items: [{ price_id: price.id, quantity: 1 }],
});

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

4. Verify

Read it back to confirm the subscription is active and the first invoice was generated:

const { data } = await easy.getSubscription(subscription.id);
console.log(data.status, data.latest_invoice_id, data.current_period_end);

Or open the subscription in the Billing → Subscriptions view in the dashboard. The matching subscription.created and invoice.paid events will fire to any registered webhook.

5. Next steps

Create a subscription — full version with trials, proration, and item changes
Send an invoice — for one-off charges and quote-style billing
Configure dunning — retry + recovery on failed renewals
Launch the customer portal — let customers self-serve