Quickstart

This walks through creating an SDK client, making a customer, and confirming the response shape.

1. Get your API keys

Generate keys from the Easy Labs dashboard. Sandbox keys are prefixed sk_test_ and route to the sandbox environment automatically; live keys route to production. Store the value in an environment variable — never commit it and never ship it to the browser.

# .env.local
EASY_API_KEY=sk_test_...

2. Initialize the SDK

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

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

createClient is async because it round-trips the key against /validate-key at startup. Treat the resolved object as a long-lived singleton — create it once, reuse it for the lifetime of the process.

3. Make your first call

const created = await easy.createCustomer({
  first_name: "Ada",
  last_name: "Lovelace",
  email: "ada@example.com",
});

console.log(created.data.id); // -> "IDU..."

Every method returns an ApiResponse<T>:

type ApiResponse<T> = {
  success: boolean;
  message?: string;
  data: T;
};

The resource you care about is always under .data.

4. Handle the response

Errors are thrown as EasyApiError with status, code, details, and retryAfterSeconds populated from the API response:

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

try {
  await easy.createCustomer({ first_name: "Ada", last_name: "Lovelace" });
} catch (err) {
  if (err instanceof EasyApiError) {
    if (err.status === 429) {
      // Honour Retry-After
      await new Promise((r) => setTimeout(r, (err.retryAfterSeconds ?? 1) * 1000));
    } else if (err.status === 422) {
      console.error("Validation failed:", err.details);
    } else {
      throw err;
    }
  } else {
    throw err;
  }
}

What's next

• Customers and Payment Instruments — the building blocks of every flow.
• Checkout for an all-in-one create-customer + charge call, or Embedded Checkout for a hosted iframe.
• Subscriptions for recurring billing with proration, pauses, discounts, and metered usage.
• Webhooks for reacting to platform events.