# Welcome (/docs)





Three products cover everything Easy Labs ships today.

## Products [#products]

<Cards>
  <Card title="Payments" href="./payments" description="Accept one-time payments, embed checkout, manage disputes." />

  <Card title="Billing" href="./billing" description="Subscriptions, invoices, dunning, customer portal." />

  <Card title="Treasury" href="./treasury" description="Send payouts, manage recipients, generate payout links." />
</Cards>

## Build with your stack [#build-with-your-stack]

<Cards>
  <Card title="JavaScript" href="./sdks/javascript" description="@easylabs/browser" />

  <Card title="React" href="./sdks/react" description="@easylabs/react" />

  <Card title="React Native" href="./sdks/react-native" description="@easylabs/react-native" />

  <Card title="Node.js" href="./sdks/node" description="@easylabs/node" />

  <Card title="Ruby" href="./sdks/ruby" description="easy-sdk gem" />

  <Card title="Python" href="./sdks/python" description="easylabs pip package" />
</Cards>

## API [#api]

<Cards>
  <Card title="API Reference" href="./reference/api" description="Per-product HTTP API operations." />

  <Card title="Webhooks" href="./reference/webhooks" description="Event types + signature verification." />

  <Card title="Compliance & scale" href="./reference/compliance" description="Security, certifications, uptime." />

  <Card title="Changelog" href="./changelog" description="Per-SDK release history." />
</Cards>


# Billing compliance & scale (/docs/billing/compliance)



{/* TODO: Single-page summary. For now, link to the shared compliance page: */}

See the cross-product [Reference → Compliance](/docs/reference/compliance) page for security model, PCI scope, certifications, uptime, throughput limits, and data residency.


# Billing (/docs/billing)



Run subscriptions, send invoices, configure dunning + a self-serve customer portal.



## Get started [#get-started]

<Cards>
  <Card title="Quickstart" href="/docs/billing/quickstart" description="From zero to your first billing call in 5 minutes." />

  <Card title="Concepts" href="/docs/billing/concepts" description="Entity model + lifecycle for Billing." />

  <Card title="API reference" href="/docs/reference/api/billing" description="Per-resource HTTP API for Billing." />
</Cards>

## Common patterns [#common-patterns]

* [Create a subscription](/docs/billing/guides/create-subscription) — start a recurring charge against a saved instrument, with optional trial and proration.
* [Send an invoice](/docs/billing/guides/send-invoice) — issue an ad-hoc invoice and let the customer pay through a hosted page.
* [Launch the customer portal](/docs/billing/guides/launch-customer-portal) — magic-link a customer into a hosted page where they self-serve plan changes, cancellations, and payment methods.
* [Configure dunning](/docs/billing/guides/configure-dunning) — set retry policy and recovery emails so failed renewals self-heal.

## Migrating from another provider [#migrating-from-another-provider]

* [From Stripe](/docs/billing/migration/from-stripe) — side-by-side method, event, and object-model mapping.


# Billing quickstart (/docs/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 [#1-get-an-api-key]

Sign in to the [Easy Labs dashboard](https://dashboard.itseasy.co), 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 [#2-install-the-sdk]

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

Other languages: see [SDKs](/docs/sdks).

## 3. Create a product, price, and subscription [#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.

```ts
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 [#4-verify]

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

```ts
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](/docs/reference/webhooks).

## 5. Next steps [#5-next-steps]

* [Create a subscription](./guides/create-subscription) — full version with trials, proration, and item changes
* [Send an invoice](./guides/send-invoice) — for one-off charges and quote-style billing
* [Configure dunning](./guides/configure-dunning) — retry + recovery on failed renewals
* [Launch the customer portal](./guides/launch-customer-portal) — let customers self-serve


# API changelog (/docs/changelog/api)





<Callout type="info">
  The Easy API doesn't ship a `CHANGELOG.md` yet. Once `easy-api` adds one
  (or its release tags get published), this page will sync from it
  automatically — see the changelog sync target in
  `easy-docs/scripts/sync-content.ts`.
</Callout>

In the meantime, surface-level changes are reflected in the
[API reference](/docs/api), which is regenerated on every staging deploy
from the live `/openapi.json`.


# Changelog (/docs/changelog)



Each SDK ships its own version history. We use [Changesets](https://github.com/changesets/changesets) on the TypeScript packages and per-package versioning on the Ruby gem and Python pip package, so every change lands in its repo's `CHANGELOG.md` and syncs into this section.



## Frontend SDKs [#frontend-sdks]

<Cards>
  <Card title="JavaScript" href="./javascript" description="@easylabs/browser" />

  <Card title="React" href="./react" description="@easylabs/react" />

  <Card title="React Native" href="./react-native" description="@easylabs/react-native" />
</Cards>

## Backend SDKs [#backend-sdks]

<Cards>
  <Card title="Node.js" href="./node" description="@easylabs/node" />

  <Card title="Ruby" href="./ruby" description="easy-sdk gem" />

  <Card title="Python" href="./python" description="easylabs pip package" />
</Cards>

## API [#api]

<Cards>
  <Card title="Easy HTTP API" href="./api" description="OpenAPI surface changes" />
</Cards>


# JavaScript SDK changelog (/docs/changelog/javascript)





<Callout type="info">
  Synced from [`packages/easy-browser/CHANGELOG.md`](https://github.com/itseasyco/easy-sdk/blob/main/packages/easy-browser/CHANGELOG.md) on the latest publish.
  This is the canonical release history for `@easylabs/browser`.
</Callout>

## 0.1.0 [#010]

### Minor Changes [#minor-changes]

Initial release of the framework-agnostic browser SDK. Mirrors Stripe's
`@stripe/stripe-js` shape so consumers on Vue, Angular, Svelte, HTMX,
Astro, and vanilla JS can use Easy Labs without React.

* `createEasyClient({ apiKey, __dev?, __internal_api_url? })` — async
  factory that validates the API key and returns the full `EasyApiClient`
  surface plus browser-specific helpers.
* `mountEmbeddedCheckout(container, options)` — vanilla DOM helper that
  mounts the Easy Labs embedded-checkout iframe, wires the postMessage
  handshake (resize, ready, crypto\_confirmed), and returns a handle with
  `update(clientSecret)` / `unmount()` methods. Functional equivalent of
  the React `<EmbeddedCheckout>` component.
* Re-exports `EasyApiClient`, `EasyApiError`, and every public type from
  `@easylabs/common` so consumers don't need a second import.


# Node.js SDK changelog (/docs/changelog/node)





<Callout type="info">
  Synced from [`packages/easy-node/CHANGELOG.md`](https://github.com/itseasyco/easy-sdk/blob/main/packages/easy-node/CHANGELOG.md) on the latest publish.
  This is the canonical release history for `@easylabs/node`.
</Callout>

## Unreleased [#unreleased]

### BREAKING CHANGES [#breaking-changes]

* Removed balance transfer operations from the SDK surface.
* Migration: Treasury operations are managed internally by Easy Labs.

## 0.0.10 [#0010]

### Patch Changes [#patch-changes]

* 7134a80: Update ProductData for new api contract returning price ids array

## 0.0.9 [#009]

### Patch Changes [#patch-changes-1]

* Added comprehensive subscription management capabilities including subscription plans and customer subscriptions:

  **Subscription Plans:**

  * `getSubscriptionPlans(params?)` - List all subscription plans with optional filtering
  * `getSubscriptionPlan(planId)` - Get a specific subscription plan
  * `createSubscriptionPlan(data)` - Create a new subscription plan with:
    * Billing intervals (DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY)
    * Trial periods with configurable duration
    * Discount phases for promotional pricing
    * Billing defaults (invoice/receipt settings)
  * `updateSubscriptionPlan(planId, data)` - Update an existing plan

  **Customer Subscriptions:**

  * `getSubscriptions(params?)` - List all subscriptions (admin context)
  * `getCustomerSubscriptions(params?)` - Get subscriptions for authenticated customer
  * `getSubscription(subscriptionId)` - Get a specific subscription
  * `createSubscription(data)` - Create a subscription with:
    * Buyer details (name, email, phone)
    * Subscription details (trial overrides, discount overrides)
    * Payment instrument configuration
  * `cancelSubscription(subscriptionId)` - Cancel an active subscription

  **Integration:**

  * Recurring prices now automatically create subscriptions during checkout
  * Mixed cart support (one-time purchases + subscriptions in single transaction)
  * Subscription data included in order line items for tracking

  All list/collection endpoints now support filtering by specific IDs using the `ids` query parameter:

  **Affected Methods:**

  * `getCustomers({ ids: ['cus_123', 'cus_456'] })`
  * `getProducts({ ids: ['prod_123', 'prod_456'] })`
  * `getPrices({ ids: ['price_123', 'price_456'] })`
  * `getOrders({ ids: ['ord_123', 'ord_456'] })`
  * `getTransfers({ ids: ['tfr_123', 'tfr_456'] })`
  * `getSettlements({ ids: ['set_123', 'set_456'] })`
  * `getDisputes({ ids: ['dis_123', 'dis_456'] })`
  * `getSubscriptions({ ids: ['sub_123', 'sub_456'] })`
  * `getSubscriptionPlans({ ids: ['plan_123', 'plan_456'] })`

  This enables efficient batch fetching of specific resources without retrieving entire collections.

  **Updated Return Value:**
  The `checkout()` and related checkout methods now return enhanced data:

  ```typescript
  {
    order: OrderData;              // The created order
    customer: CustomerData;         // Customer information
    subscriptions?: SubscriptionData[]; // Auto-created subscriptions (if cart contains recurring items)
  }
  ```

  **Benefits:**

  * Immediate access to created subscription IDs
  * No need for separate API calls to fetch subscription details
  * Simplified post-checkout subscription management
  * Better support for mixed carts (one-time + recurring)
  * Added comprehensive subscription examples to Node.js and React SDK docs
  * Updated DEVELOPER\_DOCS.md for both packages
  * Enhanced Docusaurus site with subscription management guides
  * Added batch query parameter documentation across all endpoints

  **Checkout Return Value:**
  The checkout methods now return an object with `{ order, customer, subscriptions? }` instead of just the order. Update your code:

  ```typescript
  // Before
  const order = await checkout(data);

  // After
  const { order, customer, subscriptions } = await checkout(data);
  ```

  * Fixed price display for subscription products (now uses subscription\_plan.amount)
  * Improved type safety for discriminated union types (CreatePrice, CreateSubscription)
  * Fixed controlled input warnings in form components

### Patch Changes [#patch-changes-2]

* * Add handlers for getting a customers payment instruments and orders
  * Add handler for updating payment instrument
  * Add handlers for getting order(s) and updating order tags
  * Add handlers for getProductWithPrice(s). This is used for either getting all the prices for a product or a specifc one. Different from returning the default\_price\_id

## 0.0.8 [#008]

### Patch Changes [#patch-changes-3]

* Create `EasyApiClient` class to handle all the interactions with easy-api, this reduced a lot of repetitive code that was happening between the node and react packages
* Add product and price management APIs

## 0.0.7 [#007]

### Patch Changes [#patch-changes-4]

* Update amount handling and type references
* Add customer and transfer retrieval/update methods

## 0.0.6 [#006]

### Patch Changes [#patch-changes-5]

* Refactor types package into common and update configs

## 0.0.5 [#005]

### Patch Changes [#patch-changes-6]

* Add environment-based API URL selection
* Add tags support to customer, instrument, and transfer forms + refactor types

## 0.0.4 [#004]

### Patch Changes [#patch-changes-7]

* Update package to ES module

## 0.0.3 [#003]

### Patch Changes [#patch-changes-8]

* Move workspace pacakge to devDependency

## 0.0.2 [#002]

### Patch Changes [#patch-changes-9]

* Add tsdown bundler

## 0.0.1 [#001]

### Patch Changes [#patch-changes-10]

* Update to use new shared common package and fix api endpoints


# Python SDK changelog (/docs/changelog/python)





<Callout type="info">
  Synced from [`CHANGELOG.md`](https://github.com/itseasyco/easy-sdk-python/blob/main/CHANGELOG.md) on the latest publish.
  This is the canonical release history for `easylabs (pip package)`.
</Callout>

## 0.1.1 [#011]

### Removed [#removed]

* The `dev=True` keyword argument on `Client(...)` and the matching
  `EASY_API_URL_DEV` constant in `easylabs._api_url`. The internal Easy
  Labs dev environment URL is no longer baked into the public package.
  Internal callers who genuinely need to point at a non-public host
  should pass `internal_api_url="https://..."` to `Client(...)`.

  Migration: replace `Client(api_key=..., dev=True)` with
  `Client(api_key=..., internal_api_url="https://...")` if you were
  using it. The standard `sk_test_` → sandbox / `sk_live_` → production
  routing is unchanged.

## 0.1.0 [#010]

First published release of the Python SDK, mirroring `@easylabs/node@0.1.0`.

### Added [#added]

* `easylabs.Client` — instance-style API client (mirrors `createClient` in the
  Node SDK) with namespaced resources (`client.customers.create(...)`).
* HTTP transport built on `httpx`, supporting query encoding, JSON bodies,
  optional `Idempotency-Key` header, and `skipAuth` for embedded-checkout
  public endpoints (`validate` / `confirm`).
* Sandbox / production URL routing — keys prefixed `sk_test_` route to
  `https://sandbox-api.itseasy.co/v1/api`; everything else routes to
  `https://api.itseasy.co/v1/api`. An `internal_api_url=` override is
  available for tests and self-hosted setups.
* Full resource surface (\~80 methods across 21 namespaces): customers,
  payment instruments, transfers (incl. refunds), disputes, settlements,
  products, product prices, orders, subscriptions (incl. items, discounts,
  usage, one-time charges, proration preview, pause/resume), checkout,
  payment links, embedded checkout (incl. config + crypto status), webhook
  endpoints (incl. delivery listings), invoices, coupons, promotion codes,
  authorizations, analytics, compliance forms, dunning config, and revenue
  recovery automations.
* `easylabs.Webhooks.construct_event(...)` — verifies HMAC-SHA256 webhook
  signatures with `hmac.compare_digest` and parses the payload into a typed
  `WebhookEvent` Pydantic model.
* `EASY_EVENT_TYPES` constant — full catalog of webhook event types.
* Error class hierarchy under `easylabs.error.EasyError` with HTTP-status
  subclasses (`AuthenticationError`, `PermissionError`, `NotFoundError`,
  `ConflictError`, `RateLimitError`, `InvalidRequestError`, `ServerError`)
  plus `status`, `code`, `details`, `retry_after_seconds`, and `raw` fields.
* Pydantic v2 response models with `extra="allow"` for forward compatibility.


# React Native SDK changelog (/docs/changelog/react-native)





<Callout type="info">
  Synced from [`packages/easy-react-native/CHANGELOG.md`](https://github.com/itseasyco/easy-sdk/blob/main/packages/easy-react-native/CHANGELOG.md) on the latest publish.
  This is the canonical release history for `@easylabs/react-native`.
</Callout>

## Unreleased [#unreleased]

### BREAKING CHANGES [#breaking-changes]

* Removed balance transfer operations from the SDK surface.
* Migration: Treasury operations are managed internally by Easy Labs.

## 0.0.1 [#001]

### Patch Changes [#patch-changes]

* 7134a80: Update ProductData for new api contract returning price ids array


# React SDK changelog (/docs/changelog/react)





<Callout type="info">
  Synced from [`packages/easy-react/CHANGELOG.md`](https://github.com/itseasyco/easy-sdk/blob/main/packages/easy-react/CHANGELOG.md) on the latest publish.
  This is the canonical release history for `@easylabs/react`.
</Callout>

## Unreleased [#unreleased]

### BREAKING CHANGES [#breaking-changes]

* Removed balance transfer operations from the SDK surface.
* Migration: Treasury operations are managed internally by Easy Labs.

## 0.0.10 [#0010]

### Patch Changes [#patch-changes]

* 7134a80: Update ProductData for new api contract returning price ids array

## 0.0.9 [#009]

### Patch Changes [#patch-changes-1]

* Added comprehensive subscription management capabilities including subscription plans and customer subscriptions:

  **Subscription Plans:**

  * `getSubscriptionPlans(params?)` - List all subscription plans with optional filtering
  * `getSubscriptionPlan(planId)` - Get a specific subscription plan
  * `createSubscriptionPlan(data)` - Create a new subscription plan with:
    * Billing intervals (DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY)
    * Trial periods with configurable duration
    * Discount phases for promotional pricing
    * Billing defaults (invoice/receipt settings)
  * `updateSubscriptionPlan(planId, data)` - Update an existing plan

  **Customer Subscriptions:**

  * `getSubscriptions(params?)` - List all subscriptions (admin context)
  * `getCustomerSubscriptions(params?)` - Get subscriptions for authenticated customer
  * `getSubscription(subscriptionId)` - Get a specific subscription
  * `createSubscription(data)` - Create a subscription with:
    * Buyer details (name, email, phone)
    * Subscription details (trial overrides, discount overrides)
    * Payment instrument configuration
  * `cancelSubscription(subscriptionId)` - Cancel an active subscription

  **Integration:**

  * Recurring prices now automatically create subscriptions during checkout
  * Mixed cart support (one-time purchases + subscriptions in single transaction)
  * Subscription data included in order line items for tracking

  All list/collection endpoints now support filtering by specific IDs using the `ids` query parameter:

  **Affected Methods:**

  * `getCustomers({ ids: ['cus_123', 'cus_456'] })`
  * `getProducts({ ids: ['prod_123', 'prod_456'] })`
  * `getPrices({ ids: ['price_123', 'price_456'] })`
  * `getOrders({ ids: ['ord_123', 'ord_456'] })`
  * `getTransfers({ ids: ['tfr_123', 'tfr_456'] })`
  * `getSettlements({ ids: ['set_123', 'set_456'] })`
  * `getDisputes({ ids: ['dis_123', 'dis_456'] })`
  * `getSubscriptions({ ids: ['sub_123', 'sub_456'] })`
  * `getSubscriptionPlans({ ids: ['plan_123', 'plan_456'] })`

  This enables efficient batch fetching of specific resources without retrieving entire collections.

  **Updated Return Value:**
  The `checkout()` and related checkout methods now return enhanced data:

  ```typescript
  {
    order: OrderData;              // The created order
    customer: CustomerData;         // Customer information
    subscriptions?: SubscriptionData[]; // Auto-created subscriptions (if cart contains recurring items)
  }
  ```

  **Benefits:**

  * Immediate access to created subscription IDs
  * No need for separate API calls to fetch subscription details
  * Simplified post-checkout subscription management
  * Better support for mixed carts (one-time + recurring)
  * Added comprehensive subscription examples to Node.js and React SDK docs
  * Updated DEVELOPER\_DOCS.md for both packages
  * Enhanced Docusaurus site with subscription management guides
  * Added batch query parameter documentation across all endpoints

  **Checkout Return Value:**
  The checkout methods now return an object with `{ order, customer, subscriptions? }` instead of just the order. Update your code:

  ```typescript
  // Before
  const order = await checkout(data);

  // After
  const { order, customer, subscriptions } = await checkout(data);
  ```

  * Fixed price display for subscription products (now uses subscription\_plan.amount)
  * Improved type safety for discriminated union types (CreatePrice, CreateSubscription)
  * Fixed controlled input warnings in form components

### Patch Changes [#patch-changes-2]

* Introduces a new `checkout` method to the EasyProvider context, consolidating and generalizing the checkout logic for both new and existing customers.
* * Add handlers for getting a customers payment instruments and orders
  * Add handler for updating payment instrument
  * Add handlers for getting order(s) and updating order tags
  * Add handlers for getProductWithPrice(s). This is used for either getting all the prices for a product or a specifc one. Different from returning the default\_price\_id

## 0.0.8 [#008]

### Patch Changes [#patch-changes-3]

* Create `EasyApiClient` class to handle all the interactions with easy-api, this reduced a lot of repetitive code that was happening between the node and react packages
* Add product and price management APIs
* Fix type handling for payment instrument params
* Changed anonCheckout & checkoutExistingCustomer to only return the id's of paymentInstrument & transfer instead of the entire data object

## 0.0.7 [#007]

### Patch Changes [#patch-changes-4]

* Support separate card input elements in EasyProvider

## 0.0.6 [#006]

### Patch Changes [#patch-changes-5]

* Update amount handling and type references

## 0.0.5 [#005]

### Patch Changes [#patch-changes-6]

* Refactor types package into common and update configs

## 0.0.4 [#004]

### Patch Changes [#patch-changes-7]

* Switch easy-react to tsdown build system

## 0.0.3 [#003]

### Patch Changes [#patch-changes-8]

* Add environment-based API URL selection
* Add tags support to customer, instrument, and transfer forms + refactor types
* Expose tokenizePaymentInstrument from EasyContext

## 0.0.2 [#002]

### Patch Changes [#patch-changes-9]

* Fixed API endpoints and andded updateCustomer method

## 0.0.1 [#001]

### Patch Changes [#patch-changes-10]

* initial release


# Ruby SDK changelog (/docs/changelog/ruby)





<Callout type="info">
  Synced from [`CHANGELOG.md`](https://github.com/itseasyco/easy-sdk-ruby/blob/main/CHANGELOG.md) on the latest publish.
  This is the canonical release history for `easy-sdk (Ruby gem)`.
</Callout>

All notable changes to `easy-sdk` are documented in this file. The format
follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
project adheres to [Semantic Versioning](https://semver.org/).

## [0.1.0] — Unreleased [#010--unreleased]

Initial release of the Ruby SDK. Mirrors `@easylabs/node` 0.1.0 feature
surface with idiomatic Ruby APIs.

### Added [#added]

* `EasyLabs::Client.new(api_key:)` factory that validates the API key on
  construction and exposes resource namespaces (`client.customers`,
  `client.subscriptions`, etc.).
* Full resource coverage: customers, payment instruments, transfers
  (incl. refunds), disputes, settlements, products, product prices,
  orders, subscriptions (full lifecycle: pause/resume, items, discounts,
  one-time charges, metered usage, proration preview), checkout,
  payment links, embedded checkout (incl. validate/confirm/config),
  webhook management, invoices, coupons, promotion codes,
  authorizations, analytics, compliance forms, dunning config,
  revenue-recovery automations.
* `EasyLabs::Webhooks.construct_event` HMAC-SHA256 verifier with the
  full `EVENT_TYPES` catalog.
* Typed exception hierarchy under `EasyLabs::Error` (AuthenticationError,
  PermissionError, NotFoundError, ConflictError, RateLimitError,
  InvalidRequestError, ServerError) with `status`, `code`, `details`,
  `retry_after_seconds`, and `raw` accessors.
* Sandbox auto-routing — `sk_test_*` keys hit `sandbox-api.itseasy.co`
  automatically.

[0.1.0]: https://github.com/itseasyco/easy-sdk-ruby/releases/tag/v0.1.0


# Payments compliance & scale (/docs/payments/compliance)



{/* TODO: Single-page summary. For now, link to the shared compliance page: */}

See the cross-product [Reference → Compliance](/docs/reference/compliance) page for security model, PCI scope, certifications, uptime, throughput limits, and data residency.


# Payments (/docs/payments)



Accept one-time payments, embed checkout, manage payment instruments + disputes.



## Get started [#get-started]

<Cards>
  <Card title="Quickstart" href="/docs/payments/quickstart" description="From zero to your first payments call in 5 minutes." />

  <Card title="Concepts" href="/docs/payments/concepts" description="Entity model + lifecycle for Payments." />

  <Card title="API reference" href="/docs/reference/api/payments" description="Per-resource HTTP API for Payments." />
</Cards>

## Common patterns [#common-patterns]

* [Embed hosted checkout](/docs/payments/guides/embed-hosted-checkout) — drop the iframe in for first-time card payments without taking on PCI scope.
* [Accept a card payment](/docs/payments/guides/accept-card-payment) — server-to-server charge against a saved Payment Instrument.
* [Accept a wallet payment](/docs/payments/guides/accept-wallet-payment) — opt the iframe into Solana / USDC checkout for the same session.
* [Handle a dispute](/docs/payments/guides/handle-dispute) — react to chargeback webhooks and correlate them back to your Order.

## Migrating from another provider [#migrating-from-another-provider]

* [Migrate from Stripe](/docs/payments/migration/from-stripe) — method-by-method and event-by-event mapping.


# Payments quickstart (/docs/payments/quickstart)



This walks the shortest path: install `@easylabs/node`, create a Customer, mount an Embedded Checkout session, and verify the resulting Order. End-to-end this is a few minutes of typing.

## 1. Get an API key [#1-get-an-api-key]

Sign in to the [Easy Labs dashboard](https://dashboard.itseasy.co), 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_...`) once you are ready to go live; the SDK auto-routes based on the key prefix.

## 2. Install the SDK [#2-install-the-sdk]

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

For browser flows install one of:

```bash
npm install @easylabs/react   # React apps
npm install @easylabs/browser # vanilla JS
```

Other languages: see [SDKs](/docs/sdks).

## 3. Create a Customer and start a checkout session [#3-create-a-customer-and-start-a-checkout-session]

This snippet runs on your server. It creates a Customer and an Embedded Checkout session that you can hand to the browser.

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

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

// 1. Create the buyer.
const { data: customer } = await easy.createCustomer({
  first_name: "Ada",
  last_name: "Lovelace",
  email: "ada@example.com",
});

// 2. Start an embedded checkout session for one product price.
const { data: session } = await easy.createEmbeddedCheckoutSession({
  mode: "payment",
  customer_email: customer.entity.email,
  line_items: [{ price_id: "price_01HXXXXXXXXXXX", quantity: 1 }],
  success_url: "https://your-app.com/checkout/success",
  cancel_url: "https://your-app.com/checkout/cancel",
  payment_methods: ["card"],
});

// Send `session.client_secret` to the browser. Do NOT send the API key.
return Response.json({ clientSecret: session.client_secret });
```

On the browser, render the iframe. With React:

```tsx
import { EmbeddedCheckout, EmbeddedCheckoutProvider } from "@easylabs/react";

export function Checkout({ clientSecret }: { clientSecret: string }) {
  return (
    <EmbeddedCheckoutProvider
      config={{
        clientSecret,
        onSuccess: ({ sessionId }) => console.log("paid", sessionId),
      }}
    >
      <EmbeddedCheckout clientSecret={clientSecret} />
    </EmbeddedCheckoutProvider>
  );
}
```

## 4. Verify [#4-verify]

After the buyer completes the iframe, you can confirm server-side:

```ts
const { data: status } = await easy.getEmbeddedCheckoutSession(session.id);
console.log(status.status, status.payment_status);
// → "complete" "paid"
```

Or open the [dashboard](https://dashboard.itseasy.co) and look for the new Order under **Payments → Orders**.

## 5. Next steps [#5-next-steps]

* [Accept a card payment](./guides/accept-card-payment) — direct server-to-server charge against a saved Payment Instrument.
* [Embed hosted checkout](./guides/embed-hosted-checkout) — production-grade embed with success / cancel / error handling.
* [Issue a refund](./guides/issue-refund) — partial and full reversals.
* [Migrate from Stripe](./migration/from-stripe) — method-by-method mapping.


# Compliance & scale (/docs/reference/compliance)



{/* TODO: Cross-product compliance summary. Should cover:
    - PCI DSS scope (Easy holds PCI; merchants offload via Elements/Embedded)
    - SOC 2 / ISO 27001 status (or roadmap)
    - Encryption at rest + in transit
    - Data residency
    - Uptime SLA (link to status page)
    - Rate limits
    - Webhooks delivery guarantees
  */}


# Webhooks (/docs/reference/webhooks)



Easy Labs delivers asynchronous notifications about account activity by `POST`-ing JSON to an HTTPS endpoint you register. Use webhooks to react to payments completing, subscriptions renewing, disputes opening, or settlements landing — without polling.

## Quickstart [#quickstart]

1. Register an endpoint via the [`webhooks` API](/docs/reference/api/account-and-operations/webhooks) or the dashboard. You'll get a one-time `secret` — store it immediately, it's never re-exposed.
2. Receive deliveries at your URL — Easy Labs `POST`s a signed JSON payload.
3. Verify the signature with [`EasyWebhooks.constructEvent`](#verifying-deliveries) before trusting the payload.
4. Respond `2xx` within 30 seconds. Anything else triggers a retry.

```ts
import express from 'express';
import { EasyWebhooks } from '@easylabs/node';

const app = express();

// IMPORTANT: use raw body — JSON re-stringifying breaks the signature.
app.post(
  '/webhooks/easy',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const event = EasyWebhooks.constructEvent(
      req.body.toString('utf8'),
      req.header('x-easy-webhook-signature') ?? '',
      process.env.EASY_WEBHOOK_SECRET!,
    );

    switch (event.type) {
      case 'payment.created':
        // ...
        break;
      case 'subscription.updated':
        // ...
        break;
    }

    res.status(204).end();
  },
);
```

## Delivery format [#delivery-format]

Each delivery is an HTTPS `POST` to your registered endpoint URL with these headers:

| Header                     | Value                                                                             |
| -------------------------- | --------------------------------------------------------------------------------- |
| `content-type`             | `application/json`                                                                |
| `x-easy-webhook-signature` | `sha256=<hex>` — HMAC-SHA256 of the raw body using your endpoint's signing secret |
| `x-easy-event`             | The event type, e.g. `payment.created`                                            |
| `x-easy-delivery-id`       | UUID identifying this specific delivery attempt                                   |
| `x-easy-webhook-attempt`   | Attempt number, `"1"` through `"3"`                                               |

The body is a JSON `WebhookEvent`:

```json
{
  "id": "evt_01HABCDEFGHIJK",
  "type": "payment.created",
  "created_at": "2026-05-03T12:34:56.789Z",
  "created": "2026-05-03T12:34:56.789Z",
  "api_version": "2026-05-01",
  "data": { /* event-specific payload */ },
  "previous_attributes": { /* present on `*.updated` events */ },
  "requested": {
    "id": "req_01HXYZ...",
    "idempotency_key": "your-key"
  }
}
```

## Verifying deliveries [#verifying-deliveries]

The signing secret returned at registration is your shared key. Verify every delivery before acting on it — anyone who knows your endpoint URL can `POST` to it.

### Node.js [#nodejs]

```ts
import { EasyWebhooks } from '@easylabs/node';

const event = EasyWebhooks.constructEvent(
  rawBody,                                   // exact request body string
  req.header('x-easy-webhook-signature')!,   // sha256=<hex>
  process.env.EASY_WEBHOOK_SECRET!,
);
```

`constructEvent` throws an `EasyApiError` (status 400) on any of:

* Missing or malformed signature header
* Signature is not valid hex
* Signature does not match the computed HMAC (timing-safe comparison)
* Body is not valid JSON

On success it returns a typed `WebhookEvent`.

### Other languages [#other-languages]

The verification recipe is identical: `HMAC-SHA256(body, secret)`, hex-encoded, prefixed with `sha256=`, compared in constant time.

```python
# Python — manual verification (SDK helper coming soon)
import hashlib, hmac

expected = 'sha256=' + hmac.new(
    secret.encode('utf-8'),
    raw_body.encode('utf-8'),
    hashlib.sha256,
).hexdigest()

if not hmac.compare_digest(expected, signature_header):
    raise ValueError('Invalid webhook signature')
```

```ruby
# Ruby — manual verification (SDK helper coming soon)
require 'openssl'

expected = 'sha256=' + OpenSSL::HMAC.hexdigest('SHA256', secret, raw_body)

unless Rack::Utils.secure_compare(expected, signature_header)
  raise 'Invalid webhook signature'
end
```

Native `EasyWebhooks` helpers for Ruby and Python ship with a future SDK round — until then, use the manual verification above.

### Replay protection [#replay-protection]

The current signature covers the body only — there is **no signed timestamp**. If you receive the same `x-easy-delivery-id` twice (because Easy Labs retried after a network blip and your server actually succeeded), idempotency is your responsibility: dedupe on `event.id` or `x-easy-delivery-id`.

A signed timestamp + `tolerance:` parameter is on the [SDK gap-fix tracker](https://github.com/itseasyco/easy-sdk/blob/main/docs/sdk-gap-fix-tracker.md) (item #2). When it ships, `EasyWebhooks.constructEvent` will accept a `tolerance` argument and reject deliveries older than the window.

## Retry behavior [#retry-behavior]

Easy Labs retries any delivery that doesn't return a `2xx` within 30 seconds. The dispatcher attempts each delivery up to **3 times** before giving up, with exponential backoff between attempts. The attempt count is exposed on every delivery via `x-easy-webhook-attempt`.

If your endpoint fails enough consecutive deliveries, the endpoint's `consecutive_failures` counter increments and Easy Labs eventually marks it `disabled`. Re-enable it via the dashboard or the [update endpoint API](/docs/reference/api/account-and-operations/webhooks).

To replay a delivery on demand, find it in the dashboard's webhook log and click "Resend" — useful for testing handlers without waiting for real activity.

## Event types [#event-types]

Subscribe to specific events when registering an endpoint, or use `["*"]` to catch everything. The full catalog (37 event types as of `api_version 2026-05-01`):

### Payments [#payments]

* `payment.created` — a new payment is initiated
* `payment.updated` — payment status changed (succeeded, failed, refunded, etc.)
* `refund.created` — a refund is initiated
* `refund.updated` — refund status changed
* `authorization.created` — an authorization is created (manual capture flow)
* `authorization.updated` — authorization status changed
* `authorization.voided` — authorization explicitly voided
* `dispute.created` — a chargeback or pre-dispute opens
* `dispute.updated` — dispute moves through its lifecycle (under-review, won, lost, etc.)
* `checkout.session.completed` — a hosted/embedded Checkout session closes successfully
* `checkout.session.crypto_confirmed` — a crypto checkout confirms on-chain

### Billing [#billing]

* `subscription.created` — a new subscription is created
* `subscription.updated` — subscription fields change (plan, quantity, billing cycle, etc.)
* `subscription.deleted` — subscription canceled
* `subscription.paused` — subscription paused (collection paused or fully halted)
* `subscription.resumed` — subscription resumed
* `subscription.trial_will_end` — fires 3 days before a trial ends
* `subscription.pending_update_applied` — a scheduled update took effect
* `subscription.pending_update_expired` — a scheduled update expired before applying
* `invoice.created` — a draft invoice is created
* `invoice.finalized` — invoice is finalized and ready to send/charge
* `invoice.paid` — invoice fully paid
* `invoice.payment_failed` — payment attempt failed (triggers dunning)
* `invoice.upcoming` — fires before the next renewal so you can preview the invoice
* `invoice.voided` — invoice voided
* `invoice.marked_uncollectible` — invoice flagged unrecoverable
* `revenue_recovery.action_completed` — a dunning recovery step fired (retry, email, etc.)
* `coupon.created` / `coupon.updated` / `coupon.deleted`
* `promotion_code.created` / `promotion_code.updated` / `promotion_code.deleted`

### Treasury [#treasury]

* `settlement.created` — a settlement batch lands

### Account [#account]

* `identity.created` — KYB / merchant identity record created
* `identity.updated` — KYB / merchant identity record changed (incl. status transitions)

### Test [#test]

* `test.webhook` — fires when you click "Send test event" in the dashboard

## Endpoint management [#endpoint-management]

Webhook endpoints are managed under the [account-and-operations API](/docs/reference/api/account-and-operations/webhooks):

* `POST /webhooks` — register a new endpoint (returns the signing `secret` once)
* `GET /webhooks` — list endpoints
* `GET /webhooks/{id}` — get a single endpoint (no secret in response)
* `PATCH /webhooks/{id}` — update URL, events, or active status
* `DELETE /webhooks/{id}` — remove an endpoint

Each endpoint exposes:

```ts
interface WebhookEndpoint {
  id: string;
  url: string;
  events: string[];                  // e.g. ["payment.created", "*"]
  active: boolean;
  status: 'enabled' | 'disabled';
  consecutive_failures: number;
  last_triggered_at: string | null;
  created_at: string;
  updated_at: string;
}
```

## Inspecting deliveries [#inspecting-deliveries]

Every delivery attempt is logged. Query the delivery log to debug failures or replay events:

```ts
const deliveries = await client.listWebhookDeliveries({
  endpoint_id: 'whe_01HABCD...',
  success: false,
  created_after: '2026-05-01T00:00:00Z',
  limit: 50,
});
```

The dashboard surfaces the same data with one-click "Resend" — useful for replaying without writing code.

## Related [#related]

* [Webhooks API](/docs/reference/api/account-and-operations/webhooks) — endpoint management operations
* [Node SDK reference](/docs/sdks/node) — `EasyWebhooks.constructEvent` and the `WebhookEvent` type
* [SDK gap-fix tracker #2](https://github.com/itseasyco/easy-sdk/blob/main/docs/sdk-gap-fix-tracker.md) — signed timestamp + replay protection roadmap


# SDKs (/docs/sdks)





<Cards>
  <Card title="JavaScript" href="/docs/sdks/javascript" description="@easylabs/browser — vanilla JS for any framework" />

  <Card title="React" href="/docs/sdks/react" description="@easylabs/react — hooks, providers, and elements" />

  <Card title="React Native" href="/docs/sdks/react-native" description="@easylabs/react-native — native iOS + Android" />

  <Card title="Node.js" href="/docs/sdks/node" description="@easylabs/node — TypeScript-first server SDK" />

  <Card title="Ruby" href="/docs/sdks/ruby" description="easy-sdk gem — idiomatic Ruby" />

  <Card title="Python" href="/docs/sdks/python" description="easylabs pip package — Pythonic with full type hints" />

  <Card title="MCP Server" href="/docs/sdks/mcp" description="@easylabs/mcp-server — Model Context Protocol surface for AI agents" />
</Cards>


# Treasury compliance & scale (/docs/treasury/compliance)



{/* TODO: Single-page summary. For now, link to the shared compliance page: */}

See the cross-product [Reference → Compliance](/docs/reference/compliance) page for security model, PCI scope, certifications, uptime, throughput limits, and data residency.


# Treasury (/docs/treasury)



Send payouts to bank accounts, manage recipients, generate payout links + tax documents.



## Get started [#get-started]

<Cards>
  <Card title="Quickstart" href="/docs/treasury/quickstart" description="From zero to your first treasury call in 5 minutes." />

  <Card title="Concepts" href="/docs/treasury/concepts" description="Entity model + lifecycle for Treasury." />

  <Card title="API reference" href="/docs/reference/api/treasury" description="Per-resource HTTP API for Treasury." />
</Cards>

## Common patterns [#common-patterns]

* [Send a payout](/docs/treasury/guides/send-payout) — debit a funding account and credit a recipient over ACH, RTP, or wire.
* [Invite a recipient](/docs/treasury/guides/invite-recipient) — let recipients enter their own banking via a 72-hour self-serve link instead of collecting account numbers yourself.
* [Generate a payout link](/docs/treasury/guides/generate-payout-link) — share a single-use, fixed-amount link with someone who isn't a recipient yet.
* [Request a W-9](/docs/treasury/guides/request-w9) — capture a US recipient's tax info ahead of year-end 1099 issuance.


# Treasury quickstart (/docs/treasury/quickstart)



This walks the smallest end-to-end happy path: create a recipient with a bank
account attached, then send them a payout. Server-side, in Node.

## 1. Get an API key [#1-get-an-api-key]

In the [Easy Dashboard](https://app.itseasy.co), open **Settings → API keys**
and create a sandbox key (`sk_sandbox_…`). Copy it immediately — secret keys
are shown only once.

## 2. Install the SDK [#2-install-the-sdk]

```bash
npm install @easylabs/node
```

## 3. Create a recipient + send a payout [#3-create-a-recipient--send-a-payout]

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

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

// 3a. Create the recipient with their bank account in one call.
const { data: recipient } = await client.createRecipient({
  name: "Ada Lovelace",
  email: "ada@example.com",
  type: "person",
  payment_methods: [
    {
      method_type: "ach",
      account_type: "checking",
      routing_number: "021000021",     // Chase test routing
      account_number: "000123456789",  // tokenized server-side
    },
  ],
});

// 3b. List your funding accounts and pick one to debit.
const { data: funding } = await client.listBankAccounts();
const sourceAccount = funding[0];

// 3c. Initiate the payout. Amounts are USD cents.
const { data: payout } = await client.createPayout({
  recipient_id: recipient.id,
  source_account_id: sourceAccount.id,
  amount: 5_000,            // $50.00
  method: "ach",
  memo: "Invoice #1024",
});

// 3d. Confirm. (Pass `security_code` if your security rules require 2FA.)
await client.confirmPayout({ transaction_id: payout.id });
```

## 4. Verify [#4-verify]

Open **Treasury → Transactions** in the dashboard — your payout will be in
`processing`. Or fetch it programmatically:

```ts
const { data } = await client.getTransaction(payout.id);
console.log(data.status); // "processing" → "completed"
```

When the underlying [settlement](./concepts/settlement) is funded, a
`settlement.created` webhook fires. See
[Webhooks](/docs/sdks/node/webhooks) to wire that up.

## 5. Next steps [#5-next-steps]

* [Send a payout](./guides/send-payout) — full reference for the send flow,
  including reversibility, rail trade-offs, and error handling.
* [Invite a recipient](./guides/invite-recipient) — let recipients enter their
  own banking through Plaid Link instead of collecting account numbers.
* [Generate a payout link](./guides/generate-payout-link) — share a link with
  someone who isn't a recipient yet.
* [API reference](/docs/reference/api/treasury) — all Treasury endpoints.


# Coupon and Promotion Code (/docs/billing/concepts/coupon-and-promotion-code)



A **Coupon** is a reusable discount definition (percent or fixed amount, with a duration). A **Promotion Code** is a customer-redeemable shortcode that points at exactly one coupon and adds redemption controls (validity window, redemption cap, first-time-only, minimum amount). You apply a coupon directly when you have one in hand server-side; you accept a promotion code when a customer types one in.

## Lifecycle [#lifecycle]

1. **Create the coupon** with `createCoupon` — choose `percent_off` *or* `amount_off + currency`, plus `duration` (`once`, `repeating`, `forever`). For `repeating`, set `duration_in_months`.
2. **Optionally create promotion codes** with `createPromotionCode` referencing the `coupon_id`. The same coupon can back many codes.
3. **Validate** a code before applying with `validatePromotionCode` — returns `valid`, the resolved `coupon`, and a `discount_preview`.
4. **Apply** to a subscription via `applySubscriptionDiscount` (pass either `coupon_id` or `promotion_code`); scope to a single subscription item with `subscription_item_id` if needed.
5. **Remove** with `removeSubscriptionDiscount` to end the discount before its natural expiry. Coupons and promotion codes can be soft-disabled via `active: false` (`updateCoupon` / `updatePromotionCode`) or deleted outright.

## Relationships [#relationships]

A `PromotionCodeData` always points at one `CouponData` (`coupon_id`). When applied to a subscription, both surface as a `SubscriptionDiscount` row referencing `coupon_id` and/or `promotion_code_id`. Coupons may be scoped to a subset of products via `applies_to_products`, in which case only invoice line items whose `price_id` belongs to one of those products receive the discount.

## Fields that matter [#fields-that-matter]

* **Coupon `duration`** (`once` | `repeating` | `forever`) — controls how many billing cycles the discount applies for. `repeating` requires `duration_in_months`.
* **Coupon `percent_off`** (`number`, 0–100) **or*&#x2A; &#x2A;*`amount_off`** (`number`, smallest currency unit) — exactly one is set; `amount_off` requires `currency`.
* **Coupon `max_redemptions`*&#x2A; / &#x2A;*`times_redeemed`** — global cap across all customers; `applies_to_products` scopes the discount to specific products.
* **Promotion code `code`** (`string`) — the human-typed token. Case is preserved as stored.
* **Promotion code `first_time_only`** (`boolean`) — restricts to a customer's first redemption against this coupon family.
* **Promotion code `minimum_amount`** (`number`) — the invoice or subscription subtotal that must be reached for the code to apply.

## Related [#related]

* [API reference: Coupons](/docs/reference/api/billing/coupons)
* [API reference: Promotion codes](/docs/reference/api/billing/promotion-codes)
* [Guide: Apply a coupon](../guides/apply-coupon)


# Customer portal (/docs/billing/concepts/customer-portal)



The **Customer portal** is a hosted, white-label page where a customer can update payment methods, change plans, view invoices, and cancel subscriptions without leaving the merchant brand. There are two pieces: the **portal config** (`customer-portal-config`) — a per-merchant policy for what's enabled and how cancellations behave — and the **access flow** (`customer-portal/access/*`) — magic-link-based authentication that mints a session for one specific customer.

## Lifecycle [#lifecycle]

1. **Configure** the portal via `PATCH /customer-portal-config` — toggle features (`payment_methods_enabled`, `subscriptions_enabled`, `cancellations_enabled`), pick `cancellation_mode` (`immediately` or `end_of_period`), set `allow_plan_switch`, restrict `subscription_product_ids`, and supply a `return_url`.
2. **Request a link** by calling `POST /customer-portal/access/request-link` with the customer's `email`, `company_id`, and a `destination` (`home`, `payment_methods`, or `billing_information`). The platform emails the customer a magic link.
3. **Customer clicks the link**, which lands on the hosted portal and calls `POST /customer-portal/access/consume` to exchange the token for a portal session.
4. **In-portal actions** — payment-method add/remove, subscription cancel, plan switch, invoice download — all execute against the portal-scoped session, not your API key.
5. **Customer signs out** or the session expires; sign-out is `POST /customer-portal/access/sign-out`.

## Relationships [#relationships]

The portal acts on the same [Customer](../../payments/concepts/customer), [Subscription](./subscription), and [Invoice](./invoice) records as the merchant API. Cancellations applied through the portal honor `cancellation_mode` and `cancellation_proration_enabled`, and may attach a `retention_coupon_id` automatically if configured. The portal is also the recommended `payment_failed_custom_link_url` target for [Dunning config](./dunning-config) so customers can fix failed payments themselves.

## Fields that matter [#fields-that-matter]

* **`payment_methods_enabled`*&#x2A; + &#x2A;*`accepted_payment_methods`** (`string[]`) — gate which instruments customers can add (e.g. card, bank account) and whether the section appears at all.
* **`subscriptions_enabled`*&#x2A; + &#x2A;*`allow_plan_switch`*&#x2A; + &#x2A;*`allow_quantity_updates`** — control the self-serve subscription management surface; restrict the catalog with `subscription_product_ids`.
* **`cancellations_enabled`*&#x2A; + &#x2A;*`cancellation_mode`** (`immediately` | `end_of_period&#x60;) + &#x2A;*`cancellation_proration_enabled`** — define the cancel UX. `cancellation_reasons_enabled` + `cancellation_reasons` (`string[]`) collect a structured reason; `retention_coupon_id` offers a discount during the cancel flow.
* **`subscription_proration_behavior`** (`none` | `prorate` | `full_difference&#x60;) + &#x2A;*`subscription_charge_timing`** (`immediately` | `period_end`) — billing semantics for plan changes initiated from the portal.
* **`return_url`** (`string | null`) — where the portal sends the customer when they exit; used by the post-cancellation and post-update flows.
* **`portal_header`*&#x2A; + &#x2A;*`custom_domain_id`** — branding overrides for the hosted page.

## Related [#related]

* [API reference: Customer portal](/docs/reference/api/billing/customer-portal)
* [API reference: Customer portal config](/docs/reference/api/billing/customer-portal-config)
* [Guide: Launch the customer portal](../guides/launch-customer-portal)


# Dunning config (/docs/billing/concepts/dunning-config)



The **Dunning config** is the per-merchant policy for what happens when a recurring charge fails: how many times to retry, on what schedule, what email to send, where to send the customer to fix it, and what terminal state to move the subscription or invoice into when retries are exhausted. There is exactly one config per merchant; it applies to every subscription and `charge_automatically` invoice.

## Lifecycle [#lifecycle]

1. **Create or replace** the config with `createOrReplaceDunningConfig`. New merchants start with no config and the engine falls back to safe defaults until one exists.
2. **Read** the current policy with `getDunningConfig`.
3. **Patch** individual fields with `updateDunningConfig` — useful for toggling email enablement or swapping a recovery page mode without re-stating the full schedule.
4. The engine consults the config on every payment failure. It picks a retry slot from `smart_retry_window` (with `smart_retry_attempts` total) or steps through `custom_retry_schedule`. Bank-debit retries follow `bank_debit_retry_schedule` when `bank_debit_retries_enabled` is `true`.
5. When retries are exhausted, the engine applies `subscription_terminal_action` to the subscription (`cancel`, `unpaid`, `past_due`, `pause`) and `invoice_terminal_action` to any open invoice (`past_due`, `uncollectible`). `invoice.marked_uncollectible` and `subscription.updated` events fire accordingly.

## Relationships [#relationships]

The dunning config governs every [Subscription](./subscription) and every [Invoice](./invoice) collected with `collection_method: "charge_automatically"`. Recovery emails link customers to either a hosted recovery page or a `custom_link_url` you supply (typically the [Customer portal](./customer-portal)). For event-driven workflows beyond retries, layer **revenue-recovery automations** on top via `createRevenueRecoveryAutomation` — these are conditional rules that fire on triggers like `invoice_overdue` and `subscription_payment_failed`.

## Fields that matter [#fields-that-matter]

* **`retry_mode`** (`smart` | `custom`) — `smart` uses the platform-tuned schedule sized by `smart_retry_window` (`1_week`, `2_weeks`, `3_weeks`, `1_month`, `2_months`) and `smart_retry_attempts` (`4` or `8`); `custom` follows `custom_retry_schedule` (array of day offsets).
* **`bank_debit_retries_enabled`*&#x2A; + &#x2A;*`bank_debit_retry_schedule`** — separate retry track for ACH/bank-debit failures, which have different reason codes and longer settlement windows than card declines.
* **`subscription_terminal_action`** (`cancel` | `unpaid` | `past_due` | `pause`) — what state the subscription lands in after the final retry fails.
* **`invoice_terminal_action`** (`past_due` | `uncollectible`) — what state the invoice lands in. `uncollectible` emits `invoice.marked_uncollectible` and stops further automated collection.
* **`payment_failed_email_enabled`*&#x2A; / &#x2A;*`expiring_card_email_enabled`*&#x2A; / &#x2A;*`email_action_required`** — toggles for the three customer-facing email types the engine sends.
* **`payment_failed_recovery_page_mode`*&#x2A; + &#x2A;*`payment_failed_custom_link_url`** — `hosted` directs to the white-label recovery page; `custom_link` deep-links to your own URL (e.g. a customer portal session).

## Related [#related]

* [API reference: Dunning](/docs/reference/api/billing/auto-pay)
* [Guide: Configure dunning](../guides/configure-dunning)
* [Guide: Launch the customer portal](../guides/launch-customer-portal)


# Billing concepts (/docs/billing/concepts)



The Billing surface is built around 6 core entities. Each page covers what the entity is, how its lifecycle progresses, and how it relates to the rest of the model.



<Cards>
  <Card title="Subscription" href="./concepts/subscription" description="The Subscription entity in Billing." />

  <Card title="Product And Price" href="./concepts/product-and-price" description="The Product And Price entity in Billing." />

  <Card title="Invoice" href="./concepts/invoice" description="The Invoice entity in Billing." />

  <Card title="Coupon And Promotion Code" href="./concepts/coupon-and-promotion-code" description="The Coupon And Promotion Code entity in Billing." />

  <Card title="Dunning Config" href="./concepts/dunning-config" description="The Dunning Config entity in Billing." />

  <Card title="Customer Portal" href="./concepts/customer-portal" description="The Customer Portal entity in Billing." />
</Cards>


# Invoice (/docs/billing/concepts/invoice)



An **Invoice** is a billable statement issued to a customer. It collects line items, taxes, discounts, and shipping into a single `total_amount`, tracks how much has been collected (`amount_paid` / `amount_due`), and exposes the actions to deliver, charge, remind, void, or render a PDF. Invoices come from two sources: created directly via `createInvoice` for ad-hoc billing, or generated automatically by the [Subscription](./subscription) engine at each cycle.

## Lifecycle [#lifecycle]

1. **`DRAFT`** — created and editable. Patch with `updateInvoice` to add items, change amounts, or move dates.
2. **`OPEN`** — finalized and ready for collection. Subscription-generated invoices skip straight to `OPEN`.
3. **`SENT` / `VIEWED`** — `sendInvoice` delivers the email and (optionally) attaches the PDF; `last_sent_at` and `last_viewed_at` track engagement. Emits `invoice.created`, `invoice.finalized`.
4. **`OVERDUE` / `PARTIALLY_PAID`** — past `due_date` with an outstanding balance. Dunning may take over for `charge_automatically` invoices. Emits `invoice.payment_failed`.
5. **`PAID`** — `amount_due` reaches zero via `payInvoice` or the customer's hosted payment page. Emits `invoice.paid`.
6. **`VOID` / `VOIDED`** — terminated by `voidInvoice` or by a dunning terminal action. Emits `invoice.voided` or `invoice.marked_uncollectible`.

## Relationships [#relationships]

An invoice references a buyer through `buyer_id` (a [Customer](../../payments/concepts/customer)) and may be linked from a [Subscription](./subscription) via `latest_invoice_id`. Each `InvoiceItem` may carry a `price_id` (linking back to a [Price](./product-and-price)) and `coupon_ids` for line-level discounts. Successful payments produce transfers visible under the customer's order history.

## Fields that matter [#fields-that-matter]

* **`status`** (`InvoiceStatus`) — `DRAFT`, `OPEN`, `SENT`, `VIEWED`, `OVERDUE`, `PARTIALLY_PAID`, `PAID`, `UNPAID`, `VOID`, `VOIDED`.
* **`collection_method`** (`charge_automatically` | `send_invoice`) — `charge_automatically` runs `payInvoice` against the customer's default instrument when the invoice opens; `send_invoice` waits for the customer to pay via the hosted page.
* **`items`** (`InvoiceItem[]`) — each line carries `description`, `quantity`, `unit_price` (smallest currency unit), and optionally `price_id`, `coupon_ids`, `manual_tax_rate`.
* **`due_date`** (ISO date) — required on create; drives `OVERDUE` and reminder behavior.
* **`is_recurring`*&#x2A; + &#x2A;*`recurrence_interval`** — generates child invoices on `WEEKLY` / `BIWEEKLY` / `MONTHLY` / `QUARTERLY` / `YEARLY` cadence; pair with `recurrence_auto_send` to skip the manual send step.
* **`amount_due`*&#x2A; / &#x2A;*`amount_paid`*&#x2A; / &#x2A;*`total_amount`** (number, smallest currency unit) — the running balance the dunning engine and webhooks act on.

## Related [#related]

* [API reference](/docs/reference/api/billing/invoices)
* [Guide: Send an invoice](../guides/send-invoice)
* [Guide: Configure dunning](../guides/configure-dunning)


# Product and Price (/docs/billing/concepts/product-and-price)



A **Product** is the catalog entry for something you sell — a plan, a feature pack, a one-off SKU. A **Price** is a specific monetary amount + currency + recurrence attached to a product. A product may have many prices (currency variants, monthly vs. yearly, grandfathered tiers); subscriptions and invoices charge against a Price ID, never a Product ID.

## Lifecycle [#lifecycle]

1. **Create the product** with `createProduct`. `active: true` makes it usable for new prices and checkouts.
2. **Create one or more prices** with `createPrice`, passing the `product_id`. Prices are immutable in terms of `unit_amount`, `currency`, and recurrence — to change the amount, create a new price and migrate subscriptions.
3. **Set a default** by patching `default_price_id` on the product so checkouts and the customer portal can resolve a single price per product.
4. **Archive** with `archiveProduct` or `archivePrice` when retired. Archived products and prices remain valid on existing subscriptions but cannot be selected for new ones.

## Relationships [#relationships]

A `PriceData` belongs to one `ProductData` (`product_id`). [Subscriptions](./subscription) reference prices through `SubscriptionItem.price_id`. [Invoice](./invoice) line items can link to a `price_id` for catalog-driven invoicing or use raw `unit_price` + `description` for ad-hoc lines. [Coupons](./coupon-and-promotion-code) may scope to specific products via `applies_to_products`.

## Fields that matter [#fields-that-matter]

* **Product `name`** (`string&#x60;) and &#x2A;*`description`** (`string`) — surfaced on hosted invoices, checkouts, and the customer portal.
* **Product `default_price_id`** (`string`) — the price used when callers don't specify one (e.g. customer portal plan switcher).
* **Price `unit_amount`** (`number&#x60;, smallest currency unit — cents) and &#x2A;*`currency`** (`CurrencyCode`) — what gets charged per unit.
* **Price `recurring`** (`boolean`) — `true` requires `interval` (`day` | `week` | `month` | `year`) and `interval_count`; `false` is a one-time price suitable for invoices and checkouts.
* **Price `pricing_model`** (`PricingModel`) — `per_unit`, `tiered_volume`, `tiered_graduated`, `package`, `metered`, or `flat_rate`. `metered` requires usage reports (see [Meter usage](../guides/meter-usage)).
* **Price `trial_period_days`** (`number`) — applies a default trial when the price is used to start a subscription without an explicit `trial_period_days` override.

## Related [#related]

* [API reference: Products](/docs/reference/api/billing/products)
* [API reference: Product (price)](/docs/reference/api/billing/product)
* [Guide: Create a subscription](../guides/create-subscription)


# Subscription (/docs/billing/concepts/subscription)



A **Subscription** is a recurring charge agreement between a customer and the merchant. It binds a customer (`identity_id`) and a payment instrument to one or more priced items, and the billing engine generates invoices on each cycle and attempts collection automatically.

## Lifecycle [#lifecycle]

1. **`incomplete`** — created without a usable instrument or before initial payment confirmation. Resolves to `active` once payment succeeds, or to `incomplete_expired` if it lapses.
2. **`trialing`** — created with `trial_period_days` or `trial_end`. No invoices are generated until the trial ends. Emits `subscription.trial_will_end` ahead of expiry.
3. **`active`** — invoices are generated at each `current_period_end` and charged against `instrument_id`. Emits `subscription.created` then `subscription.updated` on item, quantity, or status changes.
4. **`past_due` / `unpaid`** — payment failed. Dunning takes over (see [Dunning config](./dunning-config)). Terminal action is governed by `subscription_terminal_action`.
5. **`paused`** — payment collection suspended via `pauseSubscription`. Emits `subscription.paused`; `subscription.resumed` on resume.
6. **`canceled`** — terminated by `cancelSubscription` (immediate) or `cancel_at_period_end: true` (deferred). Emits `subscription.deleted` once `ended_at` is set.

## Relationships [#relationships]

A subscription belongs to a [Customer](../../payments/concepts/customer) (`identity_id`) and references a payment instrument (`instrument_id`). Each [`SubscriptionItem`](/docs/reference/api/billing/subscriptions) points at a [Price](./product-and-price) which belongs to a Product. Generated [Invoices](./invoice) are linked back via `latest_invoice_id`. Discounts attach via [`SubscriptionDiscount`](./coupon-and-promotion-code) and reference a coupon or promotion code.

## Fields that matter [#fields-that-matter]

* **`status`** (`SubscriptionStatus`) — drives billing behavior; one of `incomplete`, `incomplete_expired`, `trialing`, `active`, `past_due`, `unpaid`, `canceled`, `paused`.
* **`items`** (`SubscriptionItem[]`) — the priced lines that produce invoice line items each cycle. Mutate with `addSubscriptionItem` / `updateSubscriptionItem` / `removeSubscriptionItem`.
* **`current_period_start` / `current_period_end`** (ISO datetime) — bounds of the current billing window. Next invoice is generated at `current_period_end`.
* **`cancel_at_period_end`** (`boolean`) — when `true`, the subscription continues until `current_period_end`, then transitions to `canceled`.
* **`pause_collection`** (`{ behavior, resumes_at } | null`) — populated while paused; `behavior` controls how draft invoices during the pause are handled.
* **`pending_update`** (`SubscriptionPendingUpdate | null`) — staged item changes awaiting trial-end or next renewal.

## Related [#related]

* [API reference](/docs/reference/api/billing/subscriptions)
* [Guide: Create a subscription](../guides/create-subscription)
* [Guide: Apply a coupon](../guides/apply-coupon)


# Apply a coupon (/docs/billing/guides/apply-coupon)



## Goal [#goal]

Take a coupon ID (server-side) or a customer-typed promotion code (e.g. `LAUNCH50`), validate that it can be redeemed, and attach the resulting discount to a subscription. Coupons can also be scoped to specific products and to a single subscription item rather than the whole subscription.

## Prerequisites [#prerequisites]

* A sandbox or production API key
* `@easylabs/node` installed
* Either a [Coupon](../concepts/coupon-and-promotion-code) you've already created, or a Promotion code that points at one
* An existing [Subscription](./create-subscription) to apply the discount to

## Implementation [#implementation]

### 1. Create the coupon (one-time setup) [#1-create-the-coupon-one-time-setup]

Coupons are reusable — create them once for each campaign or pricing rule. Pick `percent_off` or `amount_off + currency`, never both.

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

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

const { data: coupon } = await easy.createCoupon({
  duration: "repeating",
  duration_in_months: 3,
  percent_off: 25,
  name: "Launch month — 25% off for 3 months",
  max_redemptions: 500,
});

// Optional: a customer-redeemable code that points at this coupon.
const { data: promo } = await easy.createPromotionCode({
  coupon_id: coupon.id,
  code: "LAUNCH25",
  first_time_only: true,
  minimum_amount: 1000,
  valid_until: "2026-12-31T23:59:59Z",
});
```

### 2. Validate a customer-entered code [#2-validate-a-customer-entered-code]

Always validate before applying — the call returns a `discount_preview` you can render in your UI ("$12.25 off") and a `valid: false` reason ("expired", "minimum\_not\_met") when the code can't be used.

```ts
const { data: validation } = await easy.validatePromotionCode({
  code: "LAUNCH25",
  identity_id: "cus_01HXXXXXXXXXXX",
  amount: 4900, // optional — checks minimum_amount if set
});

if (!validation.valid) {
  throw new Error(validation.reason ?? "Invalid promo code");
}
```

### 3. Apply the discount to the subscription [#3-apply-the-discount-to-the-subscription]

Pass exactly one of `coupon_id` or `promotion_code`. Optionally scope to a single subscription item by passing `subscription_item_id` (otherwise the discount applies to the subscription as a whole).

```ts
// Apply via promotion code (typical for customer-entered codes)
const { data: discount } = await easy.applySubscriptionDiscount(
  "sub_01HXXXXXXXXXXX",
  { promotion_code: "LAUNCH25" },
);

// Apply via coupon directly (typical for server-side / programmatic discounts)
await easy.applySubscriptionDiscount(
  "sub_01HXXXXXXXXXXX",
  { coupon_id: coupon.id, subscription_item_id: "si_01HXXXXXXXXXXX" },
);
```

The discount is honored on the next invoice generated by the subscription engine. For `repeating` coupons, the discount lasts `duration_in_months` invoices and then drops off automatically.

### 4. Inspect or remove later [#4-inspect-or-remove-later]

```ts
const { data: discounts } = await easy.listSubscriptionDiscounts("sub_01HXXXXXXXXXXX");
await easy.removeSubscriptionDiscount("sub_01HXXXXXXXXXXX", discounts[0].id);
```

## Tradeoffs [#tradeoffs]

* **Coupon vs. promotion code** — apply a `coupon_id` directly when you control the discount logic server-side (anniversary perks, retention saves, internal credits). Use a `code` when the customer types it in.
* **Subscription-level vs. item-level scope** — leaving `subscription_item_id` unset discounts the whole subscription. Set it to scope to a single line — useful when an add-on is the discounted product but the base plan is not.
* **`first_time_only` is per-coupon, not per-product** — once a customer redeems any code that maps to a given coupon, no other code mapping to that same coupon will validate for them with `first_time_only: true`.

## Related [#related]

* [Concept: Coupon and promotion code](../concepts/coupon-and-promotion-code)
* [API reference: Coupons](/docs/reference/api/billing/coupons)
* [API reference: Promotion codes](/docs/reference/api/billing/promotion-codes)


# Configure dunning (/docs/billing/guides/configure-dunning)



## Goal [#goal]

Define how the platform retries failed recurring charges, what the customer sees when a payment fails, and what state the subscription or invoice ends up in if recovery exhausts. There is exactly one dunning config per merchant — set it once, then iterate. Pair this with **revenue-recovery automations** for event-driven follow-up beyond retries.

## Prerequisites [#prerequisites]

* A sandbox or production API key
* `@easylabs/node` installed
* Active [subscriptions](./create-subscription) and/or `charge_automatically` [invoices](./send-invoice) — dunning has nothing to do until something fails

## Implementation [#implementation]

### 1. Set the retry policy [#1-set-the-retry-policy]

Pick `smart` for a platform-tuned schedule sized by `smart_retry_window` and `smart_retry_attempts`, or `custom` if you need precise day offsets.

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

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

await easy.createOrReplaceDunningConfig({
  retry_mode: "smart",
  smart_retry_attempts: 8,
  smart_retry_window: "2_weeks",

  // Bank-debit failures need their own track (longer settlement windows).
  bank_debit_retries_enabled: true,
  bank_debit_retry_schedule: [3, 7, 14],

  // Customer-facing emails on failure / expiring card.
  payment_failed_email_enabled: true,
  expiring_card_email_enabled: true,
  card_expiry_warn_days: 14,

  // Where the recovery email sends the customer.
  payment_failed_recovery_page_mode: "custom_link",
  payment_failed_custom_link_url: "https://your-app.com/billing/recover",

  // Terminal actions when retries are exhausted.
  subscription_terminal_action: "past_due",
  invoice_terminal_action: "uncollectible",
});
```

### 2. Read or patch later [#2-read-or-patch-later]

`createOrReplaceDunningConfig` is destructive — it replaces every field. Use `updateDunningConfig` to change a subset:

```ts
await easy.updateDunningConfig({ smart_retry_attempts: 4 });
const { data: current } = await easy.getDunningConfig();
```

### 3. Add revenue-recovery automations (optional) [#3-add-revenue-recovery-automations-optional]

Automations are conditional rules layered on top of the retry engine. They fire on triggers like `invoice_overdue` and run actions like `email_team_member` or `mark_invoice_uncollectible`.

```ts
await easy.createRevenueRecoveryAutomation({
  name: "Notify CSM on enterprise overdue",
  trigger_type: "invoice_overdue",
  conditions: [
    { type: "invoice_amount", operator: "more_than", amount_cents: 100_000 },
  ],
  actions: [
    { type: "email_team_member", delay_days: 1, recipient_email: "csm@your-app.com" },
  ],
  active: true,
});
```

### 4. Listen for terminal events [#4-listen-for-terminal-events]

Subscribe to `invoice.payment_failed`, `invoice.marked_uncollectible`, `subscription.updated` (status transitions to `past_due` / `unpaid`), and `revenue_recovery.action_completed` to log dunning outcomes and notify your team.

## Tradeoffs [#tradeoffs]

* **`smart` vs. `custom` retries** — `smart` adapts retry timing to issuer behavior and typically recovers more revenue than a fixed schedule; reach for `custom` only when you have hard requirements (e.g. quiet hours).
* **Terminal action `cancel` vs. `past_due`** — `cancel` ends the subscription and stops downstream charges; `past_due` keeps it visible so a customer can self-recover via the portal. Most SaaS picks `past_due` + customer-portal recovery.
* **Recovery page mode `hosted` vs. `custom_link`** — hosted is zero-effort and white-labeled; `custom_link` lets you deep-link to a [customer-portal](./launch-customer-portal) magic link with the failure context already loaded.

## Related [#related]

* [Concept: Dunning config](../concepts/dunning-config)
* [API reference](/docs/reference/api/billing/auto-pay)
* [Guide: Launch the customer portal](./launch-customer-portal)


# Create a subscription (/docs/billing/guides/create-subscription)



## Goal [#goal]

Create an `active` (or `trialing`) subscription that charges a customer's saved payment instrument on a fixed cadence. Use this whenever you sell a recurring plan — SaaS seats, monthly memberships, repeat-fulfillment products. For one-off invoices, see [Send an invoice](./send-invoice). For self-serve plan changes after the subscription exists, see [Launch the customer portal](./launch-customer-portal).

## Prerequisites [#prerequisites]

* A sandbox or production API key
* `@easylabs/node` installed
* A [Customer](../../payments/concepts/customer) and a saved [payment instrument](../../payments/concepts/payment-instrument) belonging to that customer
* A recurring [Price](../concepts/product-and-price) (`recurring: true`)

## Implementation [#implementation]

### 1. Resolve or create the price [#1-resolve-or-create-the-price]

Subscriptions charge against a price ID, not a product ID. If you don't already have one, create the price (or look it up) before continuing:

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

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

const { data: price } = await easy.createPrice({
  product_id: "prod_01HXXXXXXXXXXX",
  active: true,
  recurring: true,
  currency: "USD",
  unit_amount: 4900,            // $49.00
  interval: "month",
  interval_count: 1,
  tax_behavior: "exclusive",
});
```

### 2. Create the subscription [#2-create-the-subscription]

Pass `identity_id`, `instrument_id`, and one or more `items`. The first invoice is generated synchronously; the call resolves once the subscription is `active` (or `trialing` if you supply a trial).

```ts
const { data: subscription } = await easy.createSubscription({
  identity_id: "cus_01HXXXXXXXXXXX",
  instrument_id: "pi_01HXXXXXXXXXXX",
  items: [{ price_id: price.id, quantity: 3 }],
  metadata: { workspace_id: "ws_42" },
});
```

To start with a free trial, omit `instrument_id` and supply `trial_period_days` (or an explicit `trial_end` ISO datetime):

```ts
await easy.createSubscription({
  identity_id: "cus_01HXXXXXXXXXXX",
  items: [{ price_id: price.id, quantity: 1 }],
  trial_period_days: 14,
});
```

### 3. React to lifecycle events [#3-react-to-lifecycle-events]

Wire your webhook endpoint to act on `subscription.created`, `subscription.updated`, `subscription.trial_will_end`, `invoice.paid`, and `invoice.payment_failed`. See the [webhooks reference](/docs/reference/webhooks) for signature verification with `EasyWebhooks.constructEvent`.

### 4. Mutate later [#4-mutate-later]

Add a seat: `await easy.addSubscriptionItem(subscription.id, { price_id, quantity: 1 })`. Change quantity: `updateSubscriptionItem(subscription.id, itemId, { quantity: 5 })`. Cancel at period end: `updateSubscription(subscription.id, { cancel_at_period_end: true })`. Cancel immediately: `cancelSubscription(subscription.id)`. Preview the proration impact of a change first with `getSubscriptionProrationPreview`.

## Tradeoffs [#tradeoffs]

* **Trial without an instrument** is fine, but the subscription will move to `incomplete` at trial end if no `instrument_id` has been attached. Schedule a reminder before `trial_end` and patch the subscription with `updateSubscription({ instrument_id })`.
* **Proration behavior** defaults to `create_prorations` on item changes. Pass `proration_behavior: "none"` for grandfathered customers, or `"always_invoice"` to bill the proration immediately rather than rolling into the next cycle.
* **Skip the subscription engine entirely** when billing is per-event or quote-style — use [`createInvoice`](./send-invoice) instead and avoid the cycle bookkeeping.

## Related [#related]

* [Concept: Subscription](../concepts/subscription)
* [Concept: Product and Price](../concepts/product-and-price)
* [API reference](/docs/reference/api/billing/subscriptions)


# Billing guides (/docs/billing/guides)



Step-by-step recipes for the most common Billing integrations. Each guide states the goal, lists prerequisites, and ships working code.



<Cards>
  <Card title="Create Subscription" href="./guides/create-subscription" description="Create Subscription with Easy Billing." />

  <Card title="Send Invoice" href="./guides/send-invoice" description="Send Invoice with Easy Billing." />

  <Card title="Configure Dunning" href="./guides/configure-dunning" description="Configure Dunning with Easy Billing." />

  <Card title="Launch Customer Portal" href="./guides/launch-customer-portal" description="Launch Customer Portal with Easy Billing." />

  <Card title="Apply Coupon" href="./guides/apply-coupon" description="Apply Coupon with Easy Billing." />

  <Card title="Meter Usage" href="./guides/meter-usage" description="Meter Usage with Easy Billing." />
</Cards>


# Launch the customer portal (/docs/billing/guides/launch-customer-portal)



## Goal [#goal]

Let a customer manage their own subscriptions, payment methods, and invoices in a hosted, white-label page. You configure what the portal exposes once, then mint a magic link per session — no portal-specific UI to build, and your API key never leaves the server. The portal is also the recommended target for failed-payment recovery emails (see [Configure dunning](./configure-dunning)).

## Prerequisites [#prerequisites]

* A sandbox or production API key
* A [Customer](../../payments/concepts/customer) with a known `email`
* One configuration pass through `PATCH /customer-portal-config` to enable the sections you want (payment methods, subscriptions, cancellations) — see the [config reference](/docs/reference/api/billing/customer-portal-config)

## Implementation [#implementation]

### 1. Configure the portal once [#1-configure-the-portal-once]

Toggle features and define cancellation semantics. Done once per environment, not per customer.

```ts
// PATCH /v1/api/customer-portal-config
await fetch(`${EASY_API_URL}/v1/api/customer-portal-config/`, {
  method: "PATCH",
  headers: {
    "x-easy-api-key": process.env.EASY_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    payment_methods_enabled: true,
    accepted_payment_methods: ["card", "bank_account"],
    subscriptions_enabled: true,
    allow_plan_switch: true,
    allow_quantity_updates: true,
    cancellations_enabled: true,
    cancellation_mode: "end_of_period",
    cancellation_proration_enabled: false,
    cancellation_reasons_enabled: true,
    cancellation_reasons: ["Too expensive", "Missing features", "Switching tools"],
    return_url: "https://your-app.com/account",
    invoice_history_enabled: true,
  }),
});
```

### 2. Request a magic link for a customer [#2-request-a-magic-link-for-a-customer]

When a signed-in user clicks "Manage billing" in your app, call the request-link endpoint server-side. The platform emails the link to the customer.

```ts
type RequestLinkBody = {
  company_id: string;
  email: string;
  destination?: "home" | "payment_methods" | "billing_information";
  destination_context?: Record<string, unknown>;
};

async function requestPortalLink(body: RequestLinkBody) {
  const res = await fetch(`${EASY_API_URL}/v1/api/customer-portal/access/request-link`, {
    method: "POST",
    headers: {
      "x-easy-api-key": process.env.EASY_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`request-link failed: ${res.status}`);
  return res.json();
}

await requestPortalLink({
  company_id: process.env.EASY_COMPANY_ID!,
  email: "ada@example.com",
  destination: "payment_methods",
});
```

The `destination` controls the landing section. Use `payment_methods` from a "Update your card" prompt and `home` from a generic "Manage billing" link.

### 3. Customer follows the link [#3-customer-follows-the-link]

The customer clicks the email, the portal loads, and a token in the URL is exchanged for a session via `POST /customer-portal/access/consume`. Everything from that point — payment-method updates, plan switches, cancels — runs against that scoped session, not your API key.

### 4. React to portal-driven changes [#4-react-to-portal-driven-changes]

The portal mutates the same records as the merchant API, so your existing webhook handlers will fire. Watch for `subscription.updated` (plan switches, quantity changes), `subscription.deleted` (cancellations), `invoice.paid` (recovered failures), and act in your app accordingly.

## Tradeoffs [#tradeoffs]

* **Magic link delivery is asynchronous** — if your UI promises "we just emailed you", make sure your transactional email provider is set up. For a same-tab handoff (no email round-trip), use the access-handoff create/exchange pair instead.
* **`cancellation_mode: "immediately"` vs. `"end_of_period"`** — immediate cancels free the seat now but lose the remaining paid period; end-of-period preserves goodwill and is the conventional SaaS default.
* **Self-serve plan switching** is convenient but skips your in-app upsell logic. Restrict to a curated catalog with `subscription_product_ids` if you only want certain plans available in the portal.

## Related [#related]

* [Concept: Customer portal](../concepts/customer-portal)
* [API reference: Customer portal](/docs/reference/api/billing/customer-portal)
* [Guide: Configure dunning](./configure-dunning)


# Meter usage (/docs/billing/guides/meter-usage)



## Goal [#goal]

Bill a customer for variable consumption — API calls, GB ingested, minutes streamed — by reporting usage events against a subscription item with a `metered` price. The platform aggregates the reports, generates an invoice line at period close, and exposes a reconciliation view so you can match what you reported against what was billed.

## Prerequisites [#prerequisites]

* A sandbox or production API key
* `@easylabs/node` installed
* A [Price](../concepts/product-and-price) created with `pricing_model: "metered"`
* A [Subscription](./create-subscription) with at least one item using that price

## Implementation [#implementation]

### 1. Report usage as it happens [#1-report-usage-as-it-happens]

Each event references the `subscription_item_id` and a quantity. Pass `action: "increment"` (the default) to add to the bucket, or `action: "set"` to overwrite the period total. Use `idempotency_key` to make retries safe.

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

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

await easy.reportSubscriptionUsage("sub_01HXXXXXXXXXXX", {
  subscription_item_id: "si_01HXXXXXXXXXXX",
  quantity: 1,
  action: "increment",
  timestamp: new Date().toISOString(),
  idempotency_key: `evt_${eventId}`,
});
```

For high-volume metering, batch on your side and submit in larger chunks rather than one event per API call. `quantity` is an integer; pre-aggregate fractional units to whole ones at the resolution you're billing.

### 2. Read the running total [#2-read-the-running-total]

`getSubscriptionUsageSummary` returns the current period's accumulated usage by item. Use `as_of` to view a historical snapshot or `from`/`to` to bound the window.

```ts
const { data: summary } = await easy.getSubscriptionUsageSummary(
  "sub_01HXXXXXXXXXXX",
  { subscription_item_id: "si_01HXXXXXXXXXXX" },
);
```

Surface this in your customer-facing dashboard so usage is visible before the invoice closes.

### 3. Reconcile at period end [#3-reconcile-at-period-end]

When the subscription rolls over, the engine generates an invoice line for the metered totals. `getSubscriptionUsageReconciliation` returns the reported-vs-billed comparison for a closed period — call it from a scheduled job and alert if the deltas exceed your tolerance.

```ts
const { data: recon } = await easy.getSubscriptionUsageReconciliation(
  "sub_01HXXXXXXXXXXX",
  {
    subscription_item_id: "si_01HXXXXXXXXXXX",
    period_start: "2026-04-01T00:00:00Z",
    period_end: "2026-05-01T00:00:00Z",
  },
);
```

Listen for `invoice.created` and `invoice.finalized` to know when to run reconciliation.

## Tradeoffs [#tradeoffs]

* **`increment` vs. `set`** — `increment` is the default and fits event streams. `set` is the right call only when you have an authoritative period total (e.g. nightly batch from a data warehouse) and you can guarantee one report per period.
* **Latency** — usage reports are not invoiced in real time. Reports flushed within the period are billed; reports backfilled after the period closes go on the next invoice (or fail to record, depending on configuration). Bound your reporting lag to less than the billing interval.
* **Idempotency keys** are per subscription item, not global. A retry with the same `idempotency_key` is safely deduped; reusing the key for a new event will silently drop it.

## Related [#related]

* [Concept: Subscription](../concepts/subscription)
* [Concept: Product and Price](../concepts/product-and-price)
* [API reference](/docs/reference/api/billing/subscriptions)


# Send an invoice (/docs/billing/guides/send-invoice)



## Goal [#goal]

Create an invoice from line items, send it to a customer's email, and (optionally) attach the PDF. Use this for one-off billing — quotes, professional services, milestone payments — or when you want the customer to pay through a hosted page rather than charging a saved instrument. For recurring billing of a fixed plan, use [subscriptions](./create-subscription) instead.

## Prerequisites [#prerequisites]

* A sandbox or production API key
* `@easylabs/node` installed
* A `to_email` for the recipient (and optionally a `buyer_id` linking to a [Customer](../../payments/concepts/customer))

## Implementation [#implementation]

### 1. Create the invoice [#1-create-the-invoice]

Items carry `description`, `quantity`, and `unit_price` in the smallest currency unit. The invoice starts in `DRAFT`; pass `collection_method` to control how it gets paid once finalized.

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

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

const { data: invoice } = await easy.createInvoice({
  to_email: "ada@example.com",
  to_company_name: "Lovelace Labs",
  buyer_id: "cus_01HXXXXXXXXXXX",
  currency: "USD",
  collection_method: "send_invoice", // customer pays via hosted page
  due_date: "2026-06-01",
  items: [
    { description: "Q2 retainer", quantity: 1, unit_price: 500_000 }, // $5,000.00
    { description: "Add-on workshop", quantity: 2, unit_price: 75_000, manual_tax_rate: 8.875 },
  ],
  notes: "Thanks for working with us — net 30.",
  auto_reminders: true,
  include_payment_page_link: true,
});
```

### 2. Send the email [#2-send-the-email]

`sendInvoice` finalizes the invoice (DRAFT → OPEN), delivers the email, and returns the updated record. Pass `attach_pdf: true` to embed the PDF.

```ts
await easy.sendInvoice(invoice.id, {
  attach_pdf: true,
  cc_recipients: ["billing@lovelacelabs.example"],
});
```

To schedule the send for a future time, pass `scheduled_send_at` instead of calling immediately, or set it on `createInvoice` and skip the manual `sendInvoice` step.

### 3. Charge automatically (optional) [#3-charge-automatically-optional]

If you'd rather collect against the customer's default payment instrument the moment the invoice opens, pass `collection_method: "charge_automatically"` on create and call `payInvoice` (or let the platform pull on `due_date`):

```ts
await easy.payInvoice(invoice.id, {
  // omit instrument_id to use the customer's default
  idempotency_key: `invoice-${invoice.id}-attempt-1`,
});
```

### 4. React to status [#4-react-to-status]

Listen for `invoice.finalized`, `invoice.paid`, `invoice.payment_failed`, `invoice.voided`, and `invoice.marked_uncollectible`. Send manual nudges with `remindInvoice(invoice.id)` between auto-reminders, or `voidInvoice(invoice.id)` to cancel an open one.

## Tradeoffs [#tradeoffs]

* **`send_invoice` vs. `charge_automatically`** — pick `send_invoice` when the customer expects to pay manually (typical for B2B). Pick `charge_automatically` only when you have an instrument on file and the customer has agreed to be billed.
* **Recurring invoices** (`is_recurring: true` + `recurrence_interval`) are simpler than subscriptions but lack proration, item-level mutations, and the dunning lifecycle. Choose subscriptions when the relationship is open-ended.
* **Tax** — `manual_tax_rate` on each item is the lowest-friction option. For multi-jurisdiction tax, set `tax_rate_id` on prices and let the platform compute totals.

## Related [#related]

* [Concept: Invoice](../concepts/invoice)
* [API reference](/docs/reference/api/billing/invoices)
* [Guide: Configure dunning](./configure-dunning)


# Migrate from Stripe to Easy Billing (/docs/billing/migration/from-stripe)



This page is a side-by-side reference. The two APIs share the Customer / Product / Price / Subscription / Invoice / Coupon / Promotion code model, so most code is a method-name swap and a small payload translation. Differences worth knowing are called out under [Object-model differences](#object-model-differences).

## Subscriptions [#subscriptions]

| Stripe                                                                     | Easy Labs (`@easylabs/node`)                                                     | Notes                                                                                                              |
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `stripe.subscriptions.create({ customer, items, default_payment_method })` | `easy.createSubscription({ identity_id, items, instrument_id })`                 | `customer` → `identity_id`; `default_payment_method` → `instrument_id`. Items use `price_id` + `quantity` in both. |
| `stripe.subscriptions.retrieve(id)`                                        | `easy.getSubscription(id)`                                                       | Returns `{ data: SubscriptionData }`.                                                                              |
| `stripe.subscriptions.update(id, body)`                                    | `easy.updateSubscription(id, body)`                                              | `cancel_at_period_end`, `proration_behavior`, `items`, `metadata` are 1:1.                                         |
| `stripe.subscriptions.cancel(id, { invoice_now })`                         | `easy.cancelSubscription(id, { at_period_end })`                                 | Easy treats `at_period_end: false` (default) as "cancel now".                                                      |
| `stripe.subscriptions.update(id, { pause_collection })`                    | `easy.pauseSubscription(id, { behavior })` / `easy.resumeSubscription(id)`       | Dedicated endpoints. `behavior` is `void` / `keep_as_draft` / `mark_uncollectible`.                                |
| `stripe.subscriptionItems.create / update / del`                           | `easy.addSubscriptionItem` / `updateSubscriptionItem` / `removeSubscriptionItem` | Same shape.                                                                                                        |
| `stripe.invoices.retrieveUpcoming({ subscription, subscription_items })`   | `easy.getSubscriptionProrationPreview(id, { items, remove_items })`              | Returns the proration delta only (not a full upcoming invoice).                                                    |
| `stripe.subscriptionItems.createUsageRecord`                               | `easy.reportSubscriptionUsage(subscriptionId, body)`                             | Same `quantity` + `action` (`increment` / `set`) + `timestamp` semantics.                                          |

## Invoices [#invoices]

| Stripe                                                    | Easy Labs                                                                      | Notes                                                                                                          |
| --------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `stripe.invoices.create(body)`                            | `easy.createInvoice(body)`                                                     | `customer` → `buyer_id`; line items pass inline as `items[]` rather than separate `invoiceItems.create` calls. |
| `stripe.invoices.finalizeInvoice(id)` + `sendInvoice(id)` | `easy.sendInvoice(id, { attach_pdf, cc_recipients })`                          | One call: finalizes *and* sends.                                                                               |
| `stripe.invoices.pay(id, { payment_method })`             | `easy.payInvoice(id, { instrument_id })`                                       | Use `idempotency_key` on retries.                                                                              |
| `stripe.invoices.sendInvoice(id)` (reminder)              | `easy.remindInvoice(id)`                                                       | Sends a follow-up email on an already-sent invoice.                                                            |
| `stripe.invoices.voidInvoice(id)`                         | `easy.voidInvoice(id)`                                                         | Same.                                                                                                          |
| `stripe.invoices.list({ status, collection_method })`     | `easy.listInvoices({ status, collection_method, due_date_from, due_date_to })` | `status` enum is uppercase (`OPEN`, `PAID`, ...) on Easy.                                                      |

## Coupons and promotion codes [#coupons-and-promotion-codes]

| Stripe                                                                 | Easy Labs                                                                   | Notes                                                                                |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `stripe.coupons.create({ percent_off, duration, duration_in_months })` | `easy.createCoupon({ percent_off, duration, duration_in_months })`          | Same. Or pass `amount_off` + `currency` for fixed discounts.                         |
| `stripe.promotionCodes.create({ coupon, code })`                       | `easy.createPromotionCode({ coupon_id, code })`                             | `coupon` → `coupon_id`. Same `first_time_only`, `max_redemptions`, `minimum_amount`. |
| `stripe.promotionCodes.list({ code })` then check active               | `easy.validatePromotionCode({ code, identity_id, amount })`                 | Single call returns `valid`, `coupon`, `discount_preview`, and `reason`.             |
| `stripe.subscriptions.update(id, { discounts: [{ coupon }] })`         | `easy.applySubscriptionDiscount(id, { coupon_id })` or `{ promotion_code }` | Dedicated endpoint. `subscription_item_id` scopes to one item.                       |

## Customer portal [#customer-portal]

| Stripe                                                           | Easy Labs                                                                                 | Notes                                                                                                                                                                                |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `stripe.billingPortal.configurations.update(...)`                | `PATCH /v1/api/customer-portal-config/`                                                   | Toggles for payment methods, subscriptions, cancellations.                                                                                                                           |
| `stripe.billingPortal.sessions.create({ customer, return_url })` | `POST /v1/api/customer-portal/access/request-link` (`{ company_id, email, destination }`) | Easy emails the customer a magic link instead of returning a session URL directly. For an inline same-tab handoff, use the `access/handoff/create` + `access/handoff/exchange` pair. |

## Webhooks [#webhooks]

Both platforms sign webhooks with HMAC-SHA256 over the raw body. Headers and helpers:

| Stripe                                                                          | Easy Labs                                                                                                                |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `Stripe-Signature` header + `stripe.webhooks.constructEvent(body, sig, secret)` | `x-easy-webhook-signature: sha256=<hex>` header + `EasyWebhooks.constructEvent(body, sig, secret)` from `@easylabs/node` |
| `customer.subscription.created` / `.updated` / `.deleted`                       | `subscription.created` / `.updated` / `.deleted`                                                                         |
| `customer.subscription.trial_will_end`                                          | `subscription.trial_will_end`                                                                                            |
| `customer.subscription.paused` / `.resumed`                                     | `subscription.paused` / `.resumed`                                                                                       |
| `invoice.created` / `.finalized` / `.paid` / `.payment_failed` / `.voided`      | Same names.                                                                                                              |
| `invoice.marked_uncollectible`                                                  | `invoice.marked_uncollectible`                                                                                           |
| `coupon.created` / `.updated` / `.deleted`                                      | `coupon.created` / `.updated` / `.deleted`                                                                               |
| `promotion_code.created` / `.updated`                                           | `promotion_code.created` / `.updated` / `.deleted`                                                                       |
| `checkout.session.completed`                                                    | `checkout.session.completed` (plus `checkout.session.crypto_confirmed` if you accept crypto)                             |

See the [webhooks reference](/docs/reference/webhooks) for the full event list and signature format.

## Object-model differences [#object-model-differences]

* **Customer is `Identity`** under the hood — most fields you read are nested under `data.entity.*`. Anywhere Stripe takes `customer`, Easy takes `identity_id`.
* **Payment method is "instrument"** — `payment_method` → `instrument_id`. The shape returned from `createPaymentInstrument` carries instrument-level enable/disable flags rather than card-level metadata.
* **No detached invoice items.** Stripe's two-step `invoiceItems.create` + `invoices.create` is collapsed: pass `items` inline on `createInvoice`.
* **Single dunning policy per merchant.** Stripe's per-customer retry rules are replaced by `dunning-config` + revenue-recovery automations applied globally.
* **Money is in the smallest currency unit** (cents) on both platforms. `currency` is uppercase ISO 4217 on Easy (e.g. `"USD"`).
* **Status enums** are uppercase on Easy invoices (`OPEN`, `PAID`, `VOID`) but lowercase on subscriptions (`active`, `trialing`, `past_due`) — matching the underlying engines.
* **No `expand`.** Endpoints return the linked records they need (e.g. `getProductWithPrices`); there is no generic expansion mechanism.

## Related [#related]

* [Billing concepts](../concepts/subscription)
* [API reference](/docs/reference/api/billing)
* [Webhooks reference](/docs/reference/webhooks)


# Migrate to Easy Billing (/docs/billing/migration)



Mechanical mappings from competing APIs to Easy Billing. Each migration page covers method-by-method translation, webhook event pairs, and meaningful conceptual differences.



<Cards>
  <Card title="From Stripe" href="./migration/from-stripe" description="Stripe → Easy Billing mapping." />
</Cards>


# Customer (/docs/payments/concepts/customer)



A **Customer** represents a buyer (or payer) you transact with. It is the durable identity that owns Payment Instruments, Orders, Subscriptions, and Disputes — every charge in Payments either belongs to a Customer or is created on the fly during checkout (which still creates a Customer behind the scenes). Use a Customer when you need to remember the buyer across sessions: saved cards, recurring billing, refunds against the right account, dispute correlation.

## Lifecycle [#lifecycle]

1. **Created** — `client.createCustomer({ first_name, last_name, email, phone, personal_address })` returns a `CustomerData` record with an `id`. No webhook fires for creation; the API response is the source of truth.
2. **Used** — the `id` is passed as `identityId` when creating a Payment Instrument, or as `identity_id` on a Subscription / Embedded Checkout session.
3. **Updated** — `client.updateCustomer(customerId, partial)` patches mutable fields. Tags accept arbitrary JSON for your own bookkeeping.
4. **Identity events** — `identity.created` and `identity.updated` webhook events fire when the underlying processor identity changes (typically the same lifecycle, but they are the audit trail you should subscribe to if you mirror customer state into your own database).

Customers are not deleted via the API. To stop charging a Customer, disable their Payment Instruments or cancel their Subscriptions instead.

## Relationships [#relationships]

Every **Order**, **Transfer**, and **Subscription** ultimately resolves to a Customer (the payer). A Customer can own many **Payment Instruments** (cards, bank accounts) and many **Wallets** (Solana addresses for crypto checkout). **Disputes** are reachable through the Transfer that was charged on one of the Customer's Payment Instruments.

## Fields that matter [#fields-that-matter]

* `id` (`string`) — the canonical Customer ID. Pass this as `identityId` when creating a Payment Instrument and as `identity_id` for subscriptions.
* `entity.first_name`, `entity.last_name`, `entity.email`, `entity.phone` (`string`) — buyer contact info. Required at creation.
* `entity.personal_address` (`Address | null`) — used for AVS on card transactions; pass it when you have it.
* `tags` (`Record<string, string>`) — your own metadata (internal user IDs, plan tier, etc.). Searchable; keep keys stable.
* `identity_roles` (`string[]`) — processor-side flags (e.g. whether this identity has merchant capabilities). Read-only.

## Related [#related]

* [API reference](/docs/reference/api/payments/customer)
* [Guide: Accept a card payment](../guides/accept-card-payment)
* [Guide: Embed hosted checkout](../guides/embed-hosted-checkout)


# Dispute (/docs/payments/concepts/dispute)



A **Dispute** is an issuer- or buyer-initiated chargeback against a Transfer: the buyer's bank pulls the funds back into their account and asks Easy Labs (and you, the merchant) to either accept the loss or contest it with evidence. Disputes are read-mostly from the SDK's perspective — they are created by the network, not by you, and the work you do is responding to them with evidence and tracking the outcome. The Dispute object is the durable record of that exchange.

## Lifecycle [#lifecycle]

1. **Created** — a `dispute.created` webhook fires when the network notifies Easy Labs of a chargeback. The disputed amount has already been pulled from the merchant settlement. A separate Transfer with `type: "DISPUTE"` holds the funds in flight.
2. **Under review** — you have a fixed evidence window (network-dependent; typically 7–21 days) to upload supporting documentation through the dashboard or by attaching it via your account team.
3. **Decision** — the issuer decides. A `dispute.updated` webhook fires when the status changes. Outcomes are typically `WON` (funds returned to merchant), `LOST` (funds stay with buyer), or `ACCEPTED` (you chose not to contest).
4. **Tagged** — at any point you can call `client.updateDispute(disputeId, { internalCaseId: "…" })` to attach your own metadata. Tags are the only mutable surface on a Dispute.

## Relationships [#relationships]

Every Dispute references the **Transfer** it is contesting. From the Transfer you can resolve back to the **Order** (if the charge originated from a checkout flow), the **Customer** that owns the funding source, and the **Payment Instrument** that was charged.

## Fields that matter [#fields-that-matter]

The Dispute schema is processor-specific and the API exposes it as a permissive object; the fields you can rely on are:

* `id` (`string`) — the canonical Dispute ID. Use with `getDispute`, `updateDispute`.
* `amount` (`number`) — disputed amount in the smallest currency unit.
* `currency` (`string`) — ISO-4217.
* `state` / `status` (`string`) — current dispute status as reported by the network (e.g. `PENDING`, `WON`, `LOST`).
* `transfer` (`string`) — the Transfer ID this Dispute is contesting.
* `reason_code` (`string`) — network-supplied reason (`fraud`, `product_not_received`, `duplicate`, etc.). Drives what evidence you should provide.
* `respond_by` (`string`) — ISO deadline for submitting evidence.
* `tags` (`Record<string, unknown>`) — your own metadata. Mutable.

For end-to-end response workflow, the Easy Labs dashboard is the primary surface — programmatic evidence upload is on the roadmap and not yet exposed via the public SDK.

## Related [#related]

* [API reference](/docs/reference/api/payments/dispute)
* [Guide: Handle a dispute](../guides/handle-dispute)
* [Guide: Issue a refund](../guides/issue-refund)


# Payments concepts (/docs/payments/concepts)



The Payments surface is built around 6 core entities. Each page covers what the entity is, how its lifecycle progresses, and how it relates to the rest of the model.



<Cards>
  <Card title="Customer" href="./concepts/customer" description="The Customer entity in Payments." />

  <Card title="Payment Instrument" href="./concepts/payment-instrument" description="The Payment Instrument entity in Payments." />

  <Card title="Order" href="./concepts/order" description="The Order entity in Payments." />

  <Card title="Transfer" href="./concepts/transfer" description="The Transfer entity in Payments." />

  <Card title="Dispute" href="./concepts/dispute" description="The Dispute entity in Payments." />

  <Card title="Session" href="./concepts/session" description="The Session entity in Payments." />
</Cards>


# Order (/docs/payments/concepts/order)



An **Order** is the receipt-level record of a checkout: it ties a Customer, a Payment Instrument, the line items they purchased, the totals, and the resulting Transfer (the actual money movement) into a single object you can hand to your fulfillment, accounting, or analytics systems. Anything that goes through `client.checkout(...)`, an Embedded Checkout session, or a Payment Link produces an Order. Direct `createTransfer` calls do not — those are bare money movements without line-item context.

## Lifecycle [#lifecycle]

1. **Created** — emitted when a checkout flow runs successfully. The Order is created together with its child Transfer; both share the same `merchant_id`.
2. **Settled** — once the underlying Transfer's `state` becomes `SUCCEEDED`, the Order is the durable record you reconcile against. The `transfer` field on the Order embeds the Transfer object.
3. **Refunded** — when you call `client.createRefund(transferId, { refund_amount })` against the Order's Transfer, the reversal links back to the original Transfer (and therefore the Order). Refunds do not change the Order itself.
4. **Disputed** — if the buyer charges back, a `dispute.created` webhook fires. The Dispute references the Transfer; you can resolve back to the Order via `transfer.id`.

Orders are immutable except for `tags`. Use `client.updateOrderTags(orderId, tags)` to add internal references (fulfillment ID, shipment number, etc.).

## Relationships [#relationships]

Each Order has one **Customer** (`identity`), one **Payment Instrument** (`payment_instrument`), and at most one **Transfer** (`transfer`, may be `null` for orders that fail before authorization). Orders contain `purchase_items` which reference your **Products** and **Prices** by ID. Orders may carry a `payment_link_id` if they originated from a Payment Link.

## Fields that matter [#fields-that-matter]

* `id`, `order_number` (`string`) — the canonical ID and a human-friendly receipt number safe to show buyers.
* `subtotal_cents`, `tax_amount_cents`, `total_cents` (`number`) — amounts in the smallest currency unit. `total_cents` is what the buyer was charged.
* `currency` (`string`) — ISO-4217 code.
* `transfer` (`TransferData | null`) — the embedded Transfer. `transfer.state` tells you whether the money actually moved.
* `purchase_items` (`PurchaseItemData[]`) — line items with quantity, price, and product snapshot (name + image at time of sale).
* `buyer_details`, `shipping_address`, `billing_address` — what the buyer entered at checkout. Use these for fulfillment.
* `tags` (`Record<string, unknown>`) — your own metadata. Mutable.

## Related [#related]

* [API reference](/docs/reference/api/payments/order)
* [Guide: Embed hosted checkout](../guides/embed-hosted-checkout)
* [Guide: Issue a refund](../guides/issue-refund)


# Payment Instrument (/docs/payments/concepts/payment-instrument)



A **Payment Instrument** is a saved, tokenized funding source attached to a Customer — a card or a bank account. It is what you reference as the `source` on a Transfer or as the funding side of a Subscription. The raw card or bank-account number never touches your servers: tokenization happens in the iframe / browser SDK, and the API stores only the network token, the last four digits, BIN, brand, expiration, and AVS metadata.

## Lifecycle [#lifecycle]

1. **Tokenized** — the buyer enters card or bank details inside the embedded checkout iframe (or the React tokenization helpers in `@easylabs/react`). Tokenization produces an opaque token ID.
2. **Created** — `client.createPaymentInstrument({ identityId, tokenId, type, … })` exchanges the token for a persistent Payment Instrument tied to the Customer. The response includes derived fields like `brand`, `last_four`, and `expiration_month` / `expiration_year`.
3. **Used** — pass the Payment Instrument `id` as the `source` on `client.createTransfer({ amount, currency, source })`, on `client.createCheckout(...)`, or as `instrument_id` on a Subscription.
4. **Updated** — `client.updatePaymentInstrument(id, { enabled, address, name, tags, … })` toggles enable state, refreshes the billing address, or patches AVS-related fields.
5. **Disabled** — set `enabled: false` to stop accepting new charges against the instrument; existing recurring subscriptions will start failing on next attempt.

## Relationships [#relationships]

A Payment Instrument always belongs to one Customer (`identity_id`). One Customer can own many instruments — typically one default card plus older saved cards or bank accounts. Each Transfer references exactly one Payment Instrument as its `source`. Subscriptions reference one as `instrument_id` for recurring collection.

## Fields that matter [#fields-that-matter]

* `id` (`string`) — pass as `source` on Transfers, as `instrument_id` on Subscriptions.
* `type` (`"PAYMENT_CARD" | "BANK_ACCOUNT"`) — discriminates card vs. ACH; affects which fields are populated and which Transfer rails apply.
* `enabled` (`boolean`) — soft toggle. `false` blocks new charges without deleting history.
* `brand`, `last_four`, `expiration_month`, `expiration_year` — for displaying "Visa •••• 4242 (12/27)" in your UI.
* `bin`, `card_type`, `issuer_country` — for routing decisions, fee surcharging, or geo-restricted offers.
* `account_updater_enabled`, `network_token_enabled` — when on, the network refreshes the underlying credential on expiry / re-issuance so saved cards keep working.
* `address` (`Address | null`) — billing address used for AVS.

## Related [#related]

* [API reference](/docs/reference/api/payments/payment-instrument)
* [Guide: Accept a card payment](../guides/accept-card-payment)
* [Guide: Build a custom checkout](../guides/build-custom-checkout)


# Session (/docs/payments/concepts/session)



A **Session** in Payments refers to an **Embedded Checkout Session** — a short-lived, server-created handle that authorizes a single buyer to complete a single checkout inside the Easy Labs hosted iframe. You create the session on your backend with the merchant API key, hand the `client_secret` to your frontend, and the iframe authenticates against that secret instead of your API key. This is what keeps the merchant key off the public web while still letting you customize the surrounding page.

## Lifecycle [#lifecycle]

1. **Created** — `client.createEmbeddedCheckoutSession({ line_items, mode, success_url, cancel_url, customer_email, payment_methods })` returns a `EmbeddedCheckoutSessionData` with `id`, `client_secret`, `url`, `amount_total`, `currency`, `expires_at`, and an initial `status` of `open`.
2. **Open** — the buyer loads your page; you mount `<EmbeddedCheckout clientSecret={…} />` (React) or `mountEmbeddedCheckout("#root", { clientSecret })` (vanilla browser). The iframe validates the session against `/embedded-checkout/validate`.
3. **Confirmed** — the buyer enters payment details inside the iframe; the iframe POSTs to `/embedded-checkout/confirm`. On success the session's `status` transitions to `complete` and `payment_status` to `paid`. The `EmbeddedCheckoutProvider`'s `onSuccess` callback fires with `{ sessionId, status, tx_signature? }`.
4. **Closed** — sessions also reach a terminal state of `expired` when the `expires_at` window elapses without payment. Confirmed sessions cannot be re-used; create a new session for each retry.
5. **Webhook** — `checkout.session.completed` fires server-side when the session reaches `complete`. For crypto payments, `checkout.session.crypto_confirmed` fires when the on-chain transaction is confirmed.

## Relationships [#relationships]

A Session is associated with one **Customer** (created or matched via `customer_email`), produces one **Order** on success, which produces one **Transfer**. The `line_items` reference your **Prices** by ID, which reference **Products**. For crypto payments the session optionally carries a `crypto_payment` block that resolves to a confirmed on-chain transaction (recorded against a **Wallet**).

## Fields that matter [#fields-that-matter]

* `id` (`string`) — the session ID. Use with `getEmbeddedCheckoutSession` for server-side polling.
* `client_secret` (`string`) — pass this to the browser; never log or persist it. Consumed by the iframe to authenticate.
* `url` (`string`) — a fully hosted checkout URL. Use this if you want to redirect instead of embedding.
* `status` (`"open" | "complete" | "expired"`) — coarse session state.
* `payment_status` (`"unpaid" | "paid" | "no_payment_required"`) — payment-side state on the session-status endpoint.
* `amount_total` (`number`), `currency` (`string`) — totals computed from `line_items`.
* `expires_at` (`string`) — ISO timestamp after which the session is no longer usable.
* `payment_methods` (`("card" | "crypto")[]`) — which methods the iframe will offer.

## Related [#related]

* [API reference](/docs/reference/api/payments/embedded-checkout)
* [Guide: Embed hosted checkout](../guides/embed-hosted-checkout)
* [Guide: Build a custom checkout](../guides/build-custom-checkout)


# Transfer (/docs/payments/concepts/transfer)



A **Transfer** is the atomic record of a single money movement — a charge against a Payment Instrument, a refund (reversal), a settlement, or a fee. If you have used Stripe, this is the equivalent of a Charge plus a PaymentIntent collapsed into one object: there is no separate "intent" step, and the same shape covers debits, credits, refunds, and disputes via the `type` field. Most production integrations create Transfers indirectly through Checkout / Embedded Checkout / Subscriptions; the direct `client.createTransfer` API is for headless server-to-server charges against an already-saved Payment Instrument.

## Lifecycle [#lifecycle]

1. **Created** — `PENDING`. `client.createTransfer({ amount, currency, source })` (or any checkout flow) submits the charge to the processor.
2. **Authorized → captured** — the processor authorizes the funding source. For card transfers Easy Labs auto-captures; the state moves to `SUCCEEDED` when funds clear, or `FAILED` with a `failure_code` / `failure_message`.
3. **Settled** — once `ready_to_settle_at` is in the past, the Transfer is included in the next merchant Settlement. Funds appear in the merchant payout.
4. **Reversed (refunded)** — calling `client.createRefund(transferId, { refund_amount })` produces a child Transfer with `type: "REVERSAL"` and `parent_transfer` pointing back at the original. The original Transfer's `state` becomes `REVERSED` once fully reversed.
5. **Disputed** — if the buyer initiates a chargeback, a `dispute.created` webhook fires and a separate Transfer with `type: "DISPUTE"` is created to hold the disputed amount.

Webhooks: `payment.created` and `payment.updated` track the canonical state transitions. `refund.created` / `refund.updated` fire on reversals.

## Relationships [#relationships]

A Transfer has one `source` (a Payment Instrument ID), one `merchant_identity` (the Customer being charged), and optionally one `parent_transfer` (for reversals). Each Order embeds at most one Transfer. Disputes reference Transfers by ID.

## Fields that matter [#fields-that-matter]

* `id` (`string`) — pass to `getTransfer`, `createRefund`, or as `transferId` for dispute lookups.
* `amount`, `amount_requested`, `currency` — the captured amount, the originally requested amount, and ISO currency. Amounts are in the smallest unit (cents for USD).
* `state` (`"PENDING" | "SUCCEEDED" | "FAILED" | "REVERSED" | "CANCELED" | "UNKNOWN"`) — terminal states are `SUCCEEDED`, `FAILED`, `REVERSED`, `CANCELED`.
* `type` (`"DEBIT" | "CREDIT" | "REVERSAL" | "DISPUTE" | "FEE" | "ADJUSTMENT" | "RESERVE" | "SETTLEMENT" | "UNKNOWN"`) — what kind of money movement this is. Filter on `type === "DEBIT"` for buyer charges.
* `failure_code`, `failure_message` — populated when `state === "FAILED"`. Surface these to the buyer for retry-friendly errors (insufficient funds, declined, etc.).
* `parent_transfer` (`string | null`) — set on reversals to the original Transfer's ID.
* `fee` (`number`) — Easy Labs / network fee for this Transfer in the smallest unit.
* `ready_to_settle_at` (`string`) — ISO timestamp when this Transfer is eligible for the next settlement.

## Related [#related]

* [API reference](/docs/reference/api/payments/transfer)
* [Guide: Accept a card payment](../guides/accept-card-payment)
* [Guide: Issue a refund](../guides/issue-refund)


# Accept a card payment (/docs/payments/guides/accept-card-payment)



## Goal [#goal]

Charge an existing Customer's saved card for an arbitrary amount, without rendering a checkout UI. This is the right pattern for headless flows: post-purchase upsells, scheduled jobs that bill on your own cadence, retry of a failed payment, or any backend that already knows which Customer + Payment Instrument to charge.

If you do not yet have a saved Payment Instrument for the Customer, see [Embed hosted checkout](./embed-hosted-checkout) first — that flow tokenizes the card safely and saves the instrument for re-use.

## Prerequisites [#prerequisites]

* Easy Labs API key (sandbox or production) — see [Quickstart](../quickstart).
* `@easylabs/node` installed.
* A `customerId` for the buyer (returned by `createCustomer`).
* A Payment Instrument `id` belonging to that Customer (returned by `createPaymentInstrument`, or fetched via `getCustomerPaymentInstruments`).

## Implementation [#implementation]

### 1. Initialize the client [#1-initialize-the-client]

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

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

`createClient` validates the key against the Easy Labs API before resolving, so a misconfigured environment fails fast at startup rather than on first charge.

### 2. Look up (or pick) the Payment Instrument [#2-look-up-or-pick-the-payment-instrument]

```ts
const { data: instruments } = await easy.getCustomerPaymentInstruments(
  customerId,
);
const card = instruments.find((i) => i.type === "PAYMENT_CARD" && i.enabled);
if (!card) throw new Error("No active card on file");
```

In production you typically store the Payment Instrument `id` on your own customer record at the time of save, instead of re-fetching it on every charge.

### 3. Create the Transfer [#3-create-the-transfer]

```ts
const { data: transfer } = await easy.createTransfer({
  amount: 4999,        // $49.99 in cents
  currency: "USD",
  source: card.id,
  tags: { internal_order_id: "order_123" },
});

if (transfer.state === "FAILED") {
  // Surface a buyer-friendly retry path.
  throw new Error(transfer.failure_message ?? "Payment failed");
}
```

A `Transfer` with `state: "SUCCEEDED"` is a captured charge — funds will appear in the next merchant Settlement once `ready_to_settle_at` passes. `state: "PENDING"` means the processor is still working; subscribe to the `payment.updated` webhook to be notified of the terminal state without polling.

### 4. (Optional) React to webhooks [#4-optional-react-to-webhooks]

If you want server-side confirmation rather than relying on the synchronous response, register a webhook endpoint and verify deliveries with `EasyWebhooks.constructEvent`:

```ts
import { EasyWebhooks } from "@easylabs/node";

app.post("/webhooks/easy", async (req, res) => {
  const event = EasyWebhooks.constructEvent(
    req.rawBody,
    req.header("x-easy-webhook-signature") ?? "",
    process.env.EASY_WEBHOOK_SECRET!,
  );
  if (event.type === "payment.updated") {
    // event.data is the Transfer
  }
  res.status(204).end();
});
```

## Tradeoffs [#tradeoffs]

* This pattern requires that the buyer has previously consented to save a card with you. For the first charge, use [Embed hosted checkout](./embed-hosted-checkout) — it tokenizes safely and returns a re-usable instrument id.
* Direct Transfers do not produce an [Order](../concepts/order). If you need line-item bookkeeping, use `client.checkout({ … })` instead, which produces both a Transfer and an Order with line items.
* Refunds are issued against the Transfer ID — not the Customer or instrument. See [Issue a refund](./issue-refund).

## Related [#related]

* [Concept: Transfer](../concepts/transfer)
* [Concept: Payment Instrument](../concepts/payment-instrument)
* [API reference](/docs/reference/api/payments/transfer)


# Accept a wallet payment (/docs/payments/guides/accept-wallet-payment)



## Goal [#goal]

Accept payment in stablecoins from a buyer's self-custodial wallet (currently Solana / USDC) and reconcile the on-chain transaction back to an Order in your dashboard. Wallet payments are exposed through the same Embedded Checkout surface as card payments — you opt into them by including `"crypto"` in the session's `payment_methods`. The iframe handles wallet connection, message signing, and broadcasting the transaction; your code listens for the confirmed-on-chain event.

## Prerequisites [#prerequisites]

* Easy Labs API key with crypto enabled on your account — see [Quickstart](../quickstart).
* `@easylabs/node` (server) and `@easylabs/react` or `@easylabs/browser` (frontend) installed.
* Your origin added to `allowed_origins` via `client.updateEmbeddedCheckoutConfig`.

## Implementation [#implementation]

### 1. Create a session that allows crypto [#1-create-a-session-that-allows-crypto]

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

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

const { data: session } = await easy.createEmbeddedCheckoutSession({
  mode: "payment",
  line_items: [{ price_id: "price_01HXXXXXXXXXXX", quantity: 1 }],
  success_url: "https://your-app.com/checkout/success",
  cancel_url: "https://your-app.com/checkout/cancel",
  payment_methods: ["card", "crypto"], // both, or ["crypto"] only
});
```

Pass `["crypto"]` alone to force the wallet flow; pass both to let the buyer pick. The session's response carries a `crypto_payment` block with the destination address, USDC amount, and Solana Pay URL the iframe will use.

### 2. Mount the iframe and listen for confirmation [#2-mount-the-iframe-and-listen-for-confirmation]

In React, `EmbeddedCheckoutProvider`'s `onSuccess` callback fires for both card and crypto completions. The crypto-specific event includes the on-chain transaction signature:

```tsx
"use client";
import { EmbeddedCheckout, EmbeddedCheckoutProvider } from "@easylabs/react";

export function CryptoCheckout({ clientSecret }: { clientSecret: string }) {
  return (
    <EmbeddedCheckoutProvider
      config={{
        clientSecret,
        onSuccess: ({ sessionId, status, tx_signature }) => {
          // For crypto payments, tx_signature is the Solana transaction signature.
          console.log("paid", { sessionId, status, tx_signature });
        },
      }}
    >
      <EmbeddedCheckout clientSecret={clientSecret} />
    </EmbeddedCheckoutProvider>
  );
}
```

In vanilla JS:

```ts
import { mountEmbeddedCheckout } from "@easylabs/browser";

const handle = mountEmbeddedCheckout("#checkout", {
  clientSecret,
  onCryptoConfirmed: (data) => {
    console.log("crypto confirmed", data);
  },
});
```

### 3. (Optional) Poll the chain status server-side [#3-optional-poll-the-chain-status-server-side]

If the buyer leaves the page before the iframe reports confirmation, you can poll the session's crypto status from your backend:

```ts
const { data: cryptoStatus } = await easy.getCryptoPaymentStatus(session.id);
// cryptoStatus.status: "pending" | "confirmed" | "expired" | "failed"
// cryptoStatus.tx_signature: the on-chain signature once confirmed
```

The canonical signal is still the `checkout.session.crypto_confirmed` webhook — register it and use it to fulfill orders without depending on the browser staying open.

## Tradeoffs [#tradeoffs]

* Crypto payments are USDC-only on Solana today. Other chains and tokens are on the roadmap.
* The iframe handles wallet connection — you do not need to bundle a wallet adapter or `@solana/web3.js` in your app.
* Refunds for crypto transactions are not automatic; they require an off-chain reconciliation. Open a support ticket if you need to refund a confirmed crypto Order.
* `tx_signature` is the buyer's proof of payment on-chain. Store it alongside your Order for audit / customer service.

## Related [#related]

* [Concept: Session](../concepts/session)
* [Concept: Order](../concepts/order)
* [API reference](/docs/reference/api/payments/embedded-checkout)


# Build a custom checkout (/docs/payments/guides/build-custom-checkout)



## Goal [#goal]

Build a checkout where you own the surrounding page composition, multi-step navigation, and post-payment logic, while delegating the actual card / bank-account entry to a securely hosted surface. The pattern: create the checkout session on your server, pass the `client_secret` to the browser, mount the iframe inside your own multi-step UI, and react to the iframe's lifecycle events. For most teams this is the right escape valve when [Embed hosted checkout](./embed-hosted-checkout) feels too constraining but going all the way to raw card tokenization is more compliance scope than you want to take on.

## Prerequisites [#prerequisites]

* Easy Labs API key — see [Quickstart](../quickstart).
* `@easylabs/node` (server) and `@easylabs/react` or `@easylabs/browser` (frontend) installed.
* Origin added to `allowed_origins` via `client.updateEmbeddedCheckoutConfig`.
* A frontend that can manage multi-step state (your own framework / store).

## Implementation [#implementation]

### 1. Server: create the session with your own line items [#1-server-create-the-session-with-your-own-line-items]

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

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

export async function POST(req: Request) {
  const { cart, buyerEmail } = (await req.json()) as {
    cart: Array<{ priceId: string; quantity: number }>;
    buyerEmail: string;
  };

  const { data: session } = await easy.createEmbeddedCheckoutSession({
    mode: "payment",
    customer_email: buyerEmail,
    line_items: cart.map((i) => ({ price_id: i.priceId, quantity: i.quantity })),
    success_url: "https://your-app.com/checkout/success",
    cancel_url: "https://your-app.com/checkout/cancel",
    metadata: { source: "custom_checkout_v2" },
    payment_methods: ["card"],
  });

  return Response.json({
    clientSecret: session.client_secret,
    sessionId: session.id,
    amountTotal: session.amount_total,
    currency: session.currency,
  });
}
```

### 2. Frontend: orchestrate your own steps, mount the iframe at the payment step [#2-frontend-orchestrate-your-own-steps-mount-the-iframe-at-the-payment-step]

```tsx
"use client";
import {
  EmbeddedCheckout,
  EmbeddedCheckoutProvider,
  useEmbeddedCheckout,
} from "@easylabs/react";
import { useState } from "react";

type Step = "review" | "payment" | "done";

export function CustomCheckout({ clientSecret }: { clientSecret: string }) {
  const [step, setStep] = useState<Step>("review");

  if (step === "review") {
    return (
      <ReviewStep onContinue={() => setStep("payment")} />
    );
  }

  if (step === "payment") {
    return (
      <EmbeddedCheckoutProvider
        config={{
          clientSecret,
          onSuccess: () => setStep("done"),
          onClose: () => setStep("review"),
          onError: (err) => alert(err),
        }}
      >
        <CheckoutShell />
      </EmbeddedCheckoutProvider>
    );
  }

  return <DoneStep />;
}

function CheckoutShell() {
  const { status } = useEmbeddedCheckout();
  return (
    <div>
      {status === "loading" && <p>Preparing payment…</p>}
      <EmbeddedCheckout
        clientSecret={/* …passed in via props or context */ ""}
      />
    </div>
  );
}
```

`useEmbeddedCheckout()` exposes the current `status` (`"loading" | "ready" | "complete" | "error"`) so you can render skeletons, disable a parent "Pay now" CTA, or trigger analytics events as the iframe's lifecycle progresses.

### 3. Server: confirm and fulfill on the webhook [#3-server-confirm-and-fulfill-on-the-webhook]

The browser callback is convenient for UI transitions but is not the source of truth. Use the `checkout.session.completed` webhook to fulfill the order:

```ts
import { EasyWebhooks } from "@easylabs/node";

app.post("/webhooks/easy", async (req, res) => {
  const event = EasyWebhooks.constructEvent(
    req.rawBody,
    req.header("x-easy-webhook-signature") ?? "",
    process.env.EASY_WEBHOOK_SECRET!,
  );
  if (event.type === "checkout.session.completed") {
    // Look up your internal cart by session.metadata, then fulfill.
  }
  res.status(204).end();
});
```

## Tradeoffs [#tradeoffs]

* The iframe still renders the actual payment fields — you own the page chrome and step navigation but not the form layout. If you need a fully custom card form rendered with your own components, contact your account team about the white-label tokenization SDK; it carries additional PCI scope.
* One session = one payment attempt. If the buyer changes their cart between steps, create a new session. Cache the session at the cart-hash level to avoid creating one per render.
* `useEmbeddedCheckout` is a React hook; in vanilla JS the equivalent signal is the `onReady` callback on `mountEmbeddedCheckout`.

## Related [#related]

* [Concept: Session](../concepts/session)
* [Guide: Embed hosted checkout](./embed-hosted-checkout)
* [API reference](/docs/reference/api/payments/embedded-checkout)


# Embed hosted checkout (/docs/payments/guides/embed-hosted-checkout)



## Goal [#goal]

Render the Easy Labs checkout inside your own page so the buyer never leaves your site, while keeping all card / bank entry inside the hosted iframe (which means the merchant API key never reaches the browser, and your servers never touch raw PAN data). This is the recommended default for accepting first-time payments.

## Prerequisites [#prerequisites]

* Easy Labs API key — see [Quickstart](../quickstart).
* `@easylabs/node` for the server, `@easylabs/react` (or `@easylabs/browser` for vanilla JS) for the browser.
* At least one published Product + Price you can charge for. Create them in the dashboard or with `client.createProduct` / `client.createPrice`.
* Your site's origin added to the merchant's `allowed_origins` config. Set it once with `client.updateEmbeddedCheckoutConfig({ allowed_origins: ["https://your-app.com"] })`.

## Implementation [#implementation]

### 1. Create a session on the server [#1-create-a-session-on-the-server]

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

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

export async function POST() {
  const { data: session } = await easy.createEmbeddedCheckoutSession({
    mode: "payment",
    line_items: [{ price_id: "price_01HXXXXXXXXXXX", quantity: 1 }],
    success_url: "https://your-app.com/checkout/success",
    cancel_url: "https://your-app.com/checkout/cancel",
    customer_email: "ada@example.com",
    payment_methods: ["card"],
  });
  return Response.json({ clientSecret: session.client_secret });
}
```

`session.client_secret` authenticates the iframe against the session — it is safe to send to the browser. The merchant API key stays on the server.

### 2. Mount the iframe in the browser [#2-mount-the-iframe-in-the-browser]

With React:

```tsx
"use client";
import { EmbeddedCheckout, EmbeddedCheckoutProvider } from "@easylabs/react";
import { useEffect, useState } from "react";

export function Checkout() {
  const [clientSecret, setClientSecret] = useState<string | null>(null);

  useEffect(() => {
    fetch("/api/checkout-session", { method: "POST" })
      .then((r) => r.json())
      .then(({ clientSecret }) => setClientSecret(clientSecret));
  }, []);

  if (!clientSecret) return <p>Loading checkout…</p>;

  return (
    <EmbeddedCheckoutProvider
      config={{
        clientSecret,
        onSuccess: ({ sessionId }) => {
          window.location.href = `/checkout/success?session=${sessionId}`;
        },
        onError: (err) => console.error("checkout error", err),
        onClose: () => console.log("buyer closed checkout"),
      }}
    >
      <EmbeddedCheckout clientSecret={clientSecret} />
    </EmbeddedCheckoutProvider>
  );
}
```

With vanilla JS / `@easylabs/browser`:

```ts
import { mountEmbeddedCheckout } from "@easylabs/browser";

const handle = mountEmbeddedCheckout("#checkout", {
  clientSecret,
  onReady: () => console.log("checkout ready"),
});

// later — destroy when navigating away:
handle.unmount();
```

### 3. Confirm on the server (recommended) [#3-confirm-on-the-server-recommended]

Don't trust the browser's `onSuccess` alone — confirm the session server-side before fulfilling, either by handling the `checkout.session.completed` webhook or by reading the session status:

```ts
import { EasyWebhooks } from "@easylabs/node";

app.post("/webhooks/easy", async (req, res) => {
  const event = EasyWebhooks.constructEvent(
    req.rawBody,
    req.header("x-easy-webhook-signature") ?? "",
    process.env.EASY_WEBHOOK_SECRET!,
  );
  if (event.type === "checkout.session.completed") {
    // event.data is the completed session — fulfill the order here.
  }
  res.status(204).end();
});
```

## Tradeoffs [#tradeoffs]

* The iframe owns the look and feel within its bounds — you control the surrounding page, theme color, and logo (set via the merchant branding API), but the form layout itself is managed.
* For a fully bespoke UI where you render your own card form, see [Build a custom checkout](./build-custom-checkout).
* Sessions are single-use. If the buyer abandons and comes back, create a new session.
* The iframe's allowed-origin list is a hard security boundary. Forgetting to add a new domain results in a `validate` failure inside the iframe with no charge attempted.

## Related [#related]

* [Concept: Session](../concepts/session)
* [Concept: Order](../concepts/order)
* [API reference](/docs/reference/api/payments/embedded-checkout)


# Handle a dispute (/docs/payments/guides/handle-dispute)



## Goal [#goal]

Build the operational glue around chargebacks: fire an alert when a Dispute opens, surface it in your internal tooling alongside the original Order, and update your records when the network rules. Most evidence collection happens through the dashboard; the SDK's role is detection, correlation, and bookkeeping.

## Prerequisites [#prerequisites]

* Easy Labs API key — see [Quickstart](../quickstart).
* `@easylabs/node` installed.
* A registered webhook endpoint that subscribes to `dispute.created` and `dispute.updated`. Register one with `client.registerWebhookEndpoint({ url, events: ["dispute.created", "dispute.updated"] })` and store the returned signing secret immediately — it is only ever returned once.

## Implementation [#implementation]

### 1. Listen for new disputes [#1-listen-for-new-disputes]

```ts
import { createClient, EasyWebhooks } from "@easylabs/node";

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

app.post("/webhooks/easy", async (req, res) => {
  const event = EasyWebhooks.constructEvent(
    req.rawBody,
    req.header("x-easy-webhook-signature") ?? "",
    process.env.EASY_WEBHOOK_SECRET!,
  );

  if (event.type === "dispute.created") {
    const dispute = event.data as { id: string; transfer: string };
    await alertOpsTeam({
      disputeId: dispute.id,
      transferId: dispute.transfer,
    });
  }

  if (event.type === "dispute.updated") {
    const dispute = event.data as { id: string; status: string };
    await updateInternalRecord(dispute.id, dispute.status);
  }

  res.status(204).end();
});
```

`EasyWebhooks.constructEvent` verifies the HMAC-SHA256 signature against the raw request body. **Do not parse the body before passing it in** — JSON re-stringifying changes whitespace and breaks the signature check.

### 2. Correlate the Dispute back to your Order [#2-correlate-the-dispute-back-to-your-order]

The Dispute's `transfer` field is the Transfer ID; from there you can resolve the Order:

```ts
const { data: dispute } = await easy.getDispute(disputeId);
const transferId = dispute.transfer as string;

const { data: transfer } = await easy.getTransfer(transferId);
// In production, look up your internal order using transfer.tags.internal_order_id
// or by querying your DB for the matching Customer + amount + timestamp.
```

If you set `tags` on the Transfer or Order at creation time (e.g. `tags: { internal_order_id }`), this lookup is a single DB query.

### 3. Tag the Dispute for internal triage [#3-tag-the-dispute-for-internal-triage]

You can attach your own metadata to the Dispute so it correlates with your internal ticketing system:

```ts
await easy.updateDispute(disputeId, {
  internal_case_id: "CASE-2026-00123",
  assigned_to: "ops-team",
});
```

`tags` are the only mutable surface on a Dispute — submitting evidence happens through the dashboard.

### 4. Resolve [#4-resolve]

When `dispute.updated` fires with a terminal status (`WON`, `LOST`, `ACCEPTED`), update your books:

* `WON` — funds return to the merchant settlement; reverse any provisional refund you issued.
* `LOST` — funds remain with the buyer; write off the loss against the original Order.
* `ACCEPTED` — you chose not to contest; same financial impact as `LOST`.

## Tradeoffs [#tradeoffs]

* The SDK does not currently expose programmatic evidence upload — that workflow lives in the dashboard. If you need API-driven evidence for a custom internal tool, talk to your account team.
* The Dispute schema is processor-permissive (`{ id: string; [key: string]: unknown }`) — fields beyond `id`, `amount`, `currency`, `status`, `transfer`, `reason_code`, and `respond_by` may vary across networks. Treat unknown fields defensively.
* Always rely on `dispute.updated` for terminal status. Polling `getDispute` works but wastes API budget.

## Related [#related]

* [Concept: Dispute](../concepts/dispute)
* [Concept: Transfer](../concepts/transfer)
* [API reference](/docs/reference/api/payments/dispute)


# Payments guides (/docs/payments/guides)



Step-by-step recipes for the most common Payments integrations. Each guide states the goal, lists prerequisites, and ships working code.



<Cards>
  <Card title="Accept Card Payment" href="./guides/accept-card-payment" description="Accept Card Payment with Easy Payments." />

  <Card title="Embed Hosted Checkout" href="./guides/embed-hosted-checkout" description="Embed Hosted Checkout with Easy Payments." />

  <Card title="Build Custom Checkout" href="./guides/build-custom-checkout" description="Build Custom Checkout with Easy Payments." />

  <Card title="Accept Wallet Payment" href="./guides/accept-wallet-payment" description="Accept Wallet Payment with Easy Payments." />

  <Card title="Handle Dispute" href="./guides/handle-dispute" description="Handle Dispute with Easy Payments." />

  <Card title="Issue Refund" href="./guides/issue-refund" description="Issue Refund with Easy Payments." />
</Cards>


# Issue a refund (/docs/payments/guides/issue-refund)



## Goal [#goal]

Refund a successful charge back to the original payment method, in part or in full. Refunds in Easy Labs are first-class Transfers themselves (with `type: "REVERSAL"`) — they link to the original via `parent_transfer`, fire their own webhooks, and settle on their own timeline. This guide covers the most common cases: full refund of a recent charge, partial refund (e.g. one returned line item), and detecting that a refund has finished.

## Prerequisites [#prerequisites]

* Easy Labs API key — see [Quickstart](../quickstart).
* `@easylabs/node` installed.
* The `transferId` of the original successful charge. From an Order, this is `order.transfer.id`.

## Implementation [#implementation]

### 1. Issue a full refund [#1-issue-a-full-refund]

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

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

const { data: original } = await easy.getTransfer(transferId);
const { data: refund } = await easy.createRefund(transferId, {
  refund_amount: original.amount, // full amount, in the smallest currency unit
});

// refund.id is the new reversal Transfer.
// refund.parent_transfer === transferId
```

The reversal is created in the `PENDING` state and progresses to `SUCCEEDED` once the issuer accepts it. The original Transfer's state moves to `REVERSED` once fully reversed.

### 2. Issue a partial refund [#2-issue-a-partial-refund]

```ts
const { data: partial } = await easy.createRefund(transferId, {
  refund_amount: 1000, // $10.00 of the original $50.00 charge
  tags: { reason: "returned_one_item", internal_rma_id: "RMA-789" },
});
```

You can issue multiple partial refunds against the same original Transfer up to the original amount. After the sum of reversals equals the original `amount`, the original transitions to `REVERSED`.

### 3. (Optional) Subscribe to the refund webhook [#3-optional-subscribe-to-the-refund-webhook]

If you want server-side confirmation rather than polling, subscribe to `refund.created` and `refund.updated`:

```ts
import { EasyWebhooks } from "@easylabs/node";

app.post("/webhooks/easy", async (req, res) => {
  const event = EasyWebhooks.constructEvent(
    req.rawBody,
    req.header("x-easy-webhook-signature") ?? "",
    process.env.EASY_WEBHOOK_SECRET!,
  );
  if (event.type === "refund.updated") {
    // event.data is the reversal Transfer
  }
  res.status(204).end();
});
```

### 4. Verify in the dashboard [#4-verify-in-the-dashboard]

Open the original Order in the [Easy Labs dashboard](https://dashboard.itseasy.co) — you will see the linked reversal under "Refunds" with its own state and amount.

## Tradeoffs [#tradeoffs]

* Refunds always go back to the original Payment Instrument; you cannot re-route a refund to a different card or to a wallet.
* Crypto Orders are not refundable through `createRefund`. For confirmed on-chain payments, open a support ticket and reconcile off-chain.
* Refunds fire `refund.created` / `refund.updated` events, NOT `payment.updated` events. Wire up the right handler.
* A failed refund (issuer rejects) sets the reversal's `state` to `FAILED`; the original Transfer is unchanged. Surface the `failure_message` to your ops team.

## Related [#related]

* [Concept: Transfer](../concepts/transfer)
* [Concept: Order](../concepts/order)
* [API reference](/docs/reference/api/payments/transfer)


# Migrate from Stripe to Easy Payments (/docs/payments/migration/from-stripe)



This page is the mechanical method-and-event mapping between the Stripe Node SDK and `@easylabs/node`. Field names mostly carry over; the larger conceptual shift is that Easy Labs collapses Stripe's PaymentIntent / Charge / SetupIntent split into a single `Transfer` lifecycle. See **Object model differences** at the bottom.

## API surface mapping [#api-surface-mapping]

| Stripe                                             | Easy Labs                                                                                                                                               | Notes                                                                                                           |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `stripe.customers.create({ email, name })`         | `easy.createCustomer({ first_name, last_name, email })`                                                                                                 | First/last name are required and split into separate fields.                                                    |
| `stripe.customers.retrieve(id)`                    | `easy.getCustomer(id)`                                                                                                                                  | Identical.                                                                                                      |
| `stripe.customers.update(id, …)`                   | `easy.updateCustomer(id, partial)`                                                                                                                      | Identical.                                                                                                      |
| `stripe.customers.list({ limit })`                 | `easy.getCustomers({ limit, offset })`                                                                                                                  | Pagination is `offset`-based, not cursor-based.                                                                 |
| `stripe.customers.listPaymentMethods(id)`          | `easy.getCustomerPaymentInstruments(id)`                                                                                                                | Returns Payment Instruments instead of PaymentMethods.                                                          |
| `stripe.paymentMethods.create({ type: "card" })`   | Use `mountEmbeddedCheckout` (`@easylabs/browser`) or `<EmbeddedCheckout>` (`@easylabs/react`); the iframe tokenizes and creates the Payment Instrument. | No raw card → token call on the server.                                                                         |
| `stripe.paymentMethods.retrieve(id)`               | Available implicitly via `easy.getCustomerPaymentInstruments(customerId).find(i => i.id === pmId)`                                                      | No standalone get-by-id endpoint.                                                                               |
| `stripe.paymentMethods.update(id, …)`              | `easy.updatePaymentInstrument(id, partial)`                                                                                                             | Includes `enabled`, `address`, `tags`.                                                                          |
| `stripe.paymentIntents.create({ amount, … })`      | `easy.createTransfer({ amount, currency, source })`                                                                                                     | No two-step intent → confirm. Authorization + capture happen in one call against a Payment Instrument.          |
| `stripe.paymentIntents.confirm(id)`                | n/a                                                                                                                                                     | Implicit; `createTransfer` is the equivalent of "create + confirm".                                             |
| `stripe.charges.create({ … })`                     | `easy.createTransfer({ amount, currency, source })`                                                                                                     | Renamed; same contract.                                                                                         |
| `stripe.charges.retrieve(id)`                      | `easy.getTransfer(id)`                                                                                                                                  | Identical.                                                                                                      |
| `stripe.charges.list({ limit })`                   | `easy.getTransfers({ limit, offset })`                                                                                                                  | Pagination differences as above.                                                                                |
| `stripe.refunds.create({ charge, amount })`        | `easy.createRefund(transferId, { refund_amount })`                                                                                                      | Reversal is itself a Transfer with `type: "REVERSAL"`.                                                          |
| `stripe.disputes.retrieve(id)`                     | `easy.getDispute(id)`                                                                                                                                   | Identical.                                                                                                      |
| `stripe.disputes.list()`                           | `easy.getDisputes({ limit, offset })`                                                                                                                   | Pagination differences.                                                                                         |
| `stripe.disputes.update(id, { metadata })`         | `easy.updateDispute(id, tags)`                                                                                                                          | Tags are the only mutable surface; evidence upload is dashboard-only today.                                     |
| `stripe.checkout.sessions.create({ … })`           | `easy.createEmbeddedCheckoutSession({ … })`                                                                                                             | `success_url` / `cancel_url` / `line_items` shapes carry over. Add `payment_methods: ["card"]` (or `"crypto"`). |
| `stripe.checkout.sessions.retrieve(id)`            | `easy.getEmbeddedCheckoutSession(id)`                                                                                                                   | Identical.                                                                                                      |
| `stripe.products.create(…)` / `.update` / `.list`  | `easy.createProduct` / `.updateProduct` / `.getProducts`                                                                                                | Identical surface.                                                                                              |
| `stripe.prices.create(…)` / `.update` / `.list`    | `easy.createPrice` / `.updatePrice` / `.getPrices`                                                                                                      | `unit_amount` is in the smallest currency unit, same as Stripe.                                                 |
| `stripe.subscriptions.create({ customer, items })` | `easy.createSubscription({ identity_id, items, instrument_id })`                                                                                        | `customer` → `identity_id`. Funding source must be passed explicitly.                                           |
| `stripe.subscriptions.cancel(id)`                  | `easy.cancelSubscription(id, { at_period_end: true })`                                                                                                  | Default cancels immediately; opt into period-end via flag.                                                      |
| `stripe.invoices.create(…)`                        | `easy.createInvoice(…)`                                                                                                                                 | Field names differ; see invoice reference.                                                                      |
| `stripe.webhookEndpoints.create(…)`                | `easy.registerWebhookEndpoint({ url, events })`                                                                                                         | Returns the signing secret **once**; persist immediately.                                                       |
| `stripe.webhooks.constructEvent(body, sig, sec)`   | `EasyWebhooks.constructEvent(rawBody, sig, secret)`                                                                                                     | Identical signature. Header is `x-easy-webhook-signature`.                                                      |

## Webhook event mapping [#webhook-event-mapping]

| Stripe event                           | Easy Labs event                       | Notes                                                                   |
| -------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------- |
| `payment_intent.succeeded`             | `payment.updated` (state `SUCCEEDED`) | Easy Labs collapses intent + charge events into one `payment.*` stream. |
| `payment_intent.payment_failed`        | `payment.updated` (state `FAILED`)    | `failure_code` + `failure_message` are populated on the Transfer.       |
| `charge.succeeded`                     | `payment.created` / `payment.updated` | The single Transfer lifecycle covers both.                              |
| `charge.refunded`                      | `refund.updated` (state `SUCCEEDED`)  | The reversal is its own Transfer event.                                 |
| `charge.refund.updated`                | `refund.updated`                      | Identical semantics.                                                    |
| `charge.dispute.created`               | `dispute.created`                     | Identical.                                                              |
| `charge.dispute.closed`                | `dispute.updated` (terminal status)   | Watch for `status` transitioning to `WON` / `LOST`.                     |
| `checkout.session.completed`           | `checkout.session.completed`          | Identical name.                                                         |
| `customer.subscription.created`        | `subscription.created`                | Identical.                                                              |
| `customer.subscription.updated`        | `subscription.updated`                | Identical.                                                              |
| `customer.subscription.deleted`        | `subscription.deleted`                | Identical.                                                              |
| `customer.subscription.paused`         | `subscription.paused`                 | Identical.                                                              |
| `customer.subscription.resumed`        | `subscription.resumed`                | Identical.                                                              |
| `customer.subscription.trial_will_end` | `subscription.trial_will_end`         | Identical.                                                              |
| `invoice.created`                      | `invoice.created`                     | Identical.                                                              |
| `invoice.finalized`                    | `invoice.finalized`                   | Identical.                                                              |
| `invoice.paid`                         | `invoice.paid`                        | Identical.                                                              |
| `invoice.payment_failed`               | `invoice.payment_failed`              | Identical.                                                              |
| `customer.created`                     | `identity.created`                    | "Identity" is the underlying processor entity for Customer.             |
| `customer.updated`                     | `identity.updated`                    | Identical semantics.                                                    |

## Object model differences [#object-model-differences]

* **No PaymentIntent.** Stripe separates "intent to charge" from "actual charge"; Easy Labs has one `Transfer` lifecycle that covers both (`PENDING → SUCCEEDED | FAILED`). If you used `PaymentIntent.id` to correlate before/after capture, switch to `Transfer.id`.
* **Identity vs. Customer.** Internally Easy Labs calls customers "identities" (you'll see `identity_id` on Subscriptions, `identity` on Orders, and `identity.*` webhook events). The SDK surface still uses `customer` everywhere — `identity_id` is the field name on payloads.
* **Payment Instruments are saved by default.** A successful checkout always produces a re-usable `Payment Instrument`. There is no separate SetupIntent for "save card without charging" — instead, create a small auth + void or save during a real first payment.
* **Order is a first-class object.** Stripe doesn't have one — it conflates "the transaction" with "the line items." Easy Labs separates Order (line items, totals, customer details) from Transfer (money movement), so refunds happen against the Transfer but fulfillment data lives on the Order.
* **Pagination is offset-based.** No `starting_after` / `ending_before` cursors. Pass `limit` + `offset`.
* **Webhook signature header.** Stripe uses `Stripe-Signature` with a `t=…,v1=…` payload; Easy Labs uses `x-easy-webhook-signature: sha256=<hex>` over the raw body. The Node verifier handles this for you (`EasyWebhooks.constructEvent`).


# Migrate to Easy Payments (/docs/payments/migration)



Mechanical mappings from competing APIs to Easy Payments. Each migration page covers method-by-method translation, webhook event pairs, and meaningful conceptual differences.



<Cards>
  <Card title="From Stripe" href="./migration/from-stripe" description="Stripe → Easy Payments mapping." />
</Cards>


# API (/docs/reference/api)





The Easy HTTP API is split into four products. Each operation lives under its product's section in the sidebar — pick the surface you're integrating with.

<Cards>
  <Card title="Payments" href="/docs/reference/api/payments" description="Customers, payment instruments, checkout, disputes, refunds." />

  <Card title="Billing" href="/docs/reference/api/billing" description="Subscriptions, invoices, coupons, customer portal." />

  <Card title="Treasury" href="/docs/reference/api/treasury" description="Payouts, recipients, settlements, tax documents." />

  <Card title="Account & operations" href="/docs/reference/api/account-and-operations" description="Branding, custom domains, webhooks, files, security rules." />
</Cards>

Looking for SDK code samples instead? See the [SDK reference](/docs/sdks).


# Client (/docs/sdks/javascript/client)



`createEasyClient` returns an `EasyBrowserClient` — the typed `EasyApiClient` from `@easylabs/common` decorated with browser-only helpers. One client wraps one API key. Construct it once at app startup and pass it around (via your DI container, a module-level singleton, or your framework's context primitive).

The factory validates the supplied key against `GET /validate-key` before resolving, so a successful `await` is your guarantee that the key works against the resolved environment.

## Constructor [#constructor]

```ts
import { createEasyClient } from "@easylabs/browser";

const easy = await createEasyClient({
  apiKey: "sk_test_...",
});
```

### Options [#options]

| Option               | Type      | Required | Description                                                                                                                       |
| -------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`             | `string`  | yes      | Your Easy Labs secret key. Keys prefixed `sk_test_` route to the sandbox environment; everything else routes to production.       |
| `__internal_api_url` | `string`  | no       | **Internal.** Override the resolved API base URL. Used for tests and local development. Public consumers should leave this unset. |
| `__dev`              | `boolean` | no       | **Internal, deprecated.** No-op. Kept on the type for source compatibility and will be removed in a future major.                 |

### Throws [#throws]

* `Error("apiKey is required to create an Easy Labs browser client.")` if `apiKey` is empty.
* `Error("API key validation failed: ...")` if the key is rejected by `/validate-key`.
* A network error if the API is unreachable.

### Direct import [#direct-import]

If you only need the embedded-checkout helper, you don't have to construct a client at all — `mountEmbeddedCheckout` is a tree-shakeable named export:

```ts
import { mountEmbeddedCheckout } from "@easylabs/browser";
```

It authenticates against the session's `client_secret`, not your API key.

The [Element factories](./elements) (`mountCardNumberElement`, etc.) and the [wallet button factories](./wallet-checkout) (`createApplePayButton`, `createGooglePayButton`) are also tree-shakeable named exports. Element factories require an initialised Basis Theory client — call `createEasyClient` first, or use `configureBasisTheoryFromKey(apiKey, apiUrl)` for a lighter bootstrap when you don't need the typed `EasyApiClient` surface.

## Core methods [#core-methods]

The returned client exposes the full `EasyApiClient` surface from `@easylabs/common`. A representative slice — these are all methods you call **on the client instance** (`easy.createCustomer(...)`):

| Method                                                                           | Purpose                                                                                 |
| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `createCustomer(data)` / `getCustomer(id)` / `getCustomers(params)`              | Customer CRUD.                                                                          |
| `createEmbeddedCheckoutSession(data)`                                            | Mint a session server-side. **Do not call from the browser** — exposes your secret key. |
| `getEmbeddedCheckoutSession(id)`                                                 | Fetch session status (open / complete / expired).                                       |
| `validateEmbeddedCheckoutSession(body)` / `confirmEmbeddedCheckoutSession(body)` | Iframe-context endpoints. Authenticate via `client_secret`, not the API key.            |
| `getCryptoPaymentStatus(sessionId)`                                              | Poll a session's crypto payment state.                                                  |
| `createPaymentLink(payload)` / `getPaymentLinks(params)` / `getPaymentLink(id)`  | Payment-link CRUD.                                                                      |
| `createPaymentInstrument(data)` / `updatePaymentInstrument(id, data)`            | Payment instrument management.                                                          |
| `getProducts(params)`                                                            | List products.                                                                          |
| `listInvoices(query)`                                                            | List invoices with filters.                                                             |

For the complete surface, refer to the type definitions exported from `@easylabs/common` (re-exported from `@easylabs/browser`). Every method returns a typed `ApiResponse<T>` and throws `EasyApiError` on non-2xx responses.

### Related exports [#related-exports]

These are **standalone factory functions** exported from `@easylabs/browser` — they are *not* methods on the client returned by `createEasyClient`. Import them directly and call them with their own arguments:

| Export                                                                                                                | Purpose                                                                                                                                                                   |
| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mountEmbeddedCheckout(container, options)`                                                                           | Mount the hosted-checkout iframe. Authenticates against the session's `client_secret`, so no client construction is needed. See [Embedded Checkout](./embedded-checkout). |
| `mountCardNumberElement` / `mountCardExpirationDateElement` / `mountCardVerificationCodeElement` / `mountTextElement` | Mount iframed PCI-isolated form fields. Require an initialised Basis Theory client (see below). See [Elements](./elements).                                               |
| `tokenize({ cardNumber, cardExpiration, cardCvc })`                                                                   | Exchange three mounted card elements for a Basis Theory token reference.                                                                                                  |
| `createApplePayButton` / `createGooglePayButton`                                                                      | Render native wallet buttons. See [Wallet Checkout](./wallet-checkout).                                                                                                   |
| `configureBasisTheoryFromKey(apiKey, apiUrl?)`                                                                        | Lighter bootstrap for Element factories when you don't need the typed `EasyApiClient` surface. `createEasyClient` already runs this for you.                              |

Element factories require Basis Theory to be initialised first — call `createEasyClient` (which initialises it as part of bootstrap) or `configureBasisTheoryFromKey` before mounting any element.

### Errors [#errors]

Every API call rejects with an `EasyApiError` carrying the HTTP status, the API error `code`, and the parsed `details` payload:

```ts
import { EasyApiError } from "@easylabs/browser";

try {
  await easy.cancelSubscription("sub_123");
} catch (err) {
  if (err instanceof EasyApiError && err.status === 429) {
    await new Promise((r) =>
      setTimeout(r, (err.retryAfterSeconds ?? 1) * 1000),
    );
  } else {
    throw err;
  }
}
```

## Lifecycle [#lifecycle]

The client holds no long-lived resources — no sockets, no timers, no listeners. It's a thin façade over `fetch` plus an in-memory copy of your API key. You can construct it as many times as you want, but in practice one instance per app is the right shape.

There is no `dispose` or `close`. To "tear it down", drop your reference and let the garbage collector handle it.

`mountEmbeddedCheckout` **does** create resources (a `<iframe>` element and a `window` `message` listener). Call `handle.unmount()` when navigating away from the checkout — see [Embedded Checkout › Cleanup](./embedded-checkout#cleanup).


# Elements (/docs/sdks/javascript/elements)



Elements are framework-agnostic mount functions that drop a Basis Theory iframe into a container element on your page. The iframe owns the card data — the PAN never reaches your origin — and the SDK exposes a small `ElementHandle` you can use to focus, clear, observe validation, and tokenize.

Reach for Elements when you need to render the form yourself (custom layout, custom submit button, custom branding) but still want PCI-isolated inputs. If you'd rather not paint the form at all, use [Embedded Checkout](./embedded-checkout) instead.

Elements were added in `@easylabs/browser` `0.2.0`. They are the vanilla equivalents of the React components in `@easylabs/react` (`<CardNumberElement>`, `<CardExpirationDateElement>`, `<CardVerificationCodeElement>`, `<TextElement>`) — same option names, same lifecycle, just imperative.

## Available elements [#available-elements]

| Function                                             | Mounts                                                                                                              | React equivalent                |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `mountCardNumberElement(target, options?)`           | A card-number input. Surfaces `brand` on `change`.                                                                  | `<CardNumberElement>`           |
| `mountCardExpirationDateElement(target, options?)`   | An `MM / YY` expiration input.                                                                                      | `<CardExpirationDateElement>`   |
| `mountCardVerificationCodeElement(target, options?)` | A CVC input. Pass the brand from the card-number element to validate length (Amex = 4 digits, everything else = 3). | `<CardVerificationCodeElement>` |
| `mountTextElement(target, options?)`                 | A generic text input — ACH routing/account numbers, OTPs, anything else you want to keep off your origin.           | `<TextElement>`                 |

All four return the same `ElementHandle` shape.

## Quick example [#quick-example]

```ts
import {
  createEasyClient,
  mountCardNumberElement,
  mountCardExpirationDateElement,
  mountCardVerificationCodeElement,
  tokenize,
} from "@easylabs/browser";

// Validates the key and bootstraps the underlying Basis Theory client.
await createEasyClient({ apiKey: "sk_test_..." });

const cardNumber = mountCardNumberElement("#card-number", {
  placeholder: "1234 5678 9012 3456",
  classes: { focus: "is-focused", complete: "is-complete", invalid: "is-invalid" },
});
const cardExpiration = mountCardExpirationDateElement("#card-exp", {
  placeholder: "MM / YY",
});
const cardCvc = mountCardVerificationCodeElement("#card-cvc", {
  placeholder: "CVC",
});

document.getElementById("pay")!.addEventListener("click", async () => {
  const token = await tokenize({ cardNumber, cardExpiration, cardCvc });
  // token: { id: string, type: "card", fingerprint: string }
  // Forward token.id to your backend to create a payment instrument.
});
```

The matching markup:

```html
<div id="card-number"></div>
<div id="card-exp"></div>
<div id="card-cvc"></div>
<button id="pay" type="button">Pay</button>
```

## Mount options [#mount-options]

All four element factories accept the same `ElementOptions` shape. `mountCardVerificationCodeElement` and `mountTextElement` add a few extra fields (documented below).

| Option        | Type                                                      | Description                                                                                                                                                          |
| ------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placeholder` | `string`                                                  | Placeholder shown inside the iframe input.                                                                                                                           |
| `disabled`    | `boolean`                                                 | Disable user input.                                                                                                                                                  |
| `style`       | `Partial<CSSStyleDeclaration>`                            | Inline styles applied to the wrapper element around the iframe.                                                                                                      |
| `className`   | `string`                                                  | className applied to the wrapper element.                                                                                                                            |
| `classes`     | `{ focus?: string; complete?: string; invalid?: string }` | Class names applied to the wrapper when the underlying iframe reports the matching state. Lets you style focus/complete/invalid the same way Stripe.js users expect. |

`mountCardVerificationCodeElement` adds:

| Option      | Type                                                          | Description                                                                                     |
| ----------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `cardBrand` | `'visa' \| 'mastercard' \| 'amex' \| 'discover' \| 'unknown'` | Brand from the card-number element. Drives CVC length validation (Amex = 4 digits, others = 3). |

`mountTextElement` adds:

| Option      | Type                         | Description                                                             |
| ----------- | ---------------------------- | ----------------------------------------------------------------------- |
| `mask`      | `string`                     | Input mask, e.g. `"### ### ####"`. Formats the value as the user types. |
| `transform` | `'uppercase' \| 'lowercase'` | Auto-transform input before tokenisation.                               |

## The `ElementHandle` [#the-elementhandle]

Every `mount*` returns the same shape:

```ts
interface ElementHandle {
  /** Tear down the iframe and stop emitting events. */
  unmount(): void;
  /** Move focus into the iframe. */
  focus(): void;
  /** Remove focus from the iframe. */
  blur(): void;
  /** Reset the element to an empty state. */
  clear(): void;
  /** Subscribe to an element event. */
  on<E extends ElementEventName>(event: E, cb: ElementEvents[E]): void;
  /** Unsubscribe a previously-registered listener. */
  off<E extends ElementEventName>(event: E, cb: ElementEvents[E]): void;
  /** Snapshot the current validation/completion state. */
  getState(): ElementState;
}
```

`focus`, `blur`, and `clear` are safe to call before the iframe finishes its async mount — calls are queued and applied as soon as the iframe is ready.

## Events [#events]

```ts
type ElementEvents = {
  ready: () => void;
  change: (state: ElementState) => void;
  focus: () => void;
  blur: () => void;
  error: (err: Error) => void;
};

type ElementState = {
  empty: boolean;
  complete: boolean;
  errorMessage?: string;
  /** Card-number element only. */
  brand?: 'visa' | 'mastercard' | 'amex' | 'discover' | 'unknown';
};
```

The `change` event fires whenever the iframe reports a state transition. Card-number elements additionally surface `brand` so you can render a card-network logo or pass it into `mountCardVerificationCodeElement` for length validation:

```ts
const cardNumber = mountCardNumberElement("#card-number");
cardNumber.on("change", (state) => {
  console.log("brand:", state.brand);  // "visa" | "mastercard" | …
  console.log("complete:", state.complete);
});
```

Listener errors are caught and re-emitted through the `error` channel so a single broken handler doesn't break siblings.

## Styling [#styling]

The wrapper around the iframe is a plain `<div>` you control via `style`, `className`, and `classes`. The iframe inside that wrapper is opaque — Basis Theory owns the rendered input.

The Stripe-like state classes give you the most leverage. The example below paints a focus ring, a green border on completion, and a red border on invalid input:

```ts
const cardNumber = mountCardNumberElement("#card-number", {
  className: "el-host",
  classes: {
    focus: "is-focused",
    complete: "is-complete",
    invalid: "is-invalid",
  },
});
```

```css
.el-host {
  border: 1px solid #d8d8df;
  border-radius: 8px;
  padding: 0.625rem 0.75rem;
  height: 44px;
  background: white;
}
.el-host.is-focused { border-color: #2563eb; box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.08); }
.el-host.is-complete { border-color: #16a34a; }
.el-host.is-invalid { border-color: #dc2626; }
```

{/* TODO: Document the in-iframe text styling surface (font, color, placeholder color) once Basis Theory's `style` injection is exposed through `ElementOptions.style`. */}

## Tokenization [#tokenization]

Once your three card elements are mounted, call `tokenize` to exchange them for a Basis Theory token reference:

```ts
import { tokenize } from "@easylabs/browser";

const token = await tokenize({ cardNumber, cardExpiration, cardCvc });
// token.id         — pass to createPaymentInstrument or include in a session
// token.type       — "card"
// token.fingerprint — stable identifier for dedup / fraud checks
```

`tokenize` rejects with an explanatory error if any element is not yet mounted. Wait for `ready` before exposing the submit button, or simply gate the click handler on `getState().complete` for all three.

Forward `token.id` to your backend to create a payment instrument:

```ts
// server.ts
const { data: instrument } = await easy.createPaymentInstrument({
  type: "PAYMENT_CARD",
  identityId: customerId,
  tokenId: token.id,
});
```

## Cleanup [#cleanup]

Each element creates an iframe and a small bag of `postMessage` listeners. Call `handle.unmount()` on route change / component teardown:

```ts
const cardNumber = mountCardNumberElement("#card-number");
// later …
cardNumber.unmount();
```

Forgetting to unmount leaks the iframe and its listeners. In a long-lived SPA that mounts the form repeatedly, this matters.

## Bootstrap order [#bootstrap-order]

Element factories require an initialised Basis Theory client. The recommended bootstrap is:

1. `await createEasyClient({ apiKey })` — validates the key and stamps the API URL onto a window-level global.
2. Call any number of `mount*Element(...)` factories.

If you'd rather skip `createEasyClient` (for example, you only need Elements + tokenize and you don't want the typed `EasyApiClient` surface), you can configure the underlying client directly:

```ts
import { configureBasisTheoryFromKey } from "@easylabs/browser";

configureBasisTheoryFromKey("sk_test_...", "https://api.itseasy.co");
```

Calling a `mount*` factory before either bootstrap path will surface an `error` event explaining the missing client.


# Embedded Checkout (/docs/sdks/javascript/embedded-checkout)



Embedded Checkout renders Easy Labs' hosted checkout page inside an iframe on your own domain. Card collection, validation, 3DS, and payment confirmation all happen inside the iframe — your page never touches the PAN, so you stay out of PCI scope. The iframe is loaded from `https://checkout.itseasy.co/embed` and authenticates against a short-lived `client_secret`.

Use it when you want a payment surface that just works and is themed by Easy Labs. If you need to fully control the UI of the form (custom card layout, custom buttons), you'll need a different integration path — embedded checkout is intentionally opinionated.

## Server: create a checkout session [#server-create-a-checkout-session]

Mint the session on your server using the secret API key. The response includes a `client_secret` that you forward to the browser:

```ts
// server.ts
import { createClient } from "@easylabs/node";

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

const { data } = await easy.createEmbeddedCheckoutSession({
  mode: "payment", // or "subscription"
  line_items: [{ price_id: "price_...", quantity: 1 }],
  customer_email: "buyer@example.com",
  success_url: "https://example.com/success",
  cancel_url: "https://example.com/cancel",
  payment_methods: ["card", "crypto"],
  metadata: { order_id: "ord_42" },
});

// data.client_secret — forward this to the browser.
// data.id, data.amount_total, data.currency, data.expires_at also available.
```

The same `createEmbeddedCheckoutSession` method exists on the browser client, but **never call it from the browser** — it requires your secret API key. Always create sessions server-side.

You also need to whitelist the parent origin (the domain hosting the iframe) in your embedded-checkout config:

```ts
await easy.updateEmbeddedCheckoutConfig({
  allowed_origins: ["https://checkout.acmecorp.com", "https://*.acmecorp.com"],
});
```

An empty `allowed_origins` array disables embedding entirely.

## Client: mount the iframe [#client-mount-the-iframe]

```ts
import { mountEmbeddedCheckout } from "@easylabs/browser";

const handle = mountEmbeddedCheckout("#checkout", {
  clientSecret,
  onReady: () => console.log("ready"),
  onCryptoConfirmed: (event) => console.log("crypto confirmed", event),
});
```

`mountEmbeddedCheckout(target, options)` accepts:

| Argument | Type                | Description                                                                                           |
| -------- | ------------------- | ----------------------------------------------------------------------------------------------------- |
| `target` | `Element \| string` | A DOM element or a CSS selector. If a selector matches no element, the function throws synchronously. |

### Options [#options]

| Option              | Type                           | Default                       | Description                                                                                                                                                         |
| ------------------- | ------------------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientSecret`      | `string`                       | required                      | Returned by `createEmbeddedCheckoutSession`. Never use the merchant API key here.                                                                                   |
| `minHeight`         | `string`                       | `"500px"`                     | Minimum iframe height before the checkout reports its actual size.                                                                                                  |
| `style`             | `Partial<CSSStyleDeclaration>` | `{}`                          | Inline style overrides applied to the iframe. Defaults (`width: 100%`, `border: none`, `colorScheme: normal`) are applied first, so any property you set wins.      |
| `className`         | `string`                       | —                             | className applied to the iframe element.                                                                                                                            |
| `onReady`           | `() => void`                   | —                             | Fired when the iframe completes its initial postMessage handshake.                                                                                                  |
| `onCryptoConfirmed` | `(data: unknown) => void`      | —                             | Fired when the checkout reports a crypto payment as confirmed. Forwarded as-received; see the `checkout.session.crypto_confirmed` webhook for the canonical schema. |
| `__checkoutUrl`     | `string`                       | `https://checkout.itseasy.co` | **Internal.** Override the checkout origin for development. Public consumers should leave this unset.                                                               |

### Return value: `EmbeddedCheckoutHandle` [#return-value-embeddedcheckouthandle]

```ts
interface EmbeddedCheckoutHandle {
  /** Re-initialize the iframe with a new client_secret. */
  update(clientSecret: string): void;
  /** Remove the iframe and stop listening for postMessage events. */
  unmount(): void;
  /** The underlying <iframe> element, exposed for advanced layout. */
  readonly iframe: HTMLIFrameElement;
}
```

`update()` is safe to call before the iframe has signalled ready — the new secret will be sent as soon as the handshake completes.

## Events [#events]

Communication between your page and the iframe runs over `postMessage`. The SDK only accepts messages whose `event.origin` matches the resolved checkout origin and whose `event.source` is the iframe's `contentWindow`. Three message types are recognised:

| Message `type`              | Direction       | Effect                                                                                                                                        |
| --------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `easylabs:ready`            | iframe → parent | Marks the iframe as initialized. Triggers `onReady` and the initial `easylabs:init` send (or re-send if `clientSecret` changed via `update`). |
| `easylabs:resize`           | iframe → parent | Sets `iframe.style.height = "<height>px"`. Lets the iframe grow with its content.                                                             |
| `easylabs:crypto_confirmed` | iframe → parent | Triggers `onCryptoConfirmed(event.data)`.                                                                                                     |
| `easylabs:init`             | parent → iframe | Sent automatically on `ready` and on `update`. Carries `{ clientSecret }`.                                                                    |

Card-payment success is communicated via the iframe redirecting itself to your `success_url` — there's no `onCardConfirmed` event because the iframe leaves the page on success.

For server-side reactions (fulfillment, receipts, accounting), listen for the `checkout.session.completed` webhook. Don't trust client events as the source of truth.

## Cleanup [#cleanup]

`mountEmbeddedCheckout` registers a `message` listener on `window` and inserts an `<iframe>` into the DOM. Call `handle.unmount()` when navigating away to remove both:

```ts
const handle = mountEmbeddedCheckout("#checkout", { clientSecret });

// later — e.g. on route change in your SPA:
handle.unmount();
```

Forgetting to unmount leaks one listener per mount. In a long-lived SPA that mounts checkout repeatedly, this matters.

## Customization [#customization]

Customization is intentionally narrow. You control:

* **Layout** — the size and position of the iframe in your page (via `style`, `className`, `minHeight`, or by reading `handle.iframe`).
* **Branding inside the iframe** — `merchant.name`, `merchant.logo`, and `merchant.primary_color` are configured per-merchant in the dashboard and applied automatically.
* **Payment methods** — `payment_methods: ["card", "crypto"]` on the session.
* **Locale / currency** — driven by the session's `currency` and the buyer's browser.

You **cannot** restyle the form fields themselves, change the field order, or swap the submit button — those are part of the hosted experience. If you need that level of control, talk to us about alternative integration paths.


# JavaScript SDK (/docs/sdks/javascript)



`@easylabs/browser` is the official Easy Labs SDK for JavaScript.

It is a framework-agnostic vanilla-JS client. Use it from Vue, Svelte, Angular, Solid, HTMX, plain HTML, or anywhere else you ship JavaScript to a browser. Every method on the typed `EasyApiClient` is available — list customers, create payment links, manage subscriptions, query treasury — and on top of that the package ships three browser-only payment surfaces:

* **Embedded Checkout** — `mountEmbeddedCheckout`, the drop-in iframe for the hosted Easy Checkout experience.
* **Elements** — `mountCardNumberElement`, `mountCardExpirationDateElement`, `mountCardVerificationCodeElement`, and `mountTextElement` for building custom card forms with iframed PCI-isolated inputs, plus `tokenize` to convert them into a token reference.
* **Wallets** — `createApplePayButton` and `createGooglePayButton` for native wallet checkout.

Pick whichever fits the integration: hosted iframe when you want zero PCI scope and zero design work, Elements when you want to render your own form, wallets when you want the buyer's device to drive payment.

If you're on React, install [`@easylabs/react`](https://www.npmjs.com/package/@easylabs/react) instead — it wraps this same client surface in components and hooks. For server-side code (Node, Bun, edge runtimes), use [`@easylabs/node`](https://www.npmjs.com/package/@easylabs/node), which adds webhook signature verification.

## Quick links [#quick-links]



<Cards>
  <Card title="Installation" href="./installation" description="Add the SDK to your project." />

  <Card title="Quickstart" href="./quickstart" description="From zero to first payment in five minutes." />

  <Card title="Embedded Checkout" href="./embedded-checkout" description="Drop-in hosted checkout iframe." />

  <Card title="Elements" href="./elements" description="Iframed card fields and tokenization." />

  <Card title="Wallet Checkout" href="./wallet-checkout" description="Apple Pay and Google Pay buttons." />
</Cards>


# Installation (/docs/sdks/javascript/installation)



## Prerequisites [#prerequisites]

* A modern evergreen browser (the SDK uses `fetch`, `URL`, and `postMessage`; no polyfills bundled).
* A bundler that understands ES modules — Vite, Rollup, esbuild, webpack 5, or Parcel all work. The package is published as ESM with a CJS fallback.
* Node 22+ if you build the project locally (the package's `engines` field declares `>=22`).
* An Easy Labs API key. Sandbox keys are prefixed `sk_test_`; production keys are not. Get one from the [Easy Labs dashboard](https://app.itseasy.co).

## Install the package [#install-the-package]



<Tabs items="['npm', 'pnpm', 'yarn', 'bun']">
  <Tab value="npm">
    ```bash
    npm install @easylabs/browser
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @easylabs/browser
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @easylabs/browser
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @easylabs/browser
    ```
  </Tab>
</Tabs>

## Verify the install [#verify-the-install]

```ts
import { createEasyClient } from "@easylabs/browser";

const easy = await createEasyClient({ apiKey: "sk_test_..." });

// If the key is invalid, createEasyClient rejects before you reach this line.
const customers = await easy.getCustomers({ limit: 1 });
console.log(customers);
```

`createEasyClient` calls `GET /validate-key` against the Easy Labs API as part of construction, so a successful resolution is itself proof that the key, the network path, and the SDK are all wired up correctly.

## Next steps [#next-steps]

* [Quickstart](./quickstart) — render your first payment.
* [Client](./client) — the SDK's entry point.


# Quickstart (/docs/sdks/javascript/quickstart)



This walkthrough takes a one-line product on your server and turns it into a working hosted-checkout iframe in the browser. By the end you'll have collected a real (sandbox) payment.

You'll need two pieces of code: a tiny server endpoint that mints a checkout session, and a browser page that mounts the iframe.

`@easylabs/browser` `0.2.0` ships three payment surfaces — Embedded Checkout, [Elements](./elements), and [Wallet buttons](./wallet-checkout). This quickstart uses Embedded Checkout because it's the fastest path to a working payment. If you'd rather render your own card form, jump to the [Elements page](./elements); the bootstrap (steps 1 and 2 below) is identical.

## 1. Get your API keys [#1-get-your-api-keys]

Sign in to the [Easy Labs dashboard](https://app.itseasy.co) and copy your sandbox secret key — it starts with `sk_test_`. The browser SDK auto-detects sandbox vs. production from this prefix; no environment flags needed.

The key in this quickstart is a **server-side secret** and must never ship to the browser. We use it on a server endpoint to create the checkout session, then hand the resulting `client_secret` (a short-lived, single-use credential) to the browser.

## 2. Initialize the SDK [#2-initialize-the-sdk]

On your server (using `@easylabs/node` or any HTTP client), create a checkout session:

```ts
// server.ts
import { createClient } from "@easylabs/node";

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

app.post("/checkout/session", async (_req, res) => {
  const { data } = await easy.createEmbeddedCheckoutSession({
    mode: "payment",
    line_items: [{ price_id: "price_...", quantity: 1 }],
    success_url: "https://example.com/success",
    cancel_url: "https://example.com/cancel",
  });
  res.json({ clientSecret: data.client_secret });
});
```

In the browser, you don't need to construct an `EasyApiClient` at all for Embedded Checkout — the iframe authenticates against the short-lived `client_secret` your server just minted. Just import the mount helper directly:

```ts
// app.ts
import { mountEmbeddedCheckout } from "@easylabs/browser";
```

> **Never ship a secret key (`sk_test_…` / `sk_live_…`) to the browser.** Anything that runs in a browser tab is publicly readable. When the SDK eventually exposes publishable keys, those are the only Easy Labs keys safe for client-side use; until then, do all secret-key work on your server and hand the browser a `client_secret` (Embedded Checkout) or a Basis Theory token reference (Elements).
>
> You only need `createEasyClient` in the browser when you want the typed `EasyApiClient` surface for read-only utility flows — see [Client](./client) for the trade-offs.

## 3. Make your first call [#3-make-your-first-call]

Fetch the session from your server, then mount the iframe into a container element:

```ts
const res = await fetch("/checkout/session", { method: "POST" });
const { clientSecret } = await res.json();

const handle = mountEmbeddedCheckout("#checkout", {
  clientSecret,
  onReady: () => console.log("checkout ready"),
  onCryptoConfirmed: (event) => console.log("crypto confirmed", event),
});
```

Drop a target into your HTML:

```html
<div id="checkout" style="max-width: 480px; margin: 0 auto;"></div>
```

## 4. Handle the response [#4-handle-the-response]

The iframe handles card entry, validation, 3DS, and confirmation internally. When the customer pays, Easy Labs redirects the iframe to your `success_url` (or `cancel_url`). For crypto payments specifically, the SDK also fires `onCryptoConfirmed` so you can react in-page without a redirect round-trip.

For everything else — fulfillment, receipts, downstream automations — listen for the `checkout.session.completed` webhook on your server. The browser is never the source of truth for "payment succeeded".

If `createEasyClient` throws, the API key is invalid or the network is unreachable. If `mountEmbeddedCheckout` throws synchronously, the selector or element you passed couldn't be resolved. Errors that come back from API calls on the client are instances of `EasyApiError` — check `err.status` and `err.code` to branch on them.

```ts
import { EasyApiError } from "@easylabs/browser";

try {
  await easy.getCustomer("cus_does_not_exist");
} catch (err) {
  if (err instanceof EasyApiError && err.status === 404) {
    // not found
  } else {
    throw err;
  }
}
```

## What's next [#whats-next]

* [Embedded Checkout](./embedded-checkout) — the full option surface for `mountEmbeddedCheckout`.
* [Elements](./elements) — render your own card form with iframed PCI-isolated inputs and `tokenize`.
* [Wallet Checkout](./wallet-checkout) — drop-in Apple Pay and Google Pay buttons.
* [Client](./client) — every typed API method you can call from the browser.
* [Examples › Vanilla JS](./examples/vanilla) — a complete runnable example covering Embedded Checkout, Elements, and wallets.


# Wallet Checkout (/docs/sdks/javascript/wallet-checkout)



`@easylabs/browser` `0.2.0` ships standalone wallet button factories — `createApplePayButton` and `createGooglePayButton` — that you drop directly into your own form. Each factory renders the official wallet button into a container element, drives the wallet handshake, exchanges the wallet's payment token for an Easy Labs token reference on your server, and forwards the result to an `onTokenized` callback.

If you'd rather have wallet buttons rendered inside a hosted iframe, use [Embedded Checkout](./embedded-checkout) — wallet eligibility is detected automatically there.

## Apple Pay [#apple-pay]

```ts
import { createApplePayButton } from "@easylabs/browser";

const apple = createApplePayButton("#apple-pay", {
  merchantId: "merchant.co.itseasy.demo",
  total: { value: 1999, currency: "USD" },
  countryCode: "US",
  merchantSession: async (validationURL) => {
    // Apple requires server-side merchant validation against the
    // certificate tied to your merchant ID. POST to your own endpoint.
    const res = await fetch("/api/apple-pay/session", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ validationURL }),
    });
    return res.json();
  },
  onTokenized: (token) => {
    console.log("apple pay token:", token.id);
  },
  onError: (err) => console.error(err),
});

if (!apple.isAvailable) {
  document.querySelector("#apple-pay")!.innerHTML =
    "<p>Apple Pay not available in this browser.</p>";
}
```

The factory uses Apple's official `<apple-pay-button>` web component when available and falls back to a styled `<button>` otherwise. Load Apple's SDK script in your HTML so the web component is registered:

```html
<script
  crossorigin
  src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js"
></script>
```

### Options [#options]

| Option            | Type                                                 | Description                                                                                                                                                                                                                                                    |
| ----------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchantId`      | `string`                                             | Apple-issued merchant identifier (must match what's in the Easy Labs dashboard).                                                                                                                                                                               |
| `total`           | `{ value: number; currency: string }`                | Total to charge. `value` is in the smallest currency unit (cents for USD). `currency` is an ISO-4217 code.                                                                                                                                                     |
| `countryCode`     | `string`                                             | ISO-3166-1 alpha-2 country code of the merchant (e.g. `"US"`).                                                                                                                                                                                                 |
| `merchantSession` | `(validationURL: string) => Promise<unknown>`        | Server-side merchant-session callback. Receives Apple's `validationURL` and must return the merchant-session payload — typically by POSTing to your own backend, which calls Apple Pay's `paymentSession` endpoint with the certificate stored on your server. |
| `onTokenized`     | `(token: { id: string; type: "apple_pay" }) => void` | Fired with the Easy Labs token reference after successful authorisation.                                                                                                                                                                                       |
| `onError`         | `(err: Error) => void`                               | Fired on any failure during the wallet flow.                                                                                                                                                                                                                   |

### Returns [#returns]

```ts
interface WalletButtonHandle {
  /** Tear down the button and any wallet listeners. */
  unmount(): void;
  /** True when Apple Pay is available on this device/browser. */
  readonly isAvailable: boolean;
}
```

`isAvailable` is computed synchronously from `window.ApplePaySession?.canMakePayments?.()`. Hide the button slot when it's `false` rather than rendering a non-functional affordance.

## Google Pay [#google-pay]

```ts
import { createGooglePayButton } from "@easylabs/browser";

const google = createGooglePayButton("#google-pay", {
  merchantId: "TEST_MERCHANT_ID",
  gatewayMerchantId: "easylabs_demo",
  total: { value: 1999, currency: "USD" },
  countryCode: "US",
  onTokenized: (token) => {
    console.log("google pay token:", token.id);
  },
  onError: (err) => console.error(err),
});
```

Load Google's PaymentsClient script in your HTML:

```html
<script src="https://pay.google.com/gp/p/js/pay.js"></script>
```

### Options [#options-1]

| Option              | Type                                                  | Description                                                                                                                                   |
| ------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchantId`        | `string`                                              | Google-issued merchant identifier (set up in Google Pay Console).                                                                             |
| `gatewayMerchantId` | `string`                                              | Gateway merchant ID — Easy Labs assigns this in the dashboard.                                                                                |
| `total`             | `{ value: number; currency: string }`                 | Total to charge. `value` is in the smallest currency unit.                                                                                    |
| `countryCode`       | `string`                                              | ISO-3166-1 alpha-2 country code (e.g. `"US"`).                                                                                                |
| `environment`       | `'TEST' \| 'PRODUCTION'`                              | Defaults to `PRODUCTION`. The factory infers `TEST` when `merchantId` starts with `TEST_` (Google's convention). Pass explicitly to override. |
| `onTokenized`       | `(token: { id: string; type: "google_pay" }) => void` | Fired with the Easy Labs token reference after successful authorisation.                                                                      |
| `onError`           | `(err: Error) => void`                                | Fired on any failure during the wallet flow.                                                                                                  |

### Returns [#returns-1]

The same `WalletButtonHandle` shape as Apple Pay. Note that `isAvailable` for Google Pay flips `true` **asynchronously** after `isReadyToPay` resolves — the container is empty until then. If you want to render a "Google Pay not available" fallback, do it on a short timer:

```ts
setTimeout(() => {
  if (!google.isAvailable) {
    document.querySelector("#google-pay")!.innerHTML =
      "<p>Google Pay not available in this browser.</p>";
  }
}, 1000);
```

## Handling the result [#handling-the-result]

Both `onTokenized` callbacks receive an `{ id, type }` shape. The `id` is the Easy Labs token reference — forward it to your backend to create a payment instrument or include it in a downstream API call:

```ts
onTokenized: async (token) => {
  await fetch("/api/checkout/wallet", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ tokenId: token.id, type: token.type }),
  });
}
```

Don't trust the browser as the source of truth. Confirm the payment server-side and listen for the `checkout.session.completed` webhook for fulfilment.

## Cleanup [#cleanup]

Both factories return a `WalletButtonHandle`. Call `unmount()` on route change / component teardown:

```ts
const apple = createApplePayButton("#apple-pay", { /* … */ });
// later …
apple.unmount();
```

## Setup notes [#setup-notes]

* **Apple Pay** requires (a) an Apple-issued merchant identifier, (b) a merchant identity certificate uploaded to your server, and (c) domain verification for every domain that hosts the button. Configure these in the Easy Labs dashboard. {/* TODO: Link to the dashboard onboarding doc that covers Apple Pay domain verification once it ships. */}
* **Google Pay** requires (a) a Google Pay Console merchant ID and (b) a gateway merchant ID assigned in the Easy Labs dashboard. {/* TODO: Link to the dashboard onboarding doc for Google Pay setup once it ships. */}
* Both buttons require HTTPS in production. Apple Pay refuses to render on `http://` origins outside `localhost`.


# MCP configuration (/docs/sdks/mcp/configuration)



## Environment variables [#environment-variables]

| Variable        | Required       | Default                  | Notes                                                                         |
| --------------- | -------------- | ------------------------ | ----------------------------------------------------------------------------- |
| `EASY_API_KEY`  | yes            | —                        | Easy Labs API key (sandbox or production)                                     |
| `EASY_API_URL`  | no             | `https://api.easy.co/v1` | Override the API base URL — needed only for self-hosted or custom deployments |
| `EASY_MCP_PORT` | no (HTTP only) | `3100`                   | Port the HTTP transport listens on                                            |

## Transports [#transports]

### Stdio (default) [#stdio-default]

The standard transport for local MCP clients (Claude Desktop, Cursor, Continue). The server reads JSON-RPC over stdin and writes responses to stdout.

```bash
npx -y @easylabs/mcp-server
```

### HTTP / SSE-compatible [#http--sse-compatible]

For remote or daemonized usage. Listens on `/mcp` at the configured port.

```bash
npx -y @easylabs/mcp-server -- --http
```

Custom port:

```bash
npx -y @easylabs/mcp-server -- --http --port=3200
```

The HTTP transport accepts `GET`, `POST`, and `DELETE` on the `/mcp` endpoint. Compatible with the SSE transport pattern most MCP clients support.

## Local development [#local-development]

Clone [`easy-mcp`](https://github.com/itseasyco/easy-mcp) and run from source:

```bash
git clone https://github.com/itseasyco/easy-mcp.git
cd easy-mcp
pnpm install
EASY_API_KEY=sk_test_... pnpm dev
```

## Logging [#logging]

The server writes status and error messages to **stderr** so they don't interfere with the JSON-RPC stream on stdout. Pipe stderr to your log collector of choice for production deployments.

## Sandbox vs production [#sandbox-vs-production]

The MCP server today reads `EASY_API_URL` as a single configurable base URL with no built-in sandbox/production split. Until the modernization adds a proper `EASY_ENV` env (see [project #3 in the modernization plan](https://github.com/itseasyco/easy-mcp/blob/main/docs/modernization-plan.md)), set the URL explicitly when targeting production:

```json
{
  "env": {
    "EASY_API_KEY": "sk_live_...",
    "EASY_API_URL": "https://api.easy.co/v1"
  }
}
```

Use a sandbox key (`sk_test_...`) for any agent that has write access — modernization Phase 2 will add write tools, and agents with prod credentials should be a deliberate opt-in.


# MCP Server (/docs/sdks/mcp)





The **Easy Labs MCP Server** lets AI agents — Claude Desktop, custom assistants, hosted agent platforms — read your Easy Labs data through structured tools and resources instead of raw HTTP calls. It speaks the [Model Context Protocol](https://modelcontextprotocol.io), an open standard for connecting LLMs to external systems.

```bash
npx -y @easylabs/mcp-server
```

## What it gives you [#what-it-gives-you]

<Cards>
  <Card title="Tools" href="/docs/sdks/mcp/tools" description="Read-only tools for transfers, disputes, settlements, customers, and balance transfers." />

  <Card title="Resources" href="/docs/sdks/mcp/resources" description="Merchant profile and summary surfaces for grounding context." />

  <Card title="Transports" href="/docs/sdks/mcp/configuration" description="Stdio (default, for local clients) and HTTP/SSE-compatible (for remote/daemonized usage)." />
</Cards>

## When to use the MCP server [#when-to-use-the-mcp-server]

* You want **Claude Desktop** (or any MCP-compatible client) to inspect your Easy Labs activity.
* You're building an **AI agent** that needs structured, validated payment data — not raw API responses.
* You need a **drop-in surface** for tool-calling LLMs without writing custom integrations per provider.

For server-to-server integrations, prefer [`@easylabs/node`](/docs/sdks/node) directly — it's the canonical SDK and has the full surface. The MCP server today exposes a subset of that surface, packaged for AI consumption.

## Quickstart [#quickstart]

<Cards>
  <Card title="Connect Claude Desktop" href="/docs/sdks/mcp/quickstart" description="Add the MCP server to claude_desktop_config.json in 60 seconds." />
</Cards>

## Roadmap [#roadmap]

The MCP server today is read-only and covers transfers / disputes / settlements / customers / balance-transfers. Modernization work tracked at [`easy-mcp` modernization plan](https://github.com/itseasyco/easy-mcp/blob/main/docs/modernization-plan.md) will:

* Expand coverage to the full `@easylabs/node` surface (subscriptions, invoices, payouts, recipients, embedded checkout, etc.)
* Add write tools with confirmation flows (`create_transfer`, `create_subscription`, `send_invoice`, etc.)
* Ship sandbox/production env splits matching the SDK
* Auto-generate tools from the OpenAPI spec so coverage stays in lockstep


# MCP quickstart (/docs/sdks/mcp/quickstart)



## 1. Get an API key [#1-get-an-api-key]

Grab an API key from the [Easy Labs dashboard](https://dashboard.easy.co). Use a sandbox key while you're testing; switch to production once you trust the wiring.

## 2. Add the server to Claude Desktop [#2-add-the-server-to-claude-desktop]

Open `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). Add an entry under `mcpServers`:

```json
{
  "mcpServers": {
    "easy-labs": {
      "command": "npx",
      "args": ["-y", "@easylabs/mcp-server"],
      "env": {
        "EASY_API_KEY": "your_easy_api_key"
      }
    }
  }
}
```

Restart Claude Desktop. The hammer icon in the chat input should now show **easy-labs** with its tools listed.

## 3. Try it [#3-try-it]

In a new Claude conversation:

> "Show me my last 10 transfers."

Claude calls `list_transfers`, formats the response, and shows it to you. No HTTP, no raw JSON, no glue code.

## Configuration [#configuration]

The defaults work for most setups. To customize:

```json
{
  "mcpServers": {
    "easy-labs": {
      "command": "npx",
      "args": ["-y", "@easylabs/mcp-server"],
      "env": {
        "EASY_API_KEY": "your_easy_api_key",
        "EASY_API_URL": "https://api.easy.co/v1"
      }
    }
  }
}
```

See [Configuration](/docs/sdks/mcp/configuration) for HTTP transport, custom ports, and the full env reference.

## Other MCP clients [#other-mcp-clients]

The same server works with any MCP-compatible client (Cursor, Continue, custom agents). Point your client at `npx -y @easylabs/mcp-server` over stdio, or run the HTTP transport and connect to `http://127.0.0.1:3100/mcp`.


# MCP resources (/docs/sdks/mcp/resources)



In MCP, **resources** are passive context the agent can read at any time — distinct from tools, which the agent invokes to do something. The Easy Labs MCP server exposes two:

## `easy://merchant/profile` [#easymerchantprofile]

Your merchant profile: business name, legal name, primary email, website, account status, creation date.

Read by an agent when it needs to ground responses in *who* the merchant is — useful for personalizing summaries or surfacing the right account context across long conversations.

## `easy://merchant/summary` [#easymerchantsummary]

A rolled-up snapshot of the merchant's recent activity — totals, counts, status flags. Good for quick orientation ("what's been happening this month?") without forcing the agent to walk every list endpoint.

## How agents use resources [#how-agents-use-resources]

MCP-compatible clients typically expose resources as references the user (or the agent) can attach to a conversation. In Claude Desktop, resources show up under the same hammer icon as tools and can be pinned for the duration of a session.

## What's missing [#whats-missing]

Resource surface is intentionally narrow today. The [modernization plan](https://github.com/itseasyco/easy-mcp/blob/main/docs/modernization-plan.md) keeps it that way — most of the leverage is in expanded **tools**, not more resources. If you have a use case that argues for new resources, open an issue against [`easy-mcp`](https://github.com/itseasyco/easy-mcp).


# MCP tools (/docs/sdks/mcp/tools)



The MCP server registers ten read-only tools today. Each tool returns a human-readable summary plus the raw entity payload — formatted for LLM consumption (currency formatted, dates ISO-normalized, statuses spelled out).

> Write operations (creating transfers, sending invoices, scheduling payouts) are **not** exposed yet — see the [modernization roadmap](https://github.com/itseasyco/easy-mcp/blob/main/docs/modernization-plan.md) for Phase 2.

## Transfers [#transfers]

### `list_transfers` [#list_transfers]

List recent transfers with optional pagination and status filter.

| Input    | Type    | Notes                                 |
| -------- | ------- | ------------------------------------- |
| `limit`  | integer | Default 25, max 100                   |
| `offset` | integer | Pagination cursor                     |
| `status` | string  | e.g. `succeeded`, `failed`, `pending` |

### `get_transfer` [#get_transfer]

Retrieve a single transfer by ID.

| Input | Type   | Notes       |
| ----- | ------ | ----------- |
| `id`  | string | Transfer ID |

## Disputes [#disputes]

### `list_disputes` [#list_disputes]

List disputes filed against your transfers.

| Input    | Type    | Notes                      |
| -------- | ------- | -------------------------- |
| `limit`  | integer | Default 25, max 100        |
| `offset` | integer | Pagination cursor          |
| `state`  | string  | e.g. `open`, `won`, `lost` |

### `get_dispute` [#get_dispute]

Retrieve a single dispute by ID.

| Input | Type   | Notes      |
| ----- | ------ | ---------- |
| `id`  | string | Dispute ID |

## Settlements [#settlements]

### `list_settlements` [#list_settlements]

List settlement batches with their totals and status.

| Input    | Type    | Notes               |
| -------- | ------- | ------------------- |
| `limit`  | integer | Default 25, max 100 |
| `offset` | integer | Pagination cursor   |

### `get_settlement` [#get_settlement]

Retrieve a single settlement by ID.

| Input | Type   | Notes         |
| ----- | ------ | ------------- |
| `id`  | string | Settlement ID |

## Customers [#customers]

### `list_customers` [#list_customers]

List customers, newest first.

| Input    | Type    | Notes               |
| -------- | ------- | ------------------- |
| `limit`  | integer | Default 25, max 100 |
| `offset` | integer | Pagination cursor   |

### `get_customer` [#get_customer]

Retrieve a single customer by ID.

| Input | Type   | Notes       |
| ----- | ------ | ----------- |
| `id`  | string | Customer ID |

## Balance transfers [#balance-transfers]

### `list_balance_transfers` [#list_balance_transfers]

List balance transfers (payouts to your bank).

| Input    | Type    | Notes               |
| -------- | ------- | ------------------- |
| `limit`  | integer | Default 25, max 100 |
| `offset` | integer | Pagination cursor   |

### `get_balance_transfer` [#get_balance_transfer]

Retrieve a single balance transfer by ID.

| Input | Type   | Notes               |
| ----- | ------ | ------------------- |
| `id`  | string | Balance transfer ID |

## What's missing [#whats-missing]

The MCP server today does not yet expose:

* **Payments**: payment instruments, orders, refunds, sessions, hosted/embedded checkout, payment links, authorizations
* **Billing**: subscriptions, products, prices, invoices, coupons, customer portal, dunning
* **Treasury beyond settlements**: payouts, recipients, bank-account management, payout links, auto-transfer rules, W-9 / tax documents
* **Account & operations**: branding, custom domains, webhooks management, files, security rules
* **Write tools**: every tool today is read-only

Tracked in the [`easy-mcp` modernization plan](https://github.com/itseasyco/easy-mcp/blob/main/docs/modernization-plan.md) — Project 2 (auto-generate tools from OpenAPI) will close this gap to \~112 tools matching the SDK surface.


# Authentication (/docs/sdks/node/authentication)



`@easylabs/node` authenticates with a single secret API key. The SDK attaches it to every outbound request as the `x-easy-api-key` header. There is no JWT flow, no OAuth, and no per-request key — `createClient` takes the key once and the resolved client carries it for its lifetime.

Keep keys server-side. `@easylabs/node` is a server-side package — `createClient` performs a startup `GET /validate-key` against your secret API key, so it must never run in a browser bundle. Two methods on the client (`validateEmbeddedCheckoutSession` and `confirmEmbeddedCheckoutSession`) authenticate with the embedded session's `client_secret` instead of the API key and have the `x-easy-api-key` header suppressed automatically — but you still call them from server code, then forward the result to the iframe over your own endpoint. If you want the iframe to talk straight to the Easy API, hit `POST /embedded-checkout/validate` and `POST /embedded-checkout/confirm` with `fetch` — the SDK isn't in that path.

## Initializing with an API key [#initializing-with-an-api-key]

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

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

The SDK picks the API base URL from the key prefix:

| Key prefix    | Environment | Base URL                                |
| ------------- | ----------- | --------------------------------------- |
| `sk_test_…`   | Sandbox     | `https://sandbox-api.itseasy.co/v1/api` |
| anything else | Live        | `https://api.itseasy.co/v1/api`         |

`createClient` calls `GET /validate-key` before returning, so a missing or revoked key throws synchronously at startup rather than later from a real request.

## Rotating keys [#rotating-keys]

The SDK doesn't hot-swap keys — `createClient` resolves once. To rotate without downtime:

1. Generate a new key in the dashboard.
2. Roll your deployment with the new value in `EASY_API_KEY`. New processes pick up the new key on next `createClient` call.
3. Once the old fleet has drained, revoke the previous key from the dashboard.

If you need to swap keys at runtime (rare — usually only in tests), discard the old client object and call `createClient` again.

## Multi-tenant authentication [#multi-tenant-authentication]

For platforms that act on behalf of multiple merchants, each merchant has its own API key. Keep one client per merchant and cache it for the lifetime of the request, the worker, or — if memory allows — the process:

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

const cache = new Map<string, ReturnType<typeof createClient>>();

export function clientFor(merchantId: string, apiKey: string) {
  let pending = cache.get(merchantId);
  if (!pending) {
    pending = createClient({ apiKey }).catch((err) => {
      // A rejected promise would otherwise poison the cache forever —
      // evict so the next call re-runs key validation.
      cache.delete(merchantId);
      throw err;
    });
    cache.set(merchantId, pending);
  }
  return pending; // Promise<EasyClient>
}
```

Because `createClient` validates the key on construction, the `.catch` above evicts the entry on a transient validation failure (network blip, brief 5xx) so a single bad startup doesn't permanently lock the merchant out. If you also want to evict when a *later* request returns 401, drop the entry from `cache` in your own error handler.

The `__internal_api_url` option exists only for internal Easy Labs testing and is intentionally undocumented in the public API surface — production code should never set it.


# Error handling (/docs/sdks/node/error-handling)



Every non-2xx response is thrown as a single class:

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

class EasyApiError extends Error {
  readonly status: number;
  readonly code: string | null;
  readonly details: unknown;
  readonly retryAfterSeconds: number | null;
  readonly raw: unknown;
}
```

* `status` — HTTP status from the response.
* `code` — short machine-readable code from the API error body (e.g. `RATE_LIMITED`, `VALIDATION_ERROR`), or `null` when the body wasn't a structured error.
* `details` — arbitrary structured payload from the API (e.g. field-level validation errors).
* `retryAfterSeconds` — parsed from the `Retry-After` response header, or `null`.
* `raw` — the original parsed JSON body for forensic logging.

`message` always begins with `API request failed: …` for backwards compatibility with code that previously matched against a plain `Error`.

## Retryable vs. non-retryable [#retryable-vs-non-retryable]

| Status    | Class                      | Retry? | Notes                                                                 |
| --------- | -------------------------- | ------ | --------------------------------------------------------------------- |
| 400 / 422 | `EasyApiError`             | No     | Validation. Surface `err.details` to the user.                        |
| 401 / 403 | `EasyApiError`             | No     | Bad / revoked key. Stop retrying and rotate.                          |
| 404       | `EasyApiError`             | No     | Not found.                                                            |
| 409       | `EasyApiError`             | No     | Conflict — usually a duplicate idempotency key with a different body. |
| 429       | `EasyApiError`             | Yes    | Honour `err.retryAfterSeconds` before retrying.                       |
| 5xx       | `EasyApiError`             | Yes    | Transient — back off and retry.                                       |
| Network   | `TypeError` (from `fetch`) | Yes    | Timeouts, DNS, TLS — wrap with your own retry.                        |

```ts
async function withRetry<T>(fn: () => Promise<T>, max = 3): Promise<T> {
  for (let attempt = 1; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const retriable =
        (err instanceof EasyApiError && (err.status === 429 || err.status >= 500)) ||
        err instanceof TypeError;
      if (!retriable || attempt >= max) throw err;
      const delay =
        err instanceof EasyApiError && err.retryAfterSeconds
          ? err.retryAfterSeconds * 1000
          : 250 * 2 ** (attempt - 1);
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}
```

## Idempotency keys [#idempotency-keys]

A few create endpoints accept an `idempotency_key` (or similar) inside the request body — most notably `reportSubscriptionUsage` and `payInvoice`. Pass a stable UUID per logical operation so retries safely deduplicate on the server:

```ts
import { randomUUID } from "node:crypto";

await easy.payInvoice("inv_123", {
  instrument_id: "PI_...",
  idempotency_key: randomUUID(),
});
```

The 0.1 SDK does not yet send a top-level idempotency header on every POST; if you need at-least-once safety on endpoints that don't accept a body-level key, deduplicate at the application layer.

## Network errors [#network-errors]

The SDK is built on the platform `fetch`. Connection failures (timeouts, DNS, TLS) propagate as Node's `TypeError("fetch failed")` with a populated `cause`. They are not wrapped in `EasyApiError` because no HTTP exchange completed — branch on `err instanceof EasyApiError` first, and treat anything else as a transport-level failure to retry or surface separately.


# Node.js SDK (/docs/sdks/node)



`@easylabs/node` is the official Easy Labs SDK for Node.js. It wraps the Easy Labs REST API in a single `createClient({ apiKey })` factory, exposes a typed method for every endpoint — customers, payment instruments, transfers, refunds, orders, checkout, embedded checkout, products and prices, subscriptions, coupons and promotion codes, invoices, dunning, treasury, settlements, disputes, authorizations, compliance forms, webhooks, and analytics — and ships an `EasyWebhooks.constructEvent` helper for verifying inbound webhook deliveries.

The SDK is server-only: it sends your secret API key on every request as `x-easy-api-key` and is designed to be initialized once per process (typically inside a framework plugin or a module-level singleton). It targets Node.js 22+, ships dual ESM + CJS bundles, and re-exports every request/response type from `@easylabs/common` so you can `import type { CreateCustomer, SubscriptionData } from "@easylabs/node"` without reaching into a separate package.

## Quick links [#quick-links]



<Cards>
  <Card title="Installation" href="./installation" description="Add the SDK to your project." />

  <Card title="Quickstart" href="./quickstart" description="From zero to first payment in five minutes." />

  <Card title="Webhooks" href="./webhooks" description="Verify and react to platform events." />
</Cards>


# Installation (/docs/sdks/node/installation)



## Prerequisites [#prerequisites]

* **Node.js 22 or newer.** The SDK relies on the platform `fetch`, `FormData`, and `crypto.timingSafeEqual` and is published as `"engines": { "node": ">=22" }`.
* **An API key.** Sandbox keys are prefixed `sk_test_` and route automatically to `https://sandbox-api.itseasy.co/v1/api`; live keys (any other prefix) route to `https://api.itseasy.co/v1/api`. Never expose either key to the browser.
* **TypeScript 5+** if you want types — the package ships `.d.ts` and `.d.cts` declarations side-by-side with the JS bundles.

## Install the package [#install-the-package]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @easylabs/node
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @easylabs/node
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @easylabs/node
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @easylabs/node
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Verify the install [#verify-the-install]

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

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

const customers = await easy.getCustomers({ limit: 1 });
console.log(`Connected. ${customers.data.length} customer(s) returned.`);
```

`createClient` validates the API key against `/validate-key` before returning, so a bad key fails fast at startup rather than on the first request.

## Next steps [#next-steps]

* [Quickstart](./quickstart) — render your first payment.
* [Authentication](./authentication) — key handling, multi-tenant patterns.
* [Webhooks](./webhooks) — verify inbound deliveries.


# Pagination (/docs/sdks/node/pagination)



Easy Labs list endpoints use **offset/limit pagination**. Every method that returns a collection accepts an optional `PaginationParams` object:

```ts
type PaginationParams = {
  limit?: number;
  offset?: number;
  ids?: string[];
};
```

`limit` caps the page size, `offset` skips that many records, and `ids` is a server-side filter that returns only the resources whose IDs match (useful for batch reads — the SDK joins them with commas and sends them as the `ids` query parameter).

The API does not return a `next` cursor. Walk pages by incrementing `offset` until the response is shorter than `limit`.

## Manual pagination [#manual-pagination]

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

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

const pageSize = 100;
let offset = 0;
const all: Awaited<ReturnType<typeof easy.getCustomers>>["data"] = [];

while (true) {
  const page = await easy.getCustomers({ limit: pageSize, offset });
  all.push(...page.data);
  if (page.data.length < pageSize) break;
  offset += pageSize;
}
```

A few endpoints wrap the rows in a paginated envelope instead of returning a bare array. The shape varies by endpoint — the rows live under a *named* key, not always `data`:

| Method                     | Envelope (under `response.data`)                                                                        |
| -------------------------- | ------------------------------------------------------------------------------------------------------- |
| `getCustomerSubscriptions` | `{ data: SubscriptionData[], total, limit, offset }`                                                    |
| `listWebhookDeliveries`    | `{ deliveries: WebhookDelivery[], limit, offset, total, event_counts?, failed_count?, success_count? }` |
| `listEndpointDeliveries`   | `{ deliveries: WebhookDelivery[], limit, offset, total }`                                               |

Use `total` for an exact stop condition when present, and read the rows from the right key:

```ts
// Subscriptions — rows under `data`
const subs = await easy.getCustomerSubscriptions(customerId, { limit: 50, offset });
if (offset + subs.data.data.length >= subs.data.total) break;

// Webhook deliveries — rows under `deliveries`
const page = await easy.listWebhookDeliveries({ limit: 50, offset });
if (offset + page.data.deliveries.length >= page.data.total) break;
```

## Auto-pagination [#auto-pagination]

The 0.1 SDK does not ship an iterator helper. Wrap the manual loop above in an `async function*` if you want one:

```ts
async function* eachCustomer() {
  const limit = 100;
  let offset = 0;
  while (true) {
    const { data } = await easy.getCustomers({ limit, offset });
    if (!data.length) return;
    for (const c of data) yield c;
    if (data.length < limit) return;
    offset += limit;
  }
}

for await (const customer of eachCustomer()) {
  console.log(customer.id);
}
```

{/* TODO: ship a first-class auto-pagination helper in a future minor and link it here. */}


# Quickstart (/docs/sdks/node/quickstart)



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

## 1. Get your API keys [#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.

```bash
# .env.local
EASY_API_KEY=sk_test_...
```

## 2. Initialize the SDK [#2-initialize-the-sdk]

```ts
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 [#3-make-your-first-call]

```ts
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>`:

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

The resource you care about is always under `.data`.

## 4. Handle the response [#4-handle-the-response]

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

```ts
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 [#whats-next]

* [Customers](./resources/customers) and [Payment Instruments](./resources/payment-instruments) — the building blocks of every flow.
* [Checkout](./resources/checkout) for an all-in-one create-customer + charge call, or [Embedded Checkout](./resources/embedded-checkout) for a hosted iframe.
* [Subscriptions](./resources/subscriptions) for recurring billing with proration, pauses, discounts, and metered usage.
* [Webhooks](./webhooks) for reacting to platform events.


# TypeScript (/docs/sdks/node/typescript)



`@easylabs/node` is written in strict TypeScript and ships `.d.ts` (ESM) and `.d.cts` (CJS) declaration files. The types from `@easylabs/common` are re-exported from the entry point — you never need to add the common package to your dependencies directly.

## Public types [#public-types]

Every method on the client is fully typed; the most-reached-for shapes are listed here so you know what to import.

### Client + envelope [#client--envelope]

```ts
import type {
  ClientOptions,        // argument to createClient
  ApiResponse,          // every method returns ApiResponse<T>
  Paginated,            // { data, total, limit, offset } envelope
  PaginationParams,     // { limit?, offset?, ids? }
  EasyApiError,         // thrown on non-2xx
} from "@easylabs/node";
```

### Resource request types [#resource-request-types]

```ts
import type {
  CreateCustomer,
  UpdatePaymentInstrument,
  CreatePaymentInstrument,
  CreateTransfer,
  CreatePaymentLinkPayload,
  UpdatePaymentLinkPayload,
  CreateCheckoutSession,
  CreateProduct,
  CreatePrice,
  CreateSubscription,
  UpdateSubscription,
  ApplySubscriptionDiscount,
  CreateOneTimeCharge,
  ProrationPreviewParams,
  ReportSubscriptionUsage,
  CreateInvoice,
  UpdateInvoice,
  ListInvoicesQuery,
  PayInvoice,
  SendInvoice,
  CreateCoupon,
  UpdateCoupon,
  CreatePromotionCode,
  UpdatePromotionCode,
  ValidatePromotionCode,
  CreateEmbeddedCheckoutSession,
  UpdateEmbeddedCheckoutConfig,
  CreateWebhookEndpoint,
  UpdateWebhookEndpoint,
  AnalyticsQuery,
  DunningConfig,
  SignComplianceForm,
} from "@easylabs/node";
```

### Resource response types [#resource-response-types]

```ts
import type {
  CustomerData,
  PaymentInstrumentData,
  TransferData,
  OrderData,
  SubscriptionData,
  SubscriptionItem,
  SubscriptionDiscount,
  ProductData,
  PriceData,
  PaymentLinkData,
  InvoiceData,
  CouponData,
  PromotionCodeData,
  AuthorizationData,
  DisputeData,
  SettlementData,
  ComplianceFormData,
  WebhookEndpoint,
  RegisteredWebhookEndpoint,
  WebhookEvent,
  WebhookDelivery,
  EmbeddedCheckoutSessionData,
  EmbeddedCheckoutSessionStatus,
  EmbeddedCheckoutConfig,
} from "@easylabs/node";
```

### Webhooks [#webhooks]

`WebhookEvent<T>` is parameterized by the `data` payload of the event, so you can narrow with a type guard or a discriminated handler:

```ts
import type { WebhookEvent, SubscriptionData, OrderData } from "@easylabs/node";

function handle(event: WebhookEvent) {
  switch (event.type) {
    case "subscription.updated": {
      const e = event as WebhookEvent<SubscriptionData>;
      // e.data.status, e.data.items, ...
      break;
    }
    case "checkout.session.completed": {
      const e = event as WebhookEvent<OrderData>;
      // e.data.order_number, e.data.identity, ...
      break;
    }
  }
}
```

The full set of event names is exported as `EASY_EVENT_TYPES` (a `readonly` tuple) and the union is `EasyEventType`.

## Module augmentation [#module-augmentation]

The SDK does not currently expose declaration-merging hooks. If you need to attach app-level metadata, use the `tags` / `metadata` fields that most resources carry — both are typed as `Record<string, unknown>`, so you can introduce a stricter interface in your own code and cast at the boundary:

```ts
interface OrderTags {
  internal_order_id: string;
  fulfillment_state: "pending" | "shipped" | "delivered";
}

await easy.updateOrderTags(orderId, {
  internal_order_id: "ord_42",
  fulfillment_state: "shipped",
} satisfies OrderTags);
```

{/* TODO: revisit if/when the SDK exposes a `EasyLabs.Tags` augmentable interface. */}


# Webhooks (/docs/sdks/node/webhooks)



Easy Labs delivers events as HTTPS POSTs with a JSON `WebhookEvent` body and four headers:

| Header                     | Description                                                     |
| -------------------------- | --------------------------------------------------------------- |
| `x-easy-webhook-signature` | `sha256=<hex>` HMAC of the raw body using your endpoint secret. |
| `x-easy-event`             | The event type, e.g. `payment.created`.                         |
| `x-easy-delivery-id`       | UUID identifying this delivery attempt.                         |
| `x-easy-webhook-attempt`   | Attempt number, `1`–`3`.                                        |

Register endpoints with `registerWebhookEndpoint`. The signing secret is returned **only on creation** — store it immediately.

## Verifying signatures [#verifying-signatures]

`EasyWebhooks.constructEvent(rawBody, signature, secret)` validates the HMAC in constant time, parses the JSON body, and returns a typed `WebhookEvent<T>`. It throws `EasyApiError` (status 400) when the signature header is missing, malformed, or doesn't match. `EasyApiError` is exported as a runtime value from `@easylabs/common` (the `@easylabs/node` re-export is type-only), so use the common import for `instanceof` checks.

The `rawBody` argument **must be the exact bytes you received**. Do not pass a parsed object — re-stringifying changes whitespace and breaks the signature. Most frameworks expose the raw body via a config flag or a per-route opt-out.

### Express [#express]

```ts
import express from "express";
import { EasyWebhooks } from "@easylabs/node";
import { EasyApiError } from "@easylabs/common";

const app = express();

app.post(
  "/webhooks/easy",
  express.raw({ type: "application/json" }),
  (req, res) => {
    try {
      const event = EasyWebhooks.constructEvent(
        req.body.toString("utf8"),
        req.header("x-easy-webhook-signature") ?? "",
        process.env.EASY_WEBHOOK_SECRET!,
      );

      // event.type is one of EASY_EVENT_TYPES, e.g. "payment.created"
      console.log(event.id, event.type);

      res.status(204).end();
    } catch (err) {
      if (err instanceof EasyApiError) return res.status(400).end();
      throw err;
    }
  },
);
```

### Fastify [#fastify]

```ts
import Fastify from "fastify";
import { EasyWebhooks } from "@easylabs/node";
import { EasyApiError } from "@easylabs/common";

const app = Fastify();

// Capture the raw body for the webhook route
app.addContentTypeParser(
  "application/json",
  { parseAs: "string" },
  (_req, body, done) => done(null, body),
);

app.post("/webhooks/easy", async (req, reply) => {
  try {
    const event = EasyWebhooks.constructEvent(
      req.body as string,
      (req.headers["x-easy-webhook-signature"] as string) ?? "",
      process.env.EASY_WEBHOOK_SECRET!,
    );
    // ...handle event...
    return reply.code(204).send();
  } catch (err) {
    // Signature failures throw EasyApiError(status: 400) — surface that
    // to the dispatcher instead of letting Fastify return a 500.
    if (err instanceof EasyApiError) return reply.code(400).send();
    throw err;
  }
});
```

### Next.js Route Handler [#nextjs-route-handler]

```ts
// app/api/webhooks/easy/route.ts
import { EasyWebhooks } from "@easylabs/node";
import { EasyApiError } from "@easylabs/common";

export async function POST(req: Request) {
  const rawBody = await req.text();
  try {
    const event = EasyWebhooks.constructEvent(
      rawBody,
      req.headers.get("x-easy-webhook-signature") ?? "",
      process.env.EASY_WEBHOOK_SECRET!,
    );
    // ...handle event...
    return new Response(null, { status: 204 });
  } catch (err) {
    if (err instanceof EasyApiError) return new Response(null, { status: 400 });
    throw err;
  }
}
```

## Replay protection [#replay-protection]

The signature alone protects integrity but not replay. Each delivery includes `x-easy-delivery-id` (UUID) and the body has `event.id` — store the delivery (or event) ID after first successful processing and reject duplicates. The dispatcher attempts a delivery up to 3 times (`x-easy-webhook-attempt: 1..3`), so your handler must be idempotent.

Inspect or replay a delivery server-side via `easy.listWebhookDeliveries({ … })` or `easy.listEndpointDeliveries(endpointId, { … })`.

## Common event types [#common-event-types]

The full list lives in the `EASY_EVENT_TYPES` const exported from `@easylabs/node`. Highlights:

| Event                                                                                                                                                  | Fires when                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
| `payment.created`, `payment.updated`                                                                                                                   | A transfer is created or transitions state. |
| `refund.created`, `refund.updated`                                                                                                                     | A reversal is opened or completes.          |
| `authorization.created`, `authorization.updated`, `authorization.voided`                                                                               | Auth-and-capture lifecycle.                 |
| `subscription.created`, `subscription.updated`, `subscription.deleted`                                                                                 | Subscription lifecycle.                     |
| `subscription.paused`, `subscription.resumed`, `subscription.trial_will_end`                                                                           | Pause / trial transitions.                  |
| `subscription.pending_update_applied`, `subscription.pending_update_expired`                                                                           | Scheduled item changes.                     |
| `invoice.created`, `invoice.finalized`, `invoice.paid`, `invoice.payment_failed`, `invoice.upcoming`, `invoice.voided`, `invoice.marked_uncollectible` | Invoice lifecycle.                          |
| `revenue_recovery.action_completed`                                                                                                                    | A dunning automation action ran.            |
| `coupon.*`, `promotion_code.*`                                                                                                                         | Promo lifecycle.                            |
| `identity.created`, `identity.updated`                                                                                                                 | Customer changes.                           |
| `settlement.created`                                                                                                                                   | A settlement was opened.                    |
| `dispute.created`, `dispute.updated`                                                                                                                   | Chargeback lifecycle.                       |
| `checkout.session.completed`, `checkout.session.crypto_confirmed`                                                                                      | Embedded checkout finished.                 |
| `test.webhook`                                                                                                                                         | Synthetic event for endpoint health checks. |

Subscribe to specific events when you register the endpoint, or pass `["*"]` (the default) to receive every event type.


# Authentication (/docs/sdks/python/authentication)



Every request from the SDK is authenticated with a single secret API key
sent on the `x-easy-api-key` header. The SDK never reads keys from the
filesystem or environment on its own — you pass the key explicitly to
`Client(api_key=...)` so you can keep secret management in one place.

Two key prefixes route automatically:

| Prefix     | Environment | Base URL                                |
| ---------- | ----------- | --------------------------------------- |
| `sk_test_` | Sandbox     | `https://sandbox-api.itseasy.co/v1/api` |
| `sk_live_` | Production  | `https://api.itseasy.co/v1/api`         |

Use sandbox keys for development and CI. Production keys see real money.

## Initializing with an API key [#initializing-with-an-api-key]

```python
import os
from easylabs import Client

# Sandbox — sk_test_... routes to sandbox automatically.
client = Client(api_key=os.environ["EASY_API_KEY"])

# Production — sk_live_... routes to production automatically.
prod = Client(api_key=os.environ["EASY_LIVE_KEY"])

# Self-hosted / pinned-CI: bypass routing entirely.
local = Client(
    api_key="sk_test_...",
    internal_api_url="http://localhost:4000/v1/api",
)
```

The constructor calls `GET /validate-key` synchronously. If the key is
malformed, revoked, or doesn't match the target environment, it raises
`easylabs.AuthenticationError` before returning the client. That gives
you a guaranteed-good client object on success — no surprise 401s on
the first real request.

## Rotating keys [#rotating-keys]

Keys can be rotated without downtime by running two clients side-by-side
during the cutover:

```python
old = Client(api_key=os.environ["EASY_API_KEY"])
new = Client(api_key=os.environ["EASY_API_KEY_NEXT"])

# Route new traffic through `new`; let in-flight requests on `old` finish.
# Once the dashboard confirms zero requests on the old key, revoke it.
```

There's no per-key state on the client, so swapping at runtime (e.g.
re-binding a module-level singleton) is also safe.

## Multi-tenant authentication [#multi-tenant-authentication]

The SDK is designed for one key per `Client` instance. For multi-tenant
servers, build a small factory keyed by tenant:

```python
from functools import lru_cache
from easylabs import Client

@lru_cache(maxsize=512)
def client_for(tenant_id: str) -> Client:
    api_key = lookup_api_key(tenant_id)        # your own resolver
    return Client(api_key=api_key)
```

`Client` is cheap to keep around (one `httpx.Client` + a few resource
namespaces), but `__init__` does perform a `/validate-key` round-trip,
so caching avoids the network hop on every request.

{/* TODO: Document a recommended request-scoped pattern for ASGI / Django
  once the async client lands in 0.2. */}


# Error handling (/docs/sdks/python/error-handling)



Every non-2xx response is mapped to a typed exception that subclasses
`easylabs.EasyError`. Catch the specific subclass for targeted handling
or `EasyError` to catch everything the SDK throws.

```python
from easylabs import (
    EasyError,            # base class for every SDK error
    AuthenticationError,  # 401
    PermissionError,      # 403  — note: shadows the Python builtin
    NotFoundError,        # 404
    ConflictError,        # 409
    InvalidRequestError,  # 400 / 422
    RateLimitError,       # 429
    ServerError,          # 5xx
)
```

> `easylabs.PermissionError` shadows the Python built-in `PermissionError`.
> Always import explicitly from `easylabs` (or reference as
> `easylabs.PermissionError`) to keep things unambiguous.

Every `EasyError` carries the same fields:

| Attribute             | Type          | Notes                                               |
| --------------------- | ------------- | --------------------------------------------------- |
| `message`             | `str`         | Human-readable summary.                             |
| `status`              | `int`         | HTTP status code.                                   |
| `code`                | `str \| None` | Server-supplied error code (e.g. `"INVALID_CARD"`). |
| `details`             | `Any`         | Field-level details from the API.                   |
| `retry_after_seconds` | `int \| None` | Parsed from the `Retry-After` header on 429s.       |
| `raw`                 | `Any`         | The raw decoded JSON body (or `None`).              |

## Retryable vs. non-retryable [#retryable-vs-non-retryable]

| HTTP status | Exception             | Retry?                                       |
| ----------- | --------------------- | -------------------------------------------- |
| 400         | `InvalidRequestError` | No — fix the request.                        |
| 401         | `AuthenticationError` | No — fix the key.                            |
| 403         | `PermissionError`     | No — caller lacks the required scope.        |
| 404         | `NotFoundError`       | No — the ID doesn't exist (or never did).    |
| 409         | `ConflictError`       | No — re-read state, then retry deliberately. |
| 422         | `InvalidRequestError` | No — validation failed.                      |
| 429         | `RateLimitError`      | Yes — wait `retry_after_seconds`.            |
| 5xx         | `ServerError`         | Yes — exponential backoff with jitter.       |

A minimal retry loop:

```python
import time
from easylabs import RateLimitError, ServerError

def with_retries(fn, *, attempts: int = 5):
    for i in range(attempts):
        try:
            return fn()
        except RateLimitError as e:
            time.sleep(e.retry_after_seconds or 1)
        except ServerError:
            time.sleep(min(2 ** i, 30))
    return fn()  # last attempt; let the exception escape if it fails
```

## Idempotency keys [#idempotency-keys]

Every mutating method on every resource accepts an `idempotency_key=`
keyword argument. The SDK sends it as the `Idempotency-Key` header.
Replays of the same key within the server's retention window return
the original response — safe to retry without creating duplicate
charges, customers, or refunds.

```python
import uuid

key = f"refund-{order_id}-{uuid.uuid4()}"

client.transfers.create_refund(
    transfer_id,
    refund_amount=2500,
    idempotency_key=key,
)
```

A few rules of thumb:

* Generate the key **once per logical operation** (e.g. one per checkout
  attempt), then reuse it across retries.
* Use UUIDs or any unique string up to 255 characters.
* Read endpoints (`list`, `retrieve`) accept the header but ignore it —
  no harm in passing it through unconditionally if your transport
  middleware does.

The SDK does not retry automatically. Pair `idempotency_key=` with the
retry loop above to make the combination safe.

## Network errors [#network-errors]

Network-level failures are not wrapped — `httpx` raises them directly.
You'll see things like:

* `httpx.ConnectError` — DNS / TCP failure.
* `httpx.ReadTimeout` / `httpx.WriteTimeout` — request exceeded the
  default 30s timeout.
* `httpx.RemoteProtocolError` — malformed server response.

Handle them alongside `EasyError` if you need a single retry layer:

```python
import httpx
from easylabs import EasyError

try:
    customer = client.customers.retrieve("cus_123")
except (httpx.HTTPError, EasyError) as e:
    log.warning("Easy API call failed: %s", e)
    raise
```


# Python SDK (/docs/sdks/python)



`easylabs` is the official Easy Labs SDK for Python. It wraps the full Easy
Labs API — payments, subscriptions, invoicing, treasury, embedded checkout,
and webhooks — behind a typed, namespaced `Client`. Responses come back as
`pydantic` v2 models, so attribute access, validation, and `model_dump()` all
work out of the box.

The SDK targets feature parity with `@easylabs/node`: identical resources,
identical error hierarchy, identical webhook signature semantics. If you've
written a JS integration, the Python one will look familiar — `snake_case`
method names, keyword arguments, and `pip`-friendly distribution are the
only real differences.

## Quick links [#quick-links]



<Cards>
  <Card title="Installation" href="./installation" description="Add the SDK to your project." />

  <Card title="Quickstart" href="./quickstart" description="From zero to first payment in five minutes." />

  <Card title="Webhooks" href="./webhooks" description="Verify and react to platform events." />
</Cards>


# Installation (/docs/sdks/python/installation)



## Prerequisites [#prerequisites]

* Python `>= 3.10` (CPython tested on 3.10 / 3.11 / 3.12 / 3.13).
* An Easy Labs API key (`sk_test_...` for sandbox, `sk_live_...` for
  production). You can grab one from the
  [Easy Labs dashboard](https://dashboard.itseasy.co).

The SDK has two runtime dependencies — both pinned to current major
releases — so installs are quick and conflict-free in most environments:

* [`httpx`](https://www.python-httpx.org/) for transport.
* [`pydantic`](https://docs.pydantic.dev/) v2 for response models.

## Install the package [#install-the-package]

```bash
# pip
pip install easylabs

# uv
uv add easylabs

# poetry
poetry add easylabs

# pipenv
pipenv install easylabs
```

The wheel is published from
[`itseasyco/easy-sdk-python`](https://github.com/itseasyco/easy-sdk-python)
on every release. There are no native dependencies — installs work on
Linux, macOS, and Windows without a build toolchain.

## Verify the install [#verify-the-install]

```python
import os
from easylabs import Client, __version__

print(f"easylabs version: {__version__}")

client = Client(api_key=os.environ["EASY_API_KEY"])
print(f"Routed to: {client.api_url}")
```

`Client(...)` calls `GET /validate-key` on construction. If the key is
invalid you'll see an `easylabs.AuthenticationError` here rather than on
your first real request.

## Next steps [#next-steps]

* [Quickstart](./quickstart) — render your first payment.
* [Authentication](./authentication) — keys, environments, and the
  `internal_api_url` escape hatch.


# Pagination (/docs/sdks/python/pagination)



All `list(...)` methods on the SDK use **offset-based pagination** with
two keyword arguments:

| Argument | Type          | Default | Notes                                          |
| -------- | ------------- | ------- | ---------------------------------------------- |
| `limit`  | `int \| None` | server  | Page size. The server enforces an upper bound. |
| `offset` | `int \| None` | server  | How many records to skip from the start.       |

Most `list(...)` methods return a &#x2A;*plain `list`** of typed models —
not a paginated wrapper. The total count is not returned, so you
paginate by walking the offset until you see fewer results than the
page size.

A handful of endpoints return a paginated envelope (`{ data, total,
limit, offset }`); those are called out below.

> Treasury transactions (`client.treasury.list_transactions`) are the
> exception — they use **cursor-based** pagination via `cursor=` /
> `next_cursor`. See the [Treasury](./resources/treasury) page.

## Manual pagination [#manual-pagination]

```python
PAGE_SIZE = 100

offset = 0
all_customers = []
while True:
    page = client.customers.list(limit=PAGE_SIZE, offset=offset)
    all_customers.extend(page)
    if len(page) < PAGE_SIZE:
        break
    offset += PAGE_SIZE
```

If you only need a slice, pass `limit=` and call it once:

```python
recent = client.invoices.list(limit=20)
```

Some `list(...)` methods accept extra filters; for example,
`client.invoices.list(...)` accepts `status=`, `collection_method=`,
`due_date_from=`, and `due_date_to=`. See each
[resource page](./resources) for the per-resource filter set.

## Endpoints that return a paginated envelope [#endpoints-that-return-a-paginated-envelope]

A few endpoints return `{ data, total, limit, offset }` instead of a
bare list — typically because the server already needs `total` to render
a count UI. These are returned as a `dict` (not a model) for simplicity:

* `client.customers.subscriptions(customer_id, ...)` — `data` is a
  list of `Subscription` models, `total` is the row count.
* `client.webhooks_management.list_deliveries(...)` and
  `list_endpoint_deliveries(...)`.
* `client.treasury.list_transactions(...)` — uses **cursor** pagination
  (`cursor=` / `next_cursor` in the envelope), not offset.

```python
page = client.customers.subscriptions("cus_123", limit=25, offset=0)
print(page["total"])
for sub in page["data"]:
    print(sub.id, sub.status)
```

## Auto-pagination [#auto-pagination]

There is no built-in iterator helper in `0.1.x`. Wrap the manual loop
in a generator if you want a Pythonic interface:

```python
from typing import Iterator
from easylabs import Customer

def iter_all(list_fn, *, page_size: int = 100, **filters) -> Iterator[Customer]:
    offset = 0
    while True:
        page = list_fn(limit=page_size, offset=offset, **filters)
        if not page:
            return
        yield from page
        if len(page) < page_size:
            return
        offset += page_size

for cust in iter_all(client.customers.list):
    ...
```

{/* TODO: A first-class auto-pagination helper (e.g. `client.customers.list_iter(...)`)
  is on the roadmap for 0.2 alongside the async client. */}


# Quickstart (/docs/sdks/python/quickstart)



This guide walks through the smallest end-to-end happy path: install the
SDK, create a customer, then charge them. Every snippet is copy-pasteable
into a `python` REPL or a script.

## 1. Get your API keys [#1-get-your-api-keys]

Sign in to the [Easy Labs dashboard](https://dashboard.itseasy.co) and
copy a secret key from **Developers → API keys**.

* Keys prefixed `sk_test_` route to **sandbox** automatically.
* Keys prefixed `sk_live_` route to **production** automatically.

Store the key in an environment variable. Never commit it to source
control.

```bash
export EASY_API_KEY="sk_test_..."
```

## 2. Initialize the SDK [#2-initialize-the-sdk]

```python
import os
from easylabs import Client

client = Client(api_key=os.environ["EASY_API_KEY"])
```

`Client(...)` calls `GET /validate-key` on construction, so an invalid
key fails fast right here with `AuthenticationError`. The publishable
Basis Theory key returned by `/validate-key` is exposed as
`client.basis_theory_public_api_key` if you need it for tokenization.

## 3. Make your first call [#3-make-your-first-call]

```python
customer = client.customers.create(
    first_name="Ada",
    last_name="Lovelace",
    email="ada@example.com",
)
print(customer.id)            # → "cus_..."
print(customer.created_at)
```

Resources are namespaced on the client (`client.customers`,
`client.payment_links`, `client.subscriptions`, ...) and every method
returns a typed `pydantic` model (or a list of them) with attribute
access.

## 4. Handle the response [#4-handle-the-response]

The full success / failure shape:

```python
from easylabs import (
    Client,
    EasyError,
    InvalidRequestError,
    RateLimitError,
)

try:
    link = client.payment_links.create(
        items=[{"price_id": "price_123", "quantity": 1}],
    )
    print(link.id)
except InvalidRequestError as e:
    # 400 / 422 — bad input. `details` carries field-level errors.
    print("validation failed:", e.code, e.details)
except RateLimitError as e:
    # 429 — back off; `retry_after_seconds` reflects the Retry-After header.
    print("rate limited; retry in", e.retry_after_seconds, "s")
except EasyError as e:
    # Catch-all for any other 4xx / 5xx response.
    print(e.status, e.code, e.message)
```

See [Error handling](./error-handling) for the full hierarchy and
[Pagination](./pagination) for working with `list(...)` endpoints.

## What's next [#whats-next]

* [Resources → Customers](./resources/customers)
* [Resources → Subscriptions](./resources/subscriptions)
* [Webhooks](./webhooks) — verify deliveries and react to events.


# Type hints (/docs/sdks/python/type-hints)



`easylabs` is fully typed. Public types are tested under `pyright` in
`standard` mode and ship with the wheel via PEP 561 — no separate stubs
package to install. If you use `mypy`, `pyright`, or any LSP that
respects inline annotations, autocomplete and type checking just work.

The SDK targets Python `>= 3.10` so it can use native `X | None` unions,
PEP 604 syntax, and `from __future__ import annotations` throughout.

## Response models — `pydantic` v2 [#response-models--pydantic-v2]

Every method returns a `pydantic` v2 model (or a list/dict of them).
Models inherit from `easylabs.EasyModel`, which sets:

* `extra="allow"` — forward-compatible. New fields the API adds appear
  on the model and survive `model_dump()` round-trips.
* `populate_by_name=True` — fields with `Field(alias=...)` accept both
  the alias and the snake\_case name on construction.

That means:

```python
customer = client.customers.retrieve("cus_123")

customer.id            # str
customer.email         # str | None
customer.tags          # dict[str, Any] | None
customer.model_dump()  # plain dict — useful for logging / DB insert
```

To go the other way (dict → model), use `Customer.model_validate(...)`:

```python
from easylabs import Customer

raw = {"id": "cus_123", "email": "ada@example.com"}
customer = Customer.model_validate(raw)
```

## Public types [#public-types]

All of these are importable from the top-level `easylabs` package.

### Client + errors [#client--errors]

| Type                  | Purpose                              |
| --------------------- | ------------------------------------ |
| `Client`              | The SDK entry point.                 |
| `EasyError`           | Base for every SDK error.            |
| `AuthenticationError` | 401.                                 |
| `PermissionError`     | 403 (shadows the Python builtin).    |
| `NotFoundError`       | 404.                                 |
| `ConflictError`       | 409.                                 |
| `InvalidRequestError` | 400 / 422.                           |
| `RateLimitError`      | 429 (carries `retry_after_seconds`). |
| `ServerError`         | 5xx.                                 |

### Webhooks [#webhooks]

| Type           | Purpose                                                      |
| -------------- | ------------------------------------------------------------ |
| `Webhooks`     | Static utility namespace; exposes `construct_event(...)`.    |
| `WebhookEvent` | Verified event payload (`id`, `type`, `data`, `created_at`). |
| `EVENT_TYPES`  | Tuple of every event name the SDK knows about.               |

### Resource models [#resource-models]

Customer / billing / payments:

`Customer`, `PaymentInstrument`, `FinixPaymentInstrument`, `Transfer`,
`Authorization`, `Order`, `Settlement`, `Dispute`, `Wallet`.

Catalog & subscriptions:

`Product`, `ProductPrice`, `Subscription`, `SubscriptionItem`,
`SubscriptionDiscount`, `SubscriptionPlan`, `Coupon`, `PromotionCode`,
`ValidatePromotionCodeResponse`.

Checkout:

`CheckoutResponse`, `PaymentLink`, `CreatePaymentLinkResponse`,
`EmbeddedCheckoutSession`, `EmbeddedCheckoutSessionStatus`,
`EmbeddedCheckoutConfig`, `ValidateEmbeddedCheckoutSessionResponse`,
`CryptoPaymentStatus`.

Operations:

`Invoice`, `DunningConfig`, `RevenueRecoveryAutomation`,
`RevenueRecoveryAutomationRun`, `ComplianceForm`, `AnalyticsResult`,
`WebhookEndpoint`, `RegisteredWebhookEndpoint`, `WebhookDelivery`.

Treasury (importable from `easylabs.models`):

`TreasuryBankAccount`, `TreasuryCategory`, `TreasuryRecipient`,
`TreasuryTransaction`, `TreasuryPayoutLink`, `TreasuryRecurringPayment`,
`TreasuryAutoTransferRule`, `TreasurySecurityRule`,
`TreasuryApprovalRequest`.

## Extending models [#extending-models]

Because `EasyModel` sets `extra="allow"`, brand-new fields the API ships
between SDK releases are still accessible — just not statically typed:

```python
customer = client.customers.retrieve("cus_123")

# Statically-known field — type-checked.
print(customer.id)

# New field the SDK doesn't know about yet — accepted at runtime.
print(customer.model_extra.get("future_field"))
```

If you need stronger typing for an extra field across your codebase,
subclass the model:

```python
from easylabs import Customer

class TenantCustomer(Customer):
    tenant_id: str | None = None

raw = client.customers.retrieve("cus_123").model_dump()
tenant_customer = TenantCustomer.model_validate(raw)
```

{/* TODO: Add a `TypedDict` companion for request bodies once the typed-input
  shapes (CreateCustomerInput, etc.) ship — currently mutating methods take
  `**kwargs: Any`. */}


# Webhooks (/docs/sdks/python/webhooks)



Webhooks let your server react to events that happen asynchronously on
Easy Labs — payments completing, subscriptions renewing, invoices
finalizing, disputes opening — without polling for changes. Easy Labs
delivers each event as a signed `POST` to a URL you register with
`client.webhooks_management.register(...)`. The SDK ships a small,
framework-agnostic verifier that turns the raw request into a typed
`WebhookEvent`.

The webhook surface has two halves:

| API                                      | Purpose                                              |
| ---------------------------------------- | ---------------------------------------------------- |
| `easylabs.Webhooks.construct_event(...)` | Verify a signature + parse the event payload.        |
| `client.webhooks_management.*`           | Register / list / delete endpoints, list deliveries. |

Endpoint management lives on its own [Webhook Endpoints](./resources/webhook-endpoints)
page; this page covers verification.

## Verifying signatures [#verifying-signatures]

```python
import os
from easylabs import Webhooks, InvalidRequestError

SECRET = os.environ["EASY_WEBHOOK_SECRET"]  # returned once on register()


def handle(request):
    try:
        event = Webhooks.construct_event(
            payload=request.body,                                  # bytes preferred
            signature=request.headers.get("x-easy-webhook-signature", ""),
            secret=SECRET,
        )
    except InvalidRequestError as e:
        # Signature missing / malformed / mismatched, or body wasn't JSON.
        return ("invalid signature", 400)

    if event.type == "payment.created":
        # event.data carries the resource payload (dict)
        ...
    elif event.type == "subscription.trial_will_end":
        ...

    return ("", 204)
```

Notes:

* Pass the **raw request body**, not a re-serialized JSON string. The
  signature is computed over the exact bytes Easy Labs sent — pretty-
  printing or re-encoding will fail verification.
* `payload=` accepts `bytes` (preferred) or `str`.
* `Webhooks.construct_event` raises `easylabs.InvalidRequestError`
  (HTTP 400) on every verification failure. Inspect `e.code` to
  distinguish cases:

  | `e.code`                           | Meaning                                                    |
  | ---------------------------------- | ---------------------------------------------------------- |
  | `WEBHOOK_SIGNATURE_MISSING`        | The `x-easy-webhook-signature` header was empty or absent. |
  | `WEBHOOK_SIGNATURE_FORMAT_INVALID` | Header didn't start with `sha256=` or wasn't valid hex.    |
  | `WEBHOOK_SIGNATURE_MISMATCH`       | Signature didn't match what we computed from the body.     |
  | `WEBHOOK_BODY_INVALID_JSON`        | Body verified but failed to parse as JSON.                 |

Comparison uses `hmac.compare_digest`, so verification is constant-time.

## Replay protection [#replay-protection]

The SDK verifies the HMAC signature over the body. Easy Labs will
re-deliver the same event with the same signature on retries, which is
exactly what makes webhooks resilient — but it also means a leaked
payload could in principle be re-played by an attacker who learns the
URL.

Two recommendations:

* **Idempotency on your side.** Treat `event.id` as a primary key.
  Skip processing if you've already seen it.

  ```python
  if WebhookEventLog.exists(event.id):
      return ("", 204)
  WebhookEventLog.record(event.id, event.type)
  ```

* **Tight network exposure.** Restrict the receive endpoint to TLS,
  authenticate the source IP / proxy, and rotate the signing secret if
  you suspect compromise (`webhooks_management.update`).

{/* TODO: Document the precise replay window once the API exposes a
  signed timestamp prefix; today the signature is body-only. */}

## Common event types [#common-event-types]

The full list is exported as `easylabs.EVENT_TYPES`:

```python
from easylabs import EVENT_TYPES
print(EVENT_TYPES)
```

A representative subset:

| Event                                                                                                              | Fired when…                                             |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
| `payment.created` / `payment.updated`                                                                              | A `Transfer` is created or transitions state.           |
| `refund.created` / `refund.updated`                                                                                | A reversal is created or transitions state.             |
| `authorization.created` / `.updated` / `.voided`                                                                   | Auth-and-capture lifecycle changes.                     |
| `subscription.created` / `.updated` / `.deleted`                                                                   | Subscription lifecycle.                                 |
| `subscription.paused` / `.resumed`                                                                                 | Pause collection toggles.                               |
| `subscription.trial_will_end`                                                                                      | 3 days before a trial ends.                             |
| `subscription.pending_update_applied` / `.pending_update_expired`                                                  | Scheduled changes resolve.                              |
| `invoice.created` / `.finalized` / `.paid` / `.payment_failed` / `.upcoming` / `.voided` / `.marked_uncollectible` | Invoice lifecycle.                                      |
| `revenue_recovery.action_completed`                                                                                | A dunning step ran.                                     |
| `coupon.*` / `promotion_code.*`                                                                                    | Discount config changes.                                |
| `identity.created` / `.updated`                                                                                    | Customer / identity changes.                            |
| `settlement.created`                                                                                               | A settlement was issued.                                |
| `dispute.created` / `.updated`                                                                                     | Chargeback / dispute lifecycle.                         |
| `checkout.session.completed`                                                                                       | A hosted / embedded checkout finished.                  |
| `checkout.session.crypto_confirmed`                                                                                | A crypto checkout payment was confirmed on-chain.       |
| `test.webhook`                                                                                                     | Sent when you click "Send test event" in the dashboard. |

The full payload for each event is documented in the
[Easy Labs API reference](https://docs.itseasy.co/api).


# Elements (/docs/sdks/react/elements)



Elements are iframe-isolated form inputs for collecting card and bank-account details. The raw values you type into them are entered into a Basis Theory iframe served from a different origin than your app — they never enter your React state, your DOM, or your network requests, which keeps your integration out of PCI scope.

`@easylabs/react` re-exports five elements from `@basis-theory/react-elements`. Use them inside an [`EasyProvider`](./provider), attach a `ref`, and pass that ref to `useEasy().checkout()`, `createPaymentInstrument()`, or `tokenizePaymentInstrument()` — the SDK handles tokenization in one step.

## Available elements [#available-elements]

| Element                         | Use for                                                                   | Ref type                       |
| ------------------------------- | ------------------------------------------------------------------------- | ------------------------------ |
| `<CardElement>`                 | A single combined card input (number, expiry, CVC).                       | `ICardElement`                 |
| `<CardNumberElement>`           | Card number only, when you want a split layout.                           | `ICardNumberElement`           |
| `<CardExpirationDateElement>`   | Expiry date only.                                                         | `ICardExpirationDateElement`   |
| `<CardVerificationCodeElement>` | CVC / CVV only.                                                           | `ICardVerificationCodeElement` |
| `<TextElement>`                 | Generic text input — used by the SDK for ACH routing and account numbers. | `ITextElement`                 |

Either `cardElement` **or** the trio (`cardNumberElement` + `cardExpirationDateElement` + `cardVerificationCodeElement`) is required for card tokenization, never both. For bank accounts, both `routingElement` and `accountElement` are required.

## Combined card [#combined-card]

```tsx title="src/CombinedCard.tsx"
import { CardElement, useEasy, type ICardElement } from "@easylabs/react";
import { useRef } from "react";

export function CombinedCard({ customerId }: { customerId: string }) {
  const cardRef = useRef<ICardElement>(null);
  const { createPaymentInstrument } = useEasy();

  async function save() {
    const res = await createPaymentInstrument({
      type: "PAYMENT_CARD",
      customerId,
      name: "Primary card",
      cardElement: cardRef,
    });
    console.log("instrument", res.data.id);
  }

  return (
    <>
      <CardElement ref={cardRef} id="card" />
      <button onClick={save}>Save card</button>
    </>
  );
}
```

## Split card fields [#split-card-fields]

```tsx title="src/SplitCard.tsx"
import {
  CardNumberElement,
  CardExpirationDateElement,
  CardVerificationCodeElement,
  useEasy,
  type ICardNumberElement,
  type ICardExpirationDateElement,
  type ICardVerificationCodeElement,
} from "@easylabs/react";
import { useRef } from "react";

export function SplitCard({ customerId }: { customerId: string }) {
  const numberRef = useRef<ICardNumberElement>(null);
  const expRef = useRef<ICardExpirationDateElement>(null);
  const cvcRef = useRef<ICardVerificationCodeElement>(null);
  const { createPaymentInstrument } = useEasy();

  async function save() {
    await createPaymentInstrument({
      type: "PAYMENT_CARD",
      customerId,
      name: "Primary card",
      cardNumberElement: numberRef,
      cardExpirationDateElement: expRef,
      cardVerificationCodeElement: cvcRef,
    });
  }

  return (
    <>
      <CardNumberElement ref={numberRef} id="card-number" />
      <CardExpirationDateElement ref={expRef} id="card-exp" />
      <CardVerificationCodeElement ref={cvcRef} id="card-cvc" />
      <button onClick={save}>Save card</button>
    </>
  );
}
```

## Bank account (ACH) [#bank-account-ach]

```tsx title="src/BankAccount.tsx"
import { TextElement, useEasy, type ITextElement } from "@easylabs/react";
import { useRef } from "react";

export function BankAccount({ customerId }: { customerId: string }) {
  const routingRef = useRef<ITextElement>(null);
  const accountRef = useRef<ITextElement>(null);
  const { createPaymentInstrument } = useEasy();

  async function save() {
    await createPaymentInstrument({
      type: "BANK_ACCOUNT",
      customerId,
      name: "Checking account",
      accountType: "PERSONAL_CHECKING",
      routingElement: routingRef,
      accountElement: accountRef,
    });
  }

  return (
    <>
      <label htmlFor="routing">Routing number</label>
      <TextElement ref={routingRef} id="routing" placeholder="Routing" />
      <label htmlFor="account">Account number</label>
      <TextElement ref={accountRef} id="account" placeholder="Account" />
      <button onClick={save}>Save bank account</button>
    </>
  );
}
```

## Styling [#styling]

Elements live inside cross-origin iframes, so your page CSS does not reach the input itself. There are two layers of styling:

* **The mount container** is a regular DOM node you can target with normal CSS, layout primitives, and design-system wrappers. Wrap the element in your own `<div>` to control border, padding, focus ring, etc. Element components also accept `style` and `className` props that apply to that wrapper.
* **The input inside the iframe** is themed with the `style` prop on each element, which accepts the [Basis Theory element style schema](https://developers.basistheory.com/docs/sdks/web/javascript/elements#style). Use it for font, color, and placeholder color of the actual input.

```tsx
<CardElement
  ref={cardRef}
  id="card"
  style={{
    base: {
      color: "#0f172a",
      fontFamily: "Inter, sans-serif",
      fontSize: "16px",
      "::placeholder": { color: "#94a3b8" },
    },
    invalid: { color: "#ef4444" },
  }}
/>
```

For autofill, pass `autoComplete` on `CardElement`:

```tsx
<CardElement
  ref={cardRef}
  id="card"
  autoComplete={{ number: "cc-number", expirationDate: "cc-exp", csc: "cc-csc" }}
/>
```

## Validation [#validation]

Validation runs inside the iframe and surfaces through Basis Theory element events (`change`, `ready`, `blur`, `focus`). Subscribe with the ref:

```tsx
useEffect(() => {
  const el = cardRef.current;
  if (!el) return;
  const sub = el.on("change", (event) => {
    setError(event.errors?.[0]?.type ?? null);
  });
  return () => sub.unsubscribe();
}, []);
```

If you call `checkout` or `createPaymentInstrument` with an incomplete element, the SDK throws before hitting the API:

* `Card element reference is not set.` — neither `cardElement` nor the split trio is mounted.
* `All card elements must be available for separate element tokenization.` — partial split-card refs.
* `Card expiration date is incomplete.` — `cardExpirationDateElement.month()` or `.year()` returned `undefined`.
* `Routing or account element reference is not set` — bank account ref missing.

For the full event API (`change`, `ready`, `blur`, `focus`, mask events) see the [Basis Theory React Elements docs](https://developers.basistheory.com/docs/sdks/web/react/).

## Submitting [#submitting]

The recommended path is to skip manual tokenization — pass the element refs straight into `checkout` or `createPaymentInstrument` and the SDK does the right thing:

```tsx
const res = await checkout({
  customer_creation: true,
  customer_details: { first_name: "Ada", last_name: "Lovelace", email: "ada@example.com" },
  line_items: [{ price_id: "price_123", quantity: 1 }],
  source: { type: "PAYMENT_CARD", name: "Ada Lovelace", cardElement: cardRef },
});
```

If you need a bare token (e.g. to store it for later use without creating an instrument), use `tokenizePaymentInstrument`:

```tsx
const tokenId = await tokenizePaymentInstrument({
  type: "PAYMENT_CARD",
  cardElement: cardRef,
});
```


# Embedded Checkout (/docs/sdks/react/embedded-checkout)



`<EmbeddedCheckout>` mounts an Easy Labs–hosted checkout flow inside an iframe in your page. Use it when you want a complete checkout — including card capture, ACH, and crypto payments — without building the form yourself, but still want it embedded in your own UI rather than redirecting the customer away.

The iframe is loaded from `https://checkout.itseasy.co/embed`, auto-resizes to its content, and communicates with your page through a small `postMessage` protocol. Wrap it in `<EmbeddedCheckoutProvider>` to get success / error / close callbacks and a `useEmbeddedCheckout()` status hook.

## Server: create a checkout session [#server-create-a-checkout-session]

Call `createEmbeddedCheckoutSession` from your server (or the client `useEasy()` hook for prototypes) to get a `client_secret`. This must happen server-side in production so your API key stays out of the browser.

```ts title="app/checkout/session.ts (Node SDK)"
import { Easy } from "@easylabs/node";

const easy = new Easy(process.env.EASY_API_KEY!);

export async function createSession() {
  const res = await easy.createEmbeddedCheckoutSession({
    line_items: [{ price_id: "price_123", quantity: 1 }],
    mode: "payment",
    success_url: "https://example.com/checkout/success",
    cancel_url: "https://example.com/checkout/cancel",
    payment_methods: ["card", "crypto"],
  });
  return res.data.client_secret;
}
```

For the matching backend reference, see [Node SDK → Embedded Checkout](/sdk/node/embedded-checkout).

## Client: mount the iframe [#client-mount-the-iframe]

Pass the `client_secret` to `<EmbeddedCheckout>`. Wrap it in `<EmbeddedCheckoutProvider>` if you want lifecycle callbacks.

```tsx title="src/app/checkout/page.tsx"
"use client";

import {
  EmbeddedCheckout,
  EmbeddedCheckoutProvider,
  useEmbeddedCheckout,
} from "@easylabs/react";
import { useEffect, useState } from "react";

function Status() {
  const { status } = useEmbeddedCheckout();
  return <p>Checkout status: {status}</p>;
}

export default function CheckoutPage() {
  const [clientSecret, setClientSecret] = useState<string>();

  useEffect(() => {
    fetch("/api/checkout/session", { method: "POST" })
      .then((r) => r.json())
      .then((d) => setClientSecret(d.clientSecret));
  }, []);

  if (!clientSecret) return <p>Loading…</p>;

  return (
    <EmbeddedCheckoutProvider
      config={{
        clientSecret,
        onSuccess: ({ sessionId, status, tx_signature }) => {
          console.log("paid", { sessionId, status, tx_signature });
          window.location.href = "/checkout/success";
        },
        onError: (err) => console.error(err),
        onClose: () => console.log("closed"),
      }}
    >
      <Status />
      <EmbeddedCheckout clientSecret={clientSecret} />
    </EmbeddedCheckoutProvider>
  );
}
```

`<EmbeddedCheckout>` and `<EmbeddedCheckoutProvider>` are both client components (`"use client"`). They do not depend on `EasyProvider` — the iframe is self-contained — so you can render them anywhere.

## Props [#props]

### `<EmbeddedCheckout>` [#embeddedcheckout]

| Prop            | Type            | Required | Description                                                                                                                                                                                                                                                                                                                   |
| --------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientSecret`  | `string`        | yes      | The `client_secret` returned by `createEmbeddedCheckoutSession`. Updating this prop re-sends the `easylabs:init` postMessage to the existing iframe (the iframe `src` is **not** reset). To force a full iframe reload — for example, after a session expires — remount the component, e.g. by changing its React `key` prop. |
| `className`     | `string`        | no       | Class on the wrapping `<div>`.                                                                                                                                                                                                                                                                                                |
| `style`         | `CSSProperties` | no       | Style overrides merged onto the iframe (`width: 100%`, `minHeight: 500px`, no border by default).                                                                                                                                                                                                                             |
| `__checkoutUrl` | `string`        | no       | **Internal.** Override the checkout origin for development.                                                                                                                                                                                                                                                                   |

### `<EmbeddedCheckoutProvider>` [#embeddedcheckoutprovider]

Takes a single `config` prop:

| Field           | Type                                                                                   | Description                                                                                                   |
| --------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `clientSecret`  | `string`                                                                               | Same value passed to `<EmbeddedCheckout>`. Used to authorize incoming events.                                 |
| `onSuccess`     | `(data: { sessionId: string; status: string; tx_signature?: string \| null }) => void` | Fires once for card success and once for confirmed crypto payments. `tx_signature` is only present on crypto. |
| `onError`       | `(error: string) => void`                                                              | Fires if the hosted checkout reports an error.                                                                |
| `onClose`       | `() => void`                                                                           | Fires when the customer closes the embedded experience.                                                       |
| `__checkoutUrl` | `string`                                                                               | **Internal.** Override the checkout origin for development.                                                   |

## `useEmbeddedCheckout()` [#useembeddedcheckout]

Inside an `<EmbeddedCheckoutProvider>`, `useEmbeddedCheckout()` returns:

```ts
{ status: "loading" | "ready" | "complete" | "error" }
```

* `"loading"` — the iframe has not yet sent its `easylabs:ready` handshake.
* `"ready"` — the iframe is rendered and accepting input.
* `"complete"` — `easylabs:success` or `easylabs:crypto_confirmed` arrived.
* `"error"` — `easylabs:error` arrived; check `onError`.

## Events: the postMessage protocol [#events-the-postmessage-protocol]

The iframe and your page exchange JSON `postMessage` events. `<EmbeddedCheckout>` and `<EmbeddedCheckoutProvider>` handle all of these for you — you only need to know about them if you're debugging or building a custom integration.

All messages have a `type` field prefixed with `easylabs:`. Both sides validate the `event.origin` against the checkout URL, and the provider additionally requires that callback-firing events carry a payload whose `client_secret` (or `clientSecret` / `checkout_client_secret`) matches the active session — origin alone isn't enough since other windows on the same origin could otherwise spoof success.

| Direction       | Type                        | Payload                                                      | Purpose                                                                           |
| --------------- | --------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| iframe → parent | `easylabs:ready`            | —                                                            | Iframe finished mounting; parent responds with `easylabs:init`.                   |
| parent → iframe | `easylabs:init`             | `{ clientSecret }`                                           | Hand the session secret to the iframe. Re-sent if `clientSecret` prop changes.    |
| iframe → parent | `easylabs:resize`           | `{ height: number }`                                         | Auto-resize the iframe to its content. Handled automatically.                     |
| iframe → parent | `easylabs:success`          | `{ sessionId, status, ... }` (with matching `client_secret`) | Card / standard payment succeeded. Triggers `onSuccess` and `status: "complete"`. |
| iframe → parent | `easylabs:crypto_confirmed` | `{ session_id, tx_signature, client_secret }`                | On-chain crypto payment confirmed. Triggers `onSuccess` and `status: "complete"`. |
| iframe → parent | `easylabs:close`            | `{ client_secret }`                                          | Customer closed the checkout. Triggers `onClose`.                                 |
| iframe → parent | `easylabs:error`            | `{ error: string, client_secret }`                           | Checkout reported an error. Triggers `onError` and `status: "error"`.             |

If you're polling crypto status server-side, use `useEasy().getCryptoPaymentStatus(sessionId)` as a fallback to the `easylabs:crypto_confirmed` event.

## Customization [#customization]

The hosted page handles the entire payment UI — fields, validation, error states, and the on-chain UX for crypto payments. What you can control today:

* **Container layout.** Use `className` and `style` on `<EmbeddedCheckout>` to set max width, border, shadow, and so on. The iframe defaults to `width: 100%` and `minHeight: 500px`.
* **Payment methods.** Pass `payment_methods: ["card"]`, `["crypto"]`, or both when creating the session.
* **Return / success / cancel URLs.** Pass `return_url`, `success_url`, and `cancel_url` to `createEmbeddedCheckoutSession`. The hosted page also fires `easylabs:success` / `easylabs:close` so you can navigate from your callbacks instead.
* **Customer pre-fill.** Pass `customer_email` to `createEmbeddedCheckoutSession`.

{/* TODO: Confirm whether brand colors / fonts inside the iframe are themable from session creation params or only from the dashboard. */}


# React SDK (/docs/sdks/react)



`@easylabs/react` is the official Easy Labs SDK for React.

It gives you a single `<EasyProvider>` that wires every Easy API resource (customers, payment instruments, products, prices, subscriptions, orders, transfers, settlements, payment links, and embedded checkout sessions) into a `useEasy()` hook, plus a set of PCI-isolated form elements for collecting card and bank-account details directly in your React tree without those values ever touching your server.

The SDK targets React 18 and 19, works in Vite, Next.js (App Router and Pages Router), and any other React renderer that can run client components, and ships with full TypeScript types re-exported from `@easylabs/common`.

## Quick links [#quick-links]



<Cards>
  <Card title="Installation" href="./installation" description="Add the SDK to your project." />

  <Card title="Quickstart" href="./quickstart" description="From zero to first payment in five minutes." />

  <Card title="EasyProvider" href="./provider" description="Wire the SDK into your app and use the useEasy() hook." />

  <Card title="Elements" href="./elements" description="PCI-isolated card and bank inputs." />

  <Card title="Embedded Checkout" href="./embedded-checkout" description="Drop-in hosted checkout iframe." />

  <Card title="Examples" href="./examples/vite-spa" description="Runnable Vite SPA and Next.js apps." />
</Cards>


# Installation (/docs/sdks/react/installation)



## Prerequisites [#prerequisites]

* **Node.js** 22 or later (matches the `engines.node` constraint in the package).
* **React** 18 or 19. `react` and `react-dom` are peer dependencies.
* A bundler that supports ES modules. Vite, Next.js, Remix, Webpack 5, and Rspack all work without configuration.
* An Easy Labs publishable API key. Test keys are prefixed with `sk_test_` and route to the sandbox environment automatically; live keys route to production.

## Install the package [#install-the-package]



<Tabs items="['npm', 'pnpm', 'yarn', 'bun']">
  <Tab value="npm">
    ```bash
    npm install @easylabs/react react react-dom
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add @easylabs/react react react-dom
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @easylabs/react react react-dom
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @easylabs/react react react-dom
    ```
  </Tab>
</Tabs>

The package is published as a dual ESM/CJS module with TypeScript declarations and is side-effect-free, so unused exports tree-shake cleanly.

## Verify the install [#verify-the-install]

Wrap your app in `EasyProvider` and exercise the SDK with a real call — `EasyProvider` runs key validation and Basis Theory session setup in an effect and **swallows** any failure (it logs `EasyProvider initialization failed:` to the console but the component still mounts). A successful mount alone does not prove the SDK is wired up; you need to either watch the console or, better, trigger an API call (e.g. `getProducts()`) or a tokenization attempt.

```tsx title="src/App.tsx"
import { EasyProvider, useEasy } from "@easylabs/react";

function StatusCheck() {
  const { getProducts } = useEasy();
  return <button onClick={() => getProducts().then(console.log)}>Ping</button>;
}

export default function App() {
  return (
    <EasyProvider apiKey={import.meta.env.VITE_EASY_API_KEY}>
      <StatusCheck />
    </EasyProvider>
  );
}
```

Open the browser console and click **Ping** — you should see an `ApiResponse<ProductData[]>` payload. If `apiKey` is missing or invalid, `EasyProvider` logs `EasyProvider initialization failed:` and `useEasy` calls that depend on tokenization (e.g. `checkout`, `createPaymentInstrument`) will throw.

## Next steps [#next-steps]

* [Quickstart](./quickstart) — render your first payment.
* [EasyProvider](./provider) — the SDK's entry point.


# EasyProvider (/docs/sdks/react/provider)



`EasyProvider` is the entry point for `@easylabs/react`. It owns three things:

1. The `EasyApiClient` instance used by every method on `useEasy()`.
2. A live Basis Theory session, opened on mount and used to tokenize card and bank-account elements without their values touching your server.
3. The `BasisTheoryProvider` context that the `<CardElement>` family needs to render. All elements in your tree must be descendants of `EasyProvider` for tokenization to work.

Mount it once, as high in your component tree as is practical. In Next.js App Router, it must be inside a Client Component (`"use client"`).

## Props [#props]

| Prop                 | Type        | Required | Description                                                                                                                            |
| -------------------- | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`             | `string`    | yes      | Your Easy Labs publishable API key. Keys starting with `sk_test_` route to the sandbox API; all others route to production.            |
| `children`           | `ReactNode` | yes      | Your app tree.                                                                                                                         |
| `__internal_api_url` | `string`    | no       | **Internal.** Override the API base URL. Not part of the public API; intended for Easy Labs development and may change without notice. |

`EasyProvider` resolves the API URL in this order: `__internal_api_url` if provided, otherwise `https://sandbox-api.itseasy.co/v1/api` for `sk_test_` keys and `https://api.itseasy.co/v1/api` for everything else. Production apps should never set the internal override.

## Example [#example]

```tsx title="src/main.tsx"
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { EasyProvider } from "@easylabs/react";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <EasyProvider apiKey={import.meta.env.VITE_EASY_API_KEY}>
      <App />
    </EasyProvider>
  </StrictMode>,
);
```

For Next.js App Router, the provider must live in a Client Component that is then rendered from your root layout:

```tsx title="src/components/Providers.tsx"
"use client";

import { EasyProvider } from "@easylabs/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <EasyProvider apiKey={process.env.NEXT_PUBLIC_EASY_API_KEY ?? ""}>
      {children}
    </EasyProvider>
  );
}
```

```tsx title="src/app/layout.tsx"
import { Providers } from "@/components/Providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

## The `useEasy()` hook [#the-useeasy-hook]

`useEasy()` returns an object with every API method on the SDK. Calling it outside an `EasyProvider` throws `useEasy must be used within an EasyProvider`.

The methods fall into a few groups:

### Customers [#customers]

| Method                                  | Description                                    |
| --------------------------------------- | ---------------------------------------------- |
| `createCustomer(data)`                  | Create a customer record.                      |
| `updateCustomer(id, data)`              | Patch a customer.                              |
| `getCustomer(id)`                       | Fetch a single customer.                       |
| `getCustomers(params?)`                 | List customers.                                |
| `getCustomerPaymentInstruments(id)`     | List a customer's saved cards / bank accounts. |
| `getCustomerOrders(id, params?)`        | List a customer's orders.                      |
| `getCustomerSubscriptions(id, params?)` | List a customer's subscriptions.               |
| `getCustomerWallets(id, params?)`       | List a customer's crypto wallets.              |

### Payment instruments [#payment-instruments]

| Method                              | Description                                                                 |
| ----------------------------------- | --------------------------------------------------------------------------- |
| `tokenizePaymentInstrument(data)`   | Tokenize element refs into a Basis Theory token ID; rarely called directly. |
| `createPaymentInstrument(data)`     | Tokenize and persist a new card or bank account against a customer.         |
| `updatePaymentInstrument(id, data)` | Patch a saved instrument.                                                   |

### Transfers, products, prices, orders, subscriptions, settlements [#transfers-products-prices-orders-subscriptions-settlements]

`createTransfer`, `getTransfers`, `getTransfer`, `updateTransferTags`,
`getProducts`, `getProduct`, `getProductWithPrice`, `getProductWithPrices`, `createProduct`, `updateProduct`, `archiveProduct`,
`getProductPrices`, `getProductPrice`, `createProductPrice`, `updateProductPrice`, `archiveProductPrice`,
`getOrders`, `getOrder`, `updateOrderTags`,
`getSubscriptions`, `getSubscription`, `createSubscription`, `updateSubscription`, `cancelSubscription`,
`getSettlements`, `getSettlement`, `closeSettlement` —
all proxy directly to `EasyApiClient` and return `ApiResponse<T>`.

### One-shot checkout [#one-shot-checkout]

| Method                           | Description                                                                                                                                                                                                      |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `checkout(data)`                 | The recommended end-to-end checkout call. Tokenizes a card / bank element (or accepts an existing instrument ID), creates a customer if `customer_creation: true`, and creates the order in a single round trip. |
| `anonCheckout(data)`             | **Deprecated.** Use `checkout` with `customer_creation: true`.                                                                                                                                                   |
| `checkoutExistingCustomer(data)` | **Deprecated.** Use `checkout` with `customer_creation: false` and `identity_id`.                                                                                                                                |

### Payment links and embedded checkout [#payment-links-and-embedded-checkout]

| Method                                | Description                                                                                           |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `createPaymentLink(data)`             | Create a hosted payment link.                                                                         |
| `createEmbeddedCheckoutSession(data)` | Create a session whose `client_secret` powers the [`<EmbeddedCheckout>`](./embedded-checkout) iframe. |
| `getEmbeddedCheckoutSession(id)`      | Poll an embedded checkout session's status.                                                           |
| `getCryptoPaymentStatus(id)`          | Poll the on-chain status of a crypto payment in an embedded session.                                  |

Every method returns either a typed `ApiResponse<T>` envelope (`{ success, data }` or `{ success: false, message }`) or, for the few that wrap multiple steps (`checkout`, `anonCheckout`, `checkoutExistingCustomer`), the underlying API response. See the [TypeScript reference](./typescript) for the exported types.

## Hooks that depend on this provider [#hooks-that-depend-on-this-provider]

* [`useEasy()`](#the-useeasy-hook) — the API surface above.
* [`useEmbeddedCheckout()`](./embedded-checkout#useembeddedcheckout) — read iframe lifecycle status when wrapped in `<EmbeddedCheckoutProvider>`.

The Basis Theory `<CardElement>`, `<CardNumberElement>`, `<CardExpirationDateElement>`, `<CardVerificationCodeElement>`, and `<TextElement>` re-exports also require `EasyProvider` as an ancestor — they read the Basis Theory client from the context that `EasyProvider` installs.


# Quickstart (/docs/sdks/react/quickstart)



This walkthrough wires `@easylabs/react` into a fresh app, mounts a card element, and runs a one-shot checkout that creates a customer, tokenizes a card, and charges it — all from the browser, with the card number never touching your server.

## 1. Get your API keys [#1-get-your-api-keys]

Open the [Easy Labs dashboard](https://dashboard.itseasy.co) and copy your publishable API key from the **Developers** tab.

* Test keys start with `sk_test_` and automatically point the SDK at `https://sandbox-api.itseasy.co/v1/api`.
* Live keys point at `https://api.itseasy.co/v1/api`.

There is no separate "publishable" vs. "secret" key for the React SDK — the key you paste into `EasyProvider` is the one used for both API calls and Basis Theory session creation, so use a test key in development.

Store it as an environment variable. For Vite, that's `VITE_EASY_API_KEY`; for Next.js, `NEXT_PUBLIC_EASY_API_KEY`.

## 2. Initialize the SDK [#2-initialize-the-sdk]

Mount `EasyProvider` once at the top of your tree.

```tsx title="src/main.tsx"
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { EasyProvider } from "@easylabs/react";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <EasyProvider apiKey={import.meta.env.VITE_EASY_API_KEY}>
      <App />
    </EasyProvider>
  </StrictMode>,
);
```

`EasyProvider` validates the key, opens a Basis Theory session, and exposes the entire API surface through `useEasy()`. See [EasyProvider](./provider) for the full prop and hook reference.

## 3. Make your first call [#3-make-your-first-call]

Render a `CardElement` and call `checkout` from `useEasy()`. The `cardElement` ref is passed straight into the `source` — the SDK handles tokenization and charge creation in a single call.

```tsx title="src/App.tsx"
import { CardElement, useEasy, type ICardElement } from "@easylabs/react";
import { useRef, useState } from "react";

export default function App() {
  const { checkout } = useEasy();
  const cardRef = useRef<ICardElement>(null);
  const [status, setStatus] = useState<"idle" | "loading" | "ok" | "err">("idle");
  const [orderId, setOrderId] = useState<string>();

  async function onSubmit(e: React.FormEvent) {
    e.preventDefault();
    setStatus("loading");
    try {
      const res = await checkout({
        customer_creation: true,
        customer_details: {
          first_name: "Ada",
          last_name: "Lovelace",
          email: "ada@example.com",
        },
        line_items: [{ price_id: "price_123", quantity: 1 }],
        source: {
          type: "PAYMENT_CARD",
          name: "Ada Lovelace",
          cardElement: cardRef,
        },
      });
      if (res.success) {
        setOrderId(res.data.orderId);
        setStatus("ok");
      } else {
        setStatus("err");
      }
    } catch {
      setStatus("err");
    }
  }

  return (
    <form onSubmit={onSubmit}>
      <CardElement ref={cardRef} id="card" />
      <button type="submit" disabled={status === "loading"}>
        {status === "loading" ? "Processing…" : "Pay"}
      </button>
      {status === "ok" && <p>Order {orderId} created.</p>}
      {status === "err" && <p>Payment failed.</p>}
    </form>
  );
}
```

Replace `price_123` with a real price ID from your dashboard.

## 4. Handle the response [#4-handle-the-response]

`checkout` returns an `ApiResponse<CheckoutResult>`:

* **Success** — `res.success === true`. `res.data` contains `orderId` (the new order's id), an optional `transfer` for one-shot payments, and `subscriptions` (an array of created subscription rows when the line items include recurring prices). The customer and payment-instrument records are not echoed back here — fetch them with `getCustomer(...)` or `getCustomerPaymentInstruments(...)` if you need them.
* **API error** — `res.success === false` with a `message` field. Surface it to the user.
* **Tokenization or network error** — `checkout` throws. Wrap the call in `try/catch`; the example above does this.

Test cards live in the [Easy Labs dashboard](https://dashboard.itseasy.co) under **Developers → Test data**. Use `4111 1111 1111 1111` with any future expiry and any 3-digit CVC for an approved test charge.

## What's next [#whats-next]

* [EasyProvider](./provider) — every method you can pull off `useEasy()`.
* [Elements](./elements) — split-field cards, bank accounts, and styling.
* [Embedded Checkout](./embedded-checkout) — skip the form-building entirely with the hosted iframe.
* [Examples](./examples/vite-spa) — full Vite SPA and Next.js apps you can clone and run.


# TypeScript (/docs/sdks/react/typescript)



`@easylabs/react` is written in TypeScript and ships with full `.d.ts` declarations. The package is built against TypeScript 5.9 with `strict: true`; consumer projects on TypeScript 5.0+ should work without configuration changes.

Every type from `@easylabs/common` and every element type from `@basis-theory/react-elements` is re-exported from the package root, so you almost never need to import from anywhere else.

## Public types [#public-types]

### Provider configuration [#provider-configuration]

| Type            | Description                                                                          |
| --------------- | ------------------------------------------------------------------------------------ |
| `ClientOptions` | Optional `apiKey` field; convenience type for wrapping the SDK in your own provider. |

### Customers [#customers]

| Type             | Description                                                     |
| ---------------- | --------------------------------------------------------------- |
| `CreateCustomer` | Body for `createCustomer` and `customer_details` in `checkout`. |
| `CustomerData`   | Customer record returned by `getCustomer`.                      |
| `Address`        | Postal address used by customers and card AVS.                  |

### Payment instruments [#payment-instruments]

| Type                                 | Description                                                                                                                                                     |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CreatePaymentInstrumentParams`      | Discriminated union for `createPaymentInstrument` (`PAYMENT_CARD` or `BANK_ACCOUNT`). Card variants accept either a single `cardElement` ref or the split trio. |
| `CreatePaymentInstrumentTokenParams` | Bare-tokenization variant for `tokenizePaymentInstrument`.                                                                                                      |
| `CreatePaymentInstrument`            | Server-shaped payload (used internally; you usually want `CreatePaymentInstrumentParams`).                                                                      |
| `PaymentInstrumentData`              | Returned instrument record.                                                                                                                                     |
| `FinixPaymentInstrumentData`         | Returned shape from `createPaymentInstrument` (Finix-backed).                                                                                                   |
| `AccountType`                        | `"PERSONAL_CHECKING" \| "BUSINESS_CHECKING" \| "PERSONAL_SAVINGS" \| "BUSINESS_SAVINGS"`.                                                                       |

### Element refs [#element-refs]

Re-exported from `@basis-theory/react-elements`:

| Type                           | Use with                                                |
| ------------------------------ | ------------------------------------------------------- |
| `ICardElement`                 | `<CardElement ref={...} />`                             |
| `ICardNumberElement`           | `<CardNumberElement ref={...} />`                       |
| `ICardExpirationDateElement`   | `<CardExpirationDateElement ref={...} />`               |
| `ICardVerificationCodeElement` | `<CardVerificationCodeElement ref={...} />`             |
| `ITextElement`                 | `<TextElement ref={...} />` (routing / account numbers) |

### Products, prices, subscriptions, transfers [#products-prices-subscriptions-transfers]

`CreateProduct`, `ProductData`, `CreatePrice`, `PriceData`, `IntervalType`,
`CreateSubscription`, `SubscriptionData`, `CreateTransfer`, `TransferData`, `OrderData` — direct shapes for the matching API endpoints.

### Checkout and embedded checkout [#checkout-and-embedded-checkout]

| Type                            | Description                                                                           |
| ------------------------------- | ------------------------------------------------------------------------------------- |
| `CreateCheckoutSession`         | Server-side checkout body.                                                            |
| `CreateEmbeddedCheckoutSession` | Body for `createEmbeddedCheckoutSession`.                                             |
| `EmbeddedCheckoutSessionData`   | Response containing `client_secret`, `url`, `amount_total`, `currency`, `expires_at`. |
| `EmbeddedCheckoutSessionStatus` | Returned by `getEmbeddedCheckoutSession`.                                             |

### API envelope [#api-envelope]

| Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ApiResponse<T>` | `{ success: boolean; message?: string; data: T }`. Returned by every direct API method on `useEasy()`. `data` is always present; `success` is a plain boolean flag and is **not** a TypeScript discriminant — checking it does not narrow the type of `data` away. Treat `success === false` as a server-reported failure (read `message` for context) and any thrown error as a network or tokenization failure. |

To pull the type of a specific `useEasy()` method, infer it from the hook:

```ts
import { useEasy } from "@easylabs/react";

type CheckoutArgs = Parameters<ReturnType<typeof useEasy>["checkout"]>[0];
type CheckoutResult = Awaited<ReturnType<ReturnType<typeof useEasy>["checkout"]>>;
```

## Module augmentation [#module-augmentation]

`@easylabs/react` does not declare any global JSX or framework augmentations, so there's nothing to extend. Element refs use the underlying Basis Theory interfaces — extend those through `@basis-theory/react-elements` if you need to add typed events.

If you wrap the SDK in your own provider or hook (common for mocking in tests), use `ClientOptions` and the existing types directly rather than augmenting module declarations.


# Wallet Checkout (/docs/sdks/react/wallet-checkout)



Today, wallet-native flows on `@easylabs/react` are delivered through the [Embedded Checkout](./embedded-checkout) iframe — there is no standalone `<ApplePayButton>` or `<GooglePayButton>` export.

## Through Embedded Checkout [#through-embedded-checkout]

`createEmbeddedCheckoutSession` accepts a `payment_methods` array. Crypto wallet payments are first-class:

```ts
const res = await easy.createEmbeddedCheckoutSession({
  line_items: [{ price_id: "price_123", quantity: 1 }],
  mode: "payment",
  payment_methods: ["card", "crypto"],
  success_url: "https://example.com/checkout/success",
});
```

When a crypto payment confirms on-chain, the iframe emits `easylabs:crypto_confirmed`, which `<EmbeddedCheckoutProvider>` surfaces through `onSuccess` with a `tx_signature`. You can also poll status from your code with `useEasy().getCryptoPaymentStatus(sessionId)`.

See [Embedded Checkout → Customization](./embedded-checkout#customization) for the full session options.

## Native Apple Pay and Google Pay [#native-apple-pay-and-google-pay]

{/* TODO: Confirm whether the React SDK exposes (or plans to expose) standalone Apple Pay / Google Pay buttons distinct from Embedded Checkout, and document merchant ID / domain verification requirements once that surface lands. */}

There is currently no dedicated `<ApplePayButton>` or `<GooglePayButton>` component in `@easylabs/react`. Use the embedded checkout flow above and rely on the hosted page's wallet support.


# Elements (/docs/sdks/react-native/elements)



Elements are PCI-scoped native input components. Card data is captured
inside the element and never enters your app's JavaScript or native heap —
only a Basis Theory token reference does. The same engine powers
`@easylabs/react` and `@easylabs/browser`; on React Native it renders as
truly native inputs (not a `WebView`).

## Available elements [#available-elements]

| Component                     | Captures                      |
| ----------------------------- | ----------------------------- |
| `CardNumberElement`           | PAN with brand auto-detection |
| `CardExpirationDateElement`   | MM / YY                       |
| `CardVerificationCodeElement` | CVC, length-aware per brand   |
| `TextElement`                 | Generic sensitive text input  |

{/* TODO: Note any RN-specific props vs. the React equivalents. */}

## Setup [#setup]

`EasyProvider` already wraps `BasisTheoryProvider` from
`@basis-theory/react-native-elements`, so elements work anywhere inside
your provider tree.

{/* TODO: Minimal screen showing imports + render of the three card elements. */}

## Refs and tokenization [#refs-and-tokenization]

Hold a `BTRef` per element and pass them to the tokenization call when the
form submits. Card data never leaves the element.

{/* TODO: Code sample using `useRef<BTRef>(null)` and the tokenization hook. */}

## Styling [#styling]

Elements accept React Native `style` props directly — no CSS class
indirection. Match your app's design system the same way you'd style a
`<TextInput>`.

{/* TODO: Style example with focus / error states. */}

## Validation [#validation]

{/* TODO: Built-in validation events (`onChange`, completeness, brand), how to surface errors to users. */}

## Related [#related]

* [EasyProvider](./provider) — required ancestor
* [Wallet Checkout](./wallet-checkout) — Apple Pay / Google Pay flows
* [TypeScript](./typescript) — `BTRef`, `InputBTRef`, and element prop types


# Embedded Checkout (/docs/sdks/react-native/embedded-checkout)



**Embedded Checkout is web-only by design.** The hosted checkout page is an
iframe surface; `@easylabs/react` and `@easylabs/browser` mount it natively
in browsers. There is no `EmbeddedCheckout` component in
`@easylabs/react-native`, and there will not be one — wrapping the iframe
in a `WebView` produces a degraded, inconsistent experience and is risky
under App Store and Play Store review for primary payment flows.

## What to use instead [#what-to-use-instead]

Build native checkout with the SDK's primitives:



<Cards>
  <Card title="Elements" href="./elements" description="Card number, expiration, and CVC inputs — same Basis Theory engine as the web SDK, rendered natively." />

  <Card title="Wallet Checkout" href="./wallet-checkout" description="Apple Pay (iOS) and Google Pay (Android) — the native equivalent of a hosted checkout flow." />
</Cards>

## If you really need the web checkout in a native app [#if-you-really-need-the-web-checkout-in-a-native-app]

Don't ship a `WebView`-wrapped Embedded Checkout to production. The known
issues — keyboard handling, payment-sheet integration, scrolling, latency,
review-process risk — outweigh any reuse benefit. If you need the hosted
page for a one-off scenario (testing, internal tooling, a feature flag
toggle), use React Native's built-in
[`react-native-webview`](https://github.com/react-native-webview/react-native-webview)
directly with the published checkout URL. We don't ship it as a first-party
component because we don't recommend it.


# React Native SDK (/docs/sdks/react-native)



`@easylabs/react-native` is the official Easy Labs SDK for React Native.

It gives you a single `EasyProvider` plus a typed `useEasy()` hook to drive every customer, payment-instrument, transfer, product, subscription, and checkout call against the Easy API — and exposes Basis Theory's native iOS/Android input components (`CardNumberElement`, `CardExpirationDateElement`, `CardVerificationCodeElement`, `TextElement`) for PCI-scoped capture of card and bank data. Card data is read inside the native input and exchanged for a Basis Theory token; your app's JavaScript never sees the PAN, CVC, or full account number.

It's built for production React Native apps (Expo or bare-RN, New Architecture compatible) shipping payments on iOS and Android. If you want hosted, browser-style Embedded Checkout, that ships in `@easylabs/react` for the web — on React Native, build native flows with [Elements](./elements) or [Wallet Checkout](./wallet-checkout) instead.

## Quick links [#quick-links]



<Cards>
  <Card title="Installation" href="./installation" description="Add the SDK to your project." />

  <Card title="Quickstart" href="./quickstart" description="From zero to first payment in five minutes." />

  <Card title="Elements" href="./elements" description="Native, PCI-scoped card and bank inputs." />

  <Card title="Wallet Checkout" href="./wallet-checkout" description="Apple Pay and Google Pay." />
</Cards>


# Installation (/docs/sdks/react-native/installation)



## Prerequisites [#prerequisites]

* **React** `>= 18.0.0`
* **React Native** `>= 0.79.0`
* **Node.js** `>= 22` for tooling (Metro, Expo CLI)
* An Easy Labs API key from the [dashboard](https://app.itseasy.co) — sandbox keys start with `sk_test_`, production keys do not

The SDK works with both **Expo** (managed or prebuild) and **bare React Native**. It's compatible with the New Architecture (`newArchEnabled: true`).

`@basis-theory/react-native-elements` is bundled as a direct dependency — you do **not** install it yourself.

## Install the package [#install-the-package]



<Tabs items="['pnpm', 'npm', 'yarn', 'bun']">
  <Tab value="pnpm">
    ```sh
    pnpm add @easylabs/react-native
    ```
  </Tab>

  <Tab value="npm">
    ```sh
    npm install @easylabs/react-native
    ```
  </Tab>

  <Tab value="yarn">
    ```sh
    yarn add @easylabs/react-native
    ```
  </Tab>

  <Tab value="bun">
    ```sh
    bun add @easylabs/react-native
    ```
  </Tab>
</Tabs>

### iOS native build [#ios-native-build]

After installing, run pod install so Basis Theory's native iOS module links against your project:

```sh
cd ios && pod install && cd ..
```

On Expo prebuild and bare RN, this is required once per dependency change. On Expo Go (managed without prebuild), Basis Theory native modules are not available — use Expo's prebuild or a development build.

{/* TODO: Confirm minimum iOS deployment target and Android `minSdkVersion` required by `@basis-theory/react-native-elements` 2.5.x. */}

## Verify the install [#verify-the-install]

Wrap your app's root with `EasyProvider` and read a value from `useEasy()`:

```tsx title="App.tsx"
import { EasyProvider, useEasy } from '@easylabs/react-native';
import { Text, View } from 'react-native';

function Probe() {
  const { getCustomers } = useEasy();
  return <Text>Easy SDK loaded: {typeof getCustomers}</Text>;
}

export default function App() {
  return (
    <EasyProvider apiKey={process.env.EXPO_PUBLIC_EASY_API_KEY!}>
      <View style={{ flex: 1, justifyContent: 'center', padding: 24 }}>
        <Probe />
      </View>
    </EasyProvider>
  );
}
```

If the screen renders `Easy SDK loaded: function`, the SDK initialized, validated your API key, and provisioned a Basis Theory session.

> **Expo:** put your key in `EXPO_PUBLIC_EASY_API_KEY` so it's exposed to the JS bundle. &#x2A;*Bare RN:** use `react-native-config`, `react-native-dotenv`, or your own native config — the SDK only cares that you pass a string into `apiKey`.

## Next steps [#next-steps]

* [Quickstart](./quickstart) — render your first payment.
* [EasyProvider](./provider) — the SDK's entry point.
* [Elements](./elements) — native card and bank inputs.


# EasyProvider (/docs/sdks/react-native/provider)



`EasyProvider` is the entry point of `@easylabs/react-native`. It does three things on mount:

1. Validates your API key against the Easy API.
2. Creates a Basis Theory session bound to that key.
3. Wraps its children in `BasisTheoryProvider` so all SDK-exported elements (`CardNumberElement`, etc.) work without extra setup.

Mount it once, as high in your tree as possible — typically at the root of your app, above your navigator. Everything inside can call [`useEasy()`](#hooks-that-depend-on-this-provider).

## Props [#props]

| Prop                 | Type        | Required | Description                                                                                                                                                                                                                   |
| -------------------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`             | `string`    | yes      | Your Easy publishable API key. The SDK selects sandbox vs. production from the key prefix (`sk_test_` → sandbox, otherwise production).                                                                                       |
| `children`           | `ReactNode` | yes      | Your app tree.                                                                                                                                                                                                                |
| `__internal_api_url` | `string`    | no       | Internal override for the Easy API base URL. Reserved for Easy Labs' own development and testing. **Not part of the public API and may change without notice** — do not use this to point at a custom or staging environment. |
| `__dev`              | `boolean`   | no       | Legacy flag. Currently a no-op for URL routing — use `__internal_api_url` if you need to override the endpoint. Will be removed in a future release.                                                                          |

The provider does not accept locale, theme, currency, or analytics props — those are concerns of the components you render inside it.

## Example [#example]

```tsx title="App.tsx"
import { EasyProvider } from '@easylabs/react-native';
import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import CheckoutScreen from './src/screens/CheckoutScreen';
import HomeScreen from './src/screens/HomeScreen';

const Stack = createNativeStackNavigator();

export default function App() {
  return (
    <EasyProvider apiKey={process.env.EXPO_PUBLIC_EASY_API_KEY!}>
      <NavigationContainer>
        <Stack.Navigator>
          <Stack.Screen name="Home" component={HomeScreen} />
          <Stack.Screen name="Checkout" component={CheckoutScreen} />
        </Stack.Navigator>
      </NavigationContainer>
    </EasyProvider>
  );
}
```

### Re-mounting [#re-mounting]

`EasyProvider` validates and creates a session on every mount. Avoid unmounting and re-mounting it on every navigation — keep it at the root so the session is reused for the lifetime of the app session.

### Initialization errors [#initialization-errors]

If validation or session creation fails, the error is logged to `console.error` with the prefix `EasyProvider initialization failed:` and the provider continues to render its children. Calls into `useEasy()` that require an initialized Basis Theory session (anything that tokenizes card or bank data — `checkout`, `createPaymentInstrument`, `tokenizePaymentInstrument`) will throw `"Basis Theory client is not initialized"`. Plain API methods (`getCustomers`, `getProducts`, etc.) work as soon as `apiClient` is constructed.

The SDK does **not** auto-retry initialization. `initClient()` only runs when `EasyProvider` mounts or when its `apiKey` prop changes. If init fails (e.g. transient network blip during app start), tokenizing calls keep throwing until you trigger a re-init by one of:

* Re-mounting `EasyProvider` (e.g. by toggling a key on the provider element, or unmounting and re-rendering the subtree that owns it).
* Restarting the app.
* Changing the `apiKey` prop to a new value (a no-op string change does not re-trigger init — the prop must actually differ).

If you need automatic recovery, wrap your app in a small effect that bumps a `key` prop on `EasyProvider` after a window of failed tokenizations, or surface a "retry" affordance in your UI that does the same.

## Hooks that depend on this provider [#hooks-that-depend-on-this-provider]

### `useEasy()` [#useeasy]

The single hook surface for the SDK. Returns the typed API client plus the tokenizing checkout helpers. Must be called inside an `EasyProvider`; otherwise it throws `"useEasy must be used within an EasyProvider"`.

```tsx
import { useEasy } from '@easylabs/react-native';

function MyComponent() {
  const {
    // Customers
    createCustomer, updateCustomer, getCustomer, getCustomers,
    getCustomerPaymentInstruments, getCustomerOrders,
    getCustomerSubscriptions, getCustomerWallets,

    // Payment instruments
    tokenizePaymentInstrument, createPaymentInstrument, updatePaymentInstrument,

    // Transfers
    createTransfer, getTransfers, getTransfer, updateTransferTags,

    // Products & prices
    getProducts, getProduct, getProductWithPrice, getProductWithPrices,
    createProduct, updateProduct, archiveProduct,
    getProductPrices, getProductPrice, createProductPrice,
    updateProductPrice, archiveProductPrice,

    // Orders, subscriptions, settlements
    getOrders, getOrder, updateOrderTags,
    getSubscriptions, getSubscription, createSubscription,
    updateSubscription, cancelSubscription,
    getSettlements, getSettlement, closeSettlement,

    // Checkout
    checkout,
    createPaymentLink,

    // Deprecated
    anonCheckout, checkoutExistingCustomer,
  } = useEasy();
}
```

See the [Quickstart](./quickstart) for `checkout()` end-to-end and [Elements](./elements) for the tokenization helpers.

### Basis Theory hooks [#basis-theory-hooks]

`@easylabs/react-native` does not re-export `useBasisTheory` from `@basis-theory/react-native-elements`. If you need lower-level control over Basis Theory tokens, import it directly from `@basis-theory/react-native-elements` — the `BasisTheoryProvider` is already in the tree, so the hook will resolve the same client `EasyProvider` is using.

{/* TODO: Decide whether `useBasisTheory` should be re-exported from `@easylabs/react-native` for first-class advanced use, or whether the direct-import escape hatch is the intended public contract. */}


# Quickstart (/docs/sdks/react-native/quickstart)



This guide takes a fresh React Native app to a working card checkout — capturing card data in native, PCI-scoped inputs, tokenizing it via Basis Theory, and creating an order through the Easy API.

## 1. Get your API keys [#1-get-your-api-keys]

Create an application in the [Easy dashboard](https://app.itseasy.co) and copy your **publishable** API key.

* Sandbox keys start with `sk_test_` and route to `https://sandbox-api.itseasy.co/v1/api`.
* Live keys do not have the `sk_test_` prefix and route to `https://api.itseasy.co/v1/api`.

The SDK picks the right environment automatically from the key prefix — you do not configure URLs.

> Only ship publishable keys to mobile clients. Secret keys belong on your server. See the [backend SDK](/docs/backend/node) for server-side calls.

## 2. Initialize the SDK [#2-initialize-the-sdk]

Wrap your root component with `EasyProvider`:

```tsx title="App.tsx"
import { EasyProvider } from '@easylabs/react-native';
import CheckoutScreen from './src/screens/CheckoutScreen';

export default function App() {
  return (
    <EasyProvider apiKey={process.env.EXPO_PUBLIC_EASY_API_KEY!}>
      <CheckoutScreen />
    </EasyProvider>
  );
}
```

`EasyProvider` validates your API key against the Easy API on mount and creates a short-lived Basis Theory session under the hood. All children inside the provider can call `useEasy()`.

## 3. Make your first call [#3-make-your-first-call]

Build a screen that captures card data with the three native elements and submits a checkout:

```tsx title="src/screens/CheckoutScreen.tsx"
import {
  type BTDateRef,
  type BTRef,
  CardExpirationDateElement,
  CardNumberElement,
  CardVerificationCodeElement,
  useEasy,
} from '@easylabs/react-native';
import { useRef, useState } from 'react';
import { Alert, Button, Text, View } from 'react-native';

export default function CheckoutScreen() {
  const { checkout } = useEasy();
  const cardNumberRef = useRef<BTRef>(null);
  const cardExpirationRef = useRef<BTDateRef>(null);
  const cardCvcRef = useRef<BTRef>(null);
  const [loading, setLoading] = useState(false);

  const handleSubmit = async () => {
    setLoading(true);
    try {
      const result = await checkout({
        customer_creation: true,
        customer_details: {
          first_name: 'Jane',
          last_name: 'Doe',
          email: 'jane@example.com',
        },
        source: {
          type: 'PAYMENT_CARD',
          name: 'Jane Doe',
          cardNumberElement: cardNumberRef,
          cardExpirationDateElement: cardExpirationRef,
          cardVerificationCodeElement: cardCvcRef,
        },
        line_items: [{ price_id: 'price_123', quantity: 1 }],
      });

      if (result.success) {
        Alert.alert('Paid', `Order ${result.data.orderId}`);
      }
    } catch (err) {
      Alert.alert('Error', err instanceof Error ? err.message : 'Failed');
    } finally {
      setLoading(false);
    }
  };

  return (
    <View style={{ padding: 16, gap: 12 }}>
      <Text>Card number</Text>
      <CardNumberElement btRef={cardNumberRef} />

      <Text>Expiration</Text>
      <CardExpirationDateElement btRef={cardExpirationRef} />

      <Text>CVC</Text>
      <CardVerificationCodeElement btRef={cardCvcRef} />

      <Button title={loading ? 'Processing…' : 'Pay'} onPress={handleSubmit} disabled={loading} />
    </View>
  );
}
```

Use the test card `4242 4242 4242 4242`, any future expiration date, and any 3-digit CVC against a sandbox key.

## 4. Handle the response [#4-handle-the-response]

`checkout()` resolves with the standard Easy API response shape:

```ts
{
  success: true,
  data: {
    orderId: 'ord_…',
    // …additional fields from the checkout session
  }
}
```

Failures throw — wrap the call in `try`/`catch`. The thrown `Error.message` will tell you which step failed:

| Message contains                            | Cause                                                                                                                                                                                                     |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey is required`                        | `EasyProvider` was rendered without an `apiKey` prop.                                                                                                                                                     |
| `API key validation failed`                 | The key was rejected by the Easy API.                                                                                                                                                                     |
| `Card element reference is not set`         | A required element ref was `null` at submit time.                                                                                                                                                         |
| `Card expiration date is incomplete`        | The user did not finish typing MM / YY.                                                                                                                                                                   |
| `Failed to create payment instrument token` | Basis Theory tokenization failed (network / data).                                                                                                                                                        |
| `API request failed: …`                     | The Easy API returned a non-2xx response. Thrown as `EasyApiError`; check `err.status` (HTTP status) and `err.code` (Easy error code, if available) with `instanceof EasyApiError` for granular handling. |

## What's next [#whats-next]

* [EasyProvider](./provider) — every prop, every option.
* [Elements](./elements) — full element reference and styling.
* [Wallet Checkout](./wallet-checkout) — Apple Pay and Google Pay.
* [Examples → Expo](./examples/expo) — guided tour of the runnable example app.


# TypeScript (/docs/sdks/react-native/typescript)



`@easylabs/react-native` is written in TypeScript and built against [`@tsconfig/strictest`](https://github.com/tsconfig/bases/blob/main/bases/strictest.json). All exports ship with `.d.ts` files; no extra `@types/*` package is required.

## Public types [#public-types]

The package re-exports two upstream type sets, plus its own React Native-specific helper types.

### Re-exported from `@easylabs/common` [#re-exported-from-easylabscommon]

The full payments domain model. Pull these types when you need to type your own state, server responses, or wrapper utilities.

```ts
import type {
  // Responses
  ApiResponse,
  ErrorResponse,
  Paginated,
  PaginationParams,

  // Customers
  CreateCustomer,
  CustomerData,

  // Payment instruments
  CreatePaymentInstrument,
  CreatePaymentInstrumentBase,
  UpdatePaymentInstrument,
  PaymentInstrumentData,
  FinixPaymentInstrumentData,
  Address,
  AccountType,

  // Money movement
  CreateTransfer,
  TransferData,

  // Catalog
  CreateProduct,
  CreatePrice,
  ProductData,
  PriceData,

  // Subscriptions
  CreateSubscription,
  SubscriptionData,

  // Checkout
  CreateCheckoutSession,
} from '@easylabs/react-native';
```

### Re-exported from `@basis-theory/react-native-elements` [#re-exported-from-basis-theoryreact-native-elements]

The element ref types. You'll attach these to `useRef<…>(null)` calls in any component that captures card or bank data.

| Type           | Used for                                                                                                                                                 |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BTRef`        | Refs for `CardNumberElement`, `CardVerificationCodeElement`, and `TextElement`.                                                                          |
| `BTDateRef`    | Ref for `CardExpirationDateElement` (exposes `.month()` / `.year()` for tokenization).                                                                   |
| `InputBTRef`   | Underlying `{ id, format }` shape produced by element refs — useful when typing custom token payloads.                                                   |
| `ElementEvent` | Payload of `onChange`, `onFocus`, and `onBlur` element callbacks (`empty`, `complete`, `valid`, `errors`, `brand`, `cardLast4`, `cvcLength`, `cardBin`). |

```tsx
import { type BTDateRef, type BTRef, CardNumberElement } from '@easylabs/react-native';
import { useRef } from 'react';

const cardNumberRef = useRef<BTRef>(null);
const expirationRef = useRef<BTDateRef>(null);
```

### React Native-specific helper types [#react-native-specific-helper-types]

Defined in this package and exported from the package root.

| Type                                 | Description                                                                                                                                                          |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ClientOptions`                      | `{ apiKey?: string }` — minimal options shape exposed for forward compatibility.                                                                                     |
| `CreatePaymentInstrumentParams`      | Discriminated union of `PAYMENT_CARD` and `BANK_ACCOUNT` create payloads, with element refs in place of raw card or account data. Pass to `createPaymentInstrument`. |
| `CreatePaymentInstrumentTokenParams` | Slimmer ref-only union used by `tokenizePaymentInstrument` when you want a token but no instrument record yet.                                                       |

## Module augmentation [#module-augmentation]

The SDK does not currently expose any module-augmentation slots. To add app-specific tag schemas, prefer typing them at your own call sites:

```ts
import type { CreateCustomer } from '@easylabs/react-native';

type AppCustomerTags = { source: 'web' | 'ios' | 'android'; campaign?: string };

const data: CreateCustomer & { tags: AppCustomerTags } = {
  first_name: 'Jane',
  last_name: 'Doe',
  tags: { source: 'ios', campaign: 'launch-2026' },
};
```

{/* TODO: Document a public augmentation surface (e.g. `EasyTags`, `EasyMetadata`) once the API stabilizes a recommendation. */}


# Wallet Checkout (/docs/sdks/react-native/wallet-checkout)



Wallet Checkout is the native-mobile equivalent of [Embedded Checkout](./embedded-checkout)
on web. Users authorize a payment with Face ID / Touch ID / device
biometrics; the SDK exchanges the platform's encrypted payment token for
a Basis Theory token; your server completes the charge using the
[backend SDK](/docs/backend).

> **Status: API in design.** Apple Pay tokenization and Google Pay
> tokenization both go through Basis Theory's `/apple-pay` and
> `/google-pay` endpoints — that part is ready. The native button
> components and unified RN-side API live in `@easylabs/react-native` and
> are landing alongside the v0.2 release. This page documents the planned
> shape; some snippets may not run yet.

## Apple Pay (iOS) [#apple-pay-ios]

### Prerequisites [#prerequisites]

* An [Apple Merchant ID](https://developer.apple.com/help/account/configure-app-capabilities/create-a-merchant-id)
  registered in your Apple Developer account
* A
  [payment processing certificate](https://developer.apple.com/help/account/configure-app-capabilities/create-an-apple-pay-payment-processing-certificate)
  uploaded to the Easy Dashboard
* The Apple Pay capability enabled in your Xcode project
* A real device — Apple Pay does **not** work in the iOS Simulator beyond
  the sandbox sheet

{/* TODO: Walk through the dashboard certificate upload step with a screenshot. */}

### Flow [#flow]

```
[ApplePayButton] → user authorizes → onPaymentAuthorized
                                          ↓
                                   tokenize(applePayPayload)
                                          ↓
                                   Basis Theory /apple-pay
                                          ↓
                                   bt token → your server
                                          ↓
                            backend SDK creates the transfer
```

{/* TODO: Code block showing the `<ApplePayButton>` component, the `tokenize` call, and the server-side completion. */}

### Merchant Capabilities [#merchant-capabilities]

{/* TODO: 3DS, EMV, credit/debit, network constraints — what to set in PKPaymentRequest. */}

## Google Pay (Android) [#google-pay-android]

### Prerequisites [#prerequisites-1]

* A Google Pay merchant ID
* The
  [Google Pay API library](https://developers.google.com/pay/api/android/guides/setup)
  bundled with your build (`com.google.android.gms:play-services-wallet`)
* Production access requested in the
  [Google Pay & Wallet console](https://pay.google.com/business/console/)
* Sandbox testing works on any Android device with a Google account

{/* TODO: Note allowed payment methods, gateway parameters. */}

### Flow [#flow-1]

```
[GooglePayButton] → user authorizes → onPaymentDataResult
                                          ↓
                                   tokenize(googlePayPayload)
                                          ↓
                                   Basis Theory /google-pay
                                          ↓
                                   bt token → your server
                                          ↓
                            backend SDK creates the transfer
```

{/* TODO: Code block showing the `<GooglePayButton>` component and tokenize handler. */}

## Cross-platform helper [#cross-platform-helper]

{/* TODO: A `<WalletCheckoutButton>` convenience that renders the right native button per platform, hides the merchant-config plumbing, and forwards a single `onTokenized` callback. */}

## Server side [#server-side]

Apple Pay and Google Pay tokens behave like any other tokenized payment
instrument once they reach your server. See [Backend SDK → Transfers](/docs/backend/node/resources/transfers)
for completing the charge.

## Related [#related]

* [Elements](./elements) — manual card capture as the fallback flow
* [EasyProvider](./provider) — required ancestor
* [Embedded Checkout](./embedded-checkout) — why the iframe path isn't
  used on React Native


# Authentication (/docs/sdks/ruby/authentication)



Every request to Easy Labs is authenticated with a single secret API key
sent in the `X-Easy-Api-Key` header. The SDK attaches it for you on every
call, so you never construct headers by hand.

Two key prefixes exist:

| Prefix      | Environment | Base URL                                |
| ----------- | ----------- | --------------------------------------- |
| `sk_test_…` | Sandbox     | `https://sandbox-api.itseasy.co/v1/api` |
| `sk_live_…` | Live        | `https://api.itseasy.co/v1/api`         |

The SDK resolves the base URL from the key prefix — pass a `sk_test_…`
key and you're on sandbox, no flag required. Keys are server-side
secrets; never ship them to a browser or mobile app.

## Initializing with an API key [#initializing-with-an-api-key]

```ruby
require "easy_sdk"

client = EasyLabs::Client.new(api_key: ENV.fetch("EASY_API_KEY"))
```

The constructor calls `GET /validate-key` and raises
`EasyLabs::AuthenticationError` if the key is rejected. It also caches the
returned BasisTheory public key on `client.basis_theory_public_api_key`
for tokenisation flows.

### Overriding the base URL [#overriding-the-base-url]

For internal testing against a custom deployment you can override the
resolved URL with `internal_api_url:` — this skips the prefix-based
routing entirely:

```ruby
EasyLabs::Client.new(
  api_key:          ENV.fetch("EASY_API_KEY"),
  internal_api_url: "https://api.staging.example.com/v1/api"
)
```

Use this only when you need it; the default resolution is correct for
sandbox and live.

## Rotating keys [#rotating-keys]

Easy Labs API keys can be rotated without downtime. The recommended
flow:

1. Issue a new key in the dashboard. The old key keeps working.
2. Deploy a new build that reads the new key from
   `EASY_API_KEY` (or whatever env var you use). New
   `EasyLabs::Client` instances will validate against the new key.
3. Once the rollout is complete, revoke the old key in the dashboard.

Because `EasyLabs::Client` is a plain object, no global state needs to be
flushed — replacing the env var and restarting the process is enough.

## Multi-tenant authentication [#multi-tenant-authentication]

There is no global state in this SDK — `EasyLabs::Client` holds the API
key as instance state. Build one client per tenant and dispatch on it:

```ruby
class TenantClients
  def self.for(tenant)
    @clients ||= {}
    @clients[tenant.id] ||= EasyLabs::Client.new(api_key: tenant.easy_api_key)
  end
end

TenantClients.for(tenant).customers.create(email: "...")
```

Clients are cheap to keep around (a single HTTP wrapper plus lazily
constructed resource objects), but the constructor does make one
`/validate-key` call. Cache the instance per tenant rather than building
a new one on every request.

## Idempotency keys [#idempotency-keys]

For mutation endpoints, pass an `Idempotency-Key` header by setting it on
the underlying HTTP layer. See [Error handling › Idempotency keys](./error-handling#idempotency-keys).


# Error handling (/docs/sdks/ruby/error-handling)



Every non-2xx response from the API turns into a Ruby exception. All
exceptions inherit from `EasyLabs::Error`, so a single `rescue
EasyLabs::Error` catches everything; subclasses let you handle specific
failures explicitly.

```ruby
begin
  client.subscriptions.cancel("sub_xyz")
rescue EasyLabs::RateLimitError => e
  sleep(e.retry_after_seconds || 1)
  retry
rescue EasyLabs::AuthenticationError
  # api key was rejected — bail out
rescue EasyLabs::Error => e
  Rails.logger.error("[easy] #{e.status} #{e.code}: #{e.message}")
  raise
end
```

Every instance exposes:

| Attribute              | Type           | Meaning                                                    |
| ---------------------- | -------------- | ---------------------------------------------------------- |
| `#status`              | `Integer`      | HTTP status of the response.                               |
| `#code`                | `String, nil`  | Machine-readable code from the structured error envelope.  |
| `#details`             | `Object, nil`  | `details` payload from the envelope, when present.         |
| `#retry_after_seconds` | `Integer, nil` | Parsed from the `Retry-After` header (rate-limit only).    |
| `#raw`                 | `Object, nil`  | Full parsed JSON body, for fields the SDK doesn't surface. |

## Retryable vs. non-retryable [#retryable-vs-non-retryable]

The SDK maps HTTP status codes to specific subclasses so you can branch
on the exception class instead of inspecting status numbers:

| Status        | Class                           | Retryable?                                |
| ------------- | ------------------------------- | ----------------------------------------- |
| 400, 422      | `EasyLabs::InvalidRequestError` | No — fix the request.                     |
| 401           | `EasyLabs::AuthenticationError` | No — rotate the key.                      |
| 403           | `EasyLabs::PermissionError`     | No.                                       |
| 404           | `EasyLabs::NotFoundError`       | No.                                       |
| 409           | `EasyLabs::ConflictError`       | Sometimes — re-read state and decide.     |
| 429           | `EasyLabs::RateLimitError`      | Yes — sleep `retry_after_seconds`, retry. |
| 5xx           | `EasyLabs::ServerError`         | Yes — exponential backoff.                |
| anything else | `EasyLabs::Error`               | Inspect `#status`.                        |

The webhook verifier raises `EasyLabs::InvalidRequestError` with a
specific `#code` (`WEBHOOK_SIGNATURE_MISSING`,
`WEBHOOK_SIGNATURE_FORMAT_INVALID`, `WEBHOOK_SIGNATURE_MISMATCH`,
`WEBHOOK_BODY_INVALID_JSON`) so signature failures are distinguishable
from API 400s.

## Idempotency keys [#idempotency-keys]

The underlying HTTP layer accepts an `Idempotency-Key` header on every
request. Resource methods do not yet expose a public keyword for it —

{/* TODO: confirm whether public resource methods should accept `idempotency_key:` directly, or whether callers route through `client.http.request(...)`. */}

For now, the SDK never retries internally — every method makes exactly
one HTTP call. Implement idempotency in your own retry wrapper using a
stable key per logical operation.

## Network errors [#network-errors]

Underlying network failures (DNS resolution, connection refused, TLS
handshake, read timeouts) propagate as the original `Net::HTTP` /
`OpenSSL::SSL` / `SocketError` exceptions — they are not wrapped in
`EasyLabs::Error`. Rescue them at the boundary if you need to:

```ruby
begin
  client.transfers.create(amount: 1000, currency: "USD", source: "pi_…")
rescue EasyLabs::Error => e
  # API responded with a non-2xx
rescue Net::OpenTimeout, Net::ReadTimeout, SocketError => e
  # never reached the API
end
```

The default open + read timeout is **30 seconds**.


# Ruby SDK (/docs/sdks/ruby)



`easy-sdk (gem)` is the official Easy Labs SDK for Ruby. It exposes the full
Easy Labs platform — payments, subscriptions, invoicing, treasury, dunning,
disputes, and webhooks — as a single `EasyLabs::Client` whose resource
methods mirror the JSON API one-for-one.

The gem ships idiomatic Ruby on top of the same wire format as
[`@easylabs/node`](https://github.com/itseasyco/easy-sdk): keyword arguments
for every input, hashes with symbol keys for every response, and a typed
exception hierarchy under `EasyLabs::Error` for every non-2xx status.
There is no DSL, no ActiveRecord-style models, and no global state — the
client is a plain object you can pass around or instantiate per tenant.

## Quick links [#quick-links]



<Cards>
  <Card title="Installation" href="./installation" description="Add the SDK to your project." />

  <Card title="Quickstart" href="./quickstart" description="From zero to first payment in five minutes." />

  <Card title="Webhooks" href="./webhooks" description="Verify and react to platform events." />
</Cards>


# Installation (/docs/sdks/ruby/installation)



## Prerequisites [#prerequisites]

* Ruby **3.2 or newer** (the gemspec sets `required_ruby_version = ">= 3.2"`).
* An Easy Labs API key. Use a `sk_test_…` key against the sandbox or a
  `sk_live_…` key against production. The SDK picks the correct base URL
  from the prefix automatically.
* The gem depends on [`multipart-post`](https://rubygems.org/gems/multipart-post)
  (`~> 2.4`) for the file-upload paths (dispute evidence, recipient
  imports). Everything else uses Ruby's stdlib `Net::HTTP`.

## Install the package [#install-the-package]

With Bundler:

```ruby
# Gemfile
gem "easy-sdk", "~> 0.1"
```

```bash
bundle install
```

Without Bundler:

```bash
gem install easy-sdk
```

## Verify the install [#verify-the-install]

```ruby
require "easy_sdk"

client = EasyLabs::Client.new(api_key: ENV.fetch("EASY_API_KEY"))

# The constructor calls GET /validate-key, so reaching this line means
# the key is valid and the SDK can reach the API.
puts "Connected to #{client.api_url}"
```

If the key is malformed or rejected, `EasyLabs::Client.new` raises
`EasyLabs::AuthenticationError` immediately — no lazy first-call surprise.

## Next steps [#next-steps]

* [Quickstart](./quickstart) — render your first payment.
* [Authentication](./authentication) — API keys, sandbox vs. live, multi-tenant clients.
* [Resources](./resources) — every method on every resource.


# Pagination (/docs/sdks/ruby/pagination)



Easy Labs uses offset-based pagination for all list endpoints. Every
`list` method on the SDK accepts the same three keyword arguments:

| Param     | Type            | Meaning                                                        |
| --------- | --------------- | -------------------------------------------------------------- |
| `limit:`  | `Integer, nil`  | Max records per page (server-side default applies if omitted). |
| `offset:` | `Integer, nil`  | Number of records to skip from the start.                      |
| `ids:`    | `Array<String>` | Filter to a specific set of IDs (joined with `,`).             |

`nil` values are dropped from the query string, so you only need to pass
what you want to override.

## Manual pagination [#manual-pagination]

```ruby
page = client.customers.list(limit: 50)
records = page[:data]      # array of customers on this page
total   = page[:meta][:total]  # full count, when the API returns it
```

Walk the next page by incrementing `offset`:

```ruby
page = client.customers.list(limit: 50, offset: 50)
```

{/* TODO: confirm canonical envelope key — `:data` vs. `:items` vs. `:results` — varies by endpoint family in @easylabs/node. */}

## Auto-pagination [#auto-pagination]

The SDK does not yet ship an auto-paginating iterator. Build one with a
plain Ruby `Enumerator` when you need it:

```ruby
def each_customer(client, page_size: 100)
  return enum_for(:each_customer, client, page_size: page_size) unless block_given?

  offset = 0
  loop do
    page = client.customers.list(limit: page_size, offset: offset)
    records = page[:data] || []
    records.each { |c| yield c }
    break if records.size < page_size

    offset += records.size
  end
end

each_customer(client).each { |c| puts c[:email] }
```

{/* TODO: ship a first-class auto-pager (e.g. `client.customers.each`) once the JS SDK does. */}


# Quickstart (/docs/sdks/ruby/quickstart)



This walkthrough creates a customer, attaches a payment instrument, and
charges them — the full happy path you'll repeat across every Easy Labs
integration.

## 1. Get your API keys [#1-get-your-api-keys]

Generate an API key in the [Easy Labs dashboard](https://app.itseasy.co).
Use a `sk_test_…` key for development (routes to the sandbox automatically)
and a `sk_live_…` key in production. Treat the key as a secret: load it
from the environment, never commit it.

```bash
export EASY_API_KEY="sk_test_..."
```

## 2. Initialize the SDK [#2-initialize-the-sdk]

```ruby
require "easy_sdk"

client = EasyLabs::Client.new(api_key: ENV.fetch("EASY_API_KEY"))
```

The constructor immediately calls `GET /validate-key` to verify the key.
A bad key raises `EasyLabs::AuthenticationError` here — not on your first
real request.

## 3. Make your first call [#3-make-your-first-call]

```ruby
customer = client.customers.create(
  first_name: "Ada",
  last_name:  "Lovelace",
  email:      "ada@example.com"
)

puts customer[:id] # => "cust_..."
```

Every response is a plain Ruby `Hash` with symbol keys. There is no
wrapper object, no `.attributes` accessor — what you get back is what the
API returned.

## 4. Handle the response [#4-handle-the-response]

```ruby
begin
  charge = client.transfers.create(
    amount:   1500,            # cents
    currency: "USD",
    source:   payment_instrument_id
  )

  puts "Charged #{charge[:amount]} #{charge[:currency]}"
rescue EasyLabs::InvalidRequestError => e
  # 400 / 422 — bad input. e.code holds the machine-readable code.
  warn "Bad request: #{e.code}: #{e.message}"
rescue EasyLabs::RateLimitError => e
  # 429 — back off using the Retry-After header.
  sleep(e.retry_after_seconds || 1)
  retry
rescue EasyLabs::Error => e
  # All other failures (auth, conflict, server, network).
  warn "API failure (#{e.status}): #{e.message}"
end
```

See [Error handling](./error-handling) for the full class hierarchy.

## What's next [#whats-next]

* [Authentication](./authentication) — sandbox vs. live, key rotation, multi-tenant.
* [Resources › Customers](./resources/customers) — full customer-resource reference.
* [Resources › Subscriptions](./resources/subscriptions) — recurring billing.
* [Webhooks](./webhooks) — verify and react to async events.


# Webhooks (/docs/sdks/ruby/webhooks)



Easy Labs delivers asynchronous events — payment confirmations,
subscription state changes, dispute notifications, settlement closes — as
HTTP POSTs to endpoints you register on your account. Webhooks let you
react to platform state without polling.

Every delivery is signed with HMAC-SHA256 over the raw request body
using the per-endpoint signing secret. The signature is sent in the
`X-Easy-Webhook-Signature` header in the form `sha256=<hex>`.

## Verifying signatures [#verifying-signatures]

Use `EasyLabs::Webhooks.construct_event` to verify the signature and
parse the JSON body in one step. It raises
`EasyLabs::InvalidRequestError` on any failure — never returns silently
on a bad signature.

```ruby
require "easy_sdk"

# Sinatra example. Same pattern works in Rails (request.raw_post) or Rack.
post "/webhooks/easy" do
  begin
    event = EasyLabs::Webhooks.construct_event(
      payload:   request.body.read,
      signature: request.headers["X-Easy-Webhook-Signature"],
      secret:    ENV.fetch("EASY_WEBHOOK_SECRET")
    )
  rescue EasyLabs::InvalidRequestError => e
    # e.code: WEBHOOK_SIGNATURE_MISSING / WEBHOOK_SIGNATURE_FORMAT_INVALID
    #       / WEBHOOK_SIGNATURE_MISMATCH / WEBHOOK_BODY_INVALID_JSON
    halt 400, e.message
  end

  case event[:type]
  when "payment.created"           then handle_payment_created(event[:data])
  when "subscription.paused"       then handle_subscription_paused(event[:data])
  when "checkout.session.completed" then fulfill_order(event[:data])
  end

  status 204
end
```

**Pass the raw body, not a parsed hash.** The signature is computed over
the exact bytes the API sent. Re-serializing a parsed body changes
whitespace and breaks verification. In Rails: `request.raw_post`. In
Rack: `request.body.read` (then rewind if anything else needs it).

The `secret` is the value returned once by
`client.webhooks.register(...)` — it is **only visible at creation
time**. Store it next to the rest of your secrets.

## Replay protection [#replay-protection]

The SDK does not bundle a timestamp-tolerance check today —
`construct_event` validates the signature only.

If you need replay protection in front of an idempotent handler, store
each `event[:id]` you've successfully processed and skip duplicates:

```ruby
return if ProcessedWebhook.exists?(event_id: event[:id])
ProcessedWebhook.create!(event_id: event[:id])
```

{/* TODO: confirm whether the API includes a `timestamp` field in the signed envelope so we can offer a tolerance window like Stripe's `tolerance:` argument. */}

## Common event types [#common-event-types]

`EasyLabs::Webhooks::EVENT_TYPES` is a frozen array of every event the
API can emit (37 entries as of `0.1.0`). The headline groups:

| Family            | Events                                                                                                                                                                                                                             |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Payments          | `payment.created`, `payment.updated`                                                                                                                                                                                               |
| Refunds           | `refund.created`, `refund.updated`                                                                                                                                                                                                 |
| Authorizations    | `authorization.created`, `authorization.updated`, `authorization.voided`                                                                                                                                                           |
| Subscriptions     | `subscription.created`, `subscription.updated`, `subscription.deleted`, `subscription.paused`, `subscription.resumed`, `subscription.trial_will_end`, `subscription.pending_update_applied`, `subscription.pending_update_expired` |
| Invoices          | `invoice.created`, `invoice.finalized`, `invoice.paid`, `invoice.payment_failed`, `invoice.upcoming`, `invoice.voided`, `invoice.marked_uncollectible`                                                                             |
| Revenue recovery  | `revenue_recovery.action_completed`                                                                                                                                                                                                |
| Coupons / promos  | `coupon.created`, `coupon.updated`, `coupon.deleted`, `promotion_code.created`, `promotion_code.updated`, `promotion_code.deleted`                                                                                                 |
| Identities        | `identity.created`, `identity.updated`                                                                                                                                                                                             |
| Settlements       | `settlement.created`                                                                                                                                                                                                               |
| Disputes          | `dispute.created`, `dispute.updated`                                                                                                                                                                                               |
| Checkout sessions | `checkout.session.completed`, `checkout.session.crypto_confirmed`                                                                                                                                                                  |
| Diagnostics       | `test.webhook`                                                                                                                                                                                                                     |

See the [API reference](https://api-docs.itseasy.co) for the payload
shape of each event.

## Registering an endpoint [#registering-an-endpoint]

```ruby
endpoint = client.webhooks.register(
  url:    "https://example.com/webhooks/easy",
  events: ["payment.created", "subscription.*"]   # default is ["*"]
)

ENV["EASY_WEBHOOK_SECRET"] = endpoint[:secret]    # capture this once
```

See [Resources › Webhook endpoints](./resources/webhook-endpoints) for
the full management surface.


# Bank account (/docs/treasury/concepts/bank-account)



A **bank account** is a US checking or savings account on either side of a
payout — a *funding* account that you (the merchant) own and debit, or a
*payment method* attached to a [Recipient](./recipient) that you credit. Both
sides use the same underlying tokenization: account and routing numbers are
exchanged for a token at creation time, and only the token + last-four are
stored on Easy. Your application never needs to handle raw account numbers.

## Lifecycle [#lifecycle]

1. **Linked** — Created via one of three paths:
   * **Plaid (server, your funding account):** `GET /treasury/bank-accounts/link-token`
     to start, then `POST /treasury/bank-accounts/link` with the resulting
     `plaid_processor_token`.
   * **Plaid (recipient self-service):** the invite flow uses
     `POST /treasury/recipients/plaid/link-token` and
     `POST /treasury/recipients/plaid/exchange` against the recipient's
     invitation token. See [recipient-plaid](/docs/reference/api/treasury/recipient-plaid).
   * **Manual entry:** `POST /treasury/recipients/{id}/payment-methods` with
     `routing_number` + `account_number`. The account number is tokenized
     server-side before persistence.
2. **Active** — Usable as a `source_account_id` (funding) or as a recipient
   payment method. `GET /treasury/bank-accounts` lists your funding accounts.
3. **Removed** — `DELETE /treasury/bank-accounts/{id}` (funding) detaches the
   account. Existing payouts that already reference it complete normally.

The `link` endpoint is **idempotent** on the underlying instrument — re-linking
the same Plaid account returns the existing record instead of duplicating it.

## Relationships [#relationships]

Each bank account belongs to either your company (funding) or one
[Recipient](./recipient) (payment method). It is referenced by zero-to-many
[Payouts](./payout) (as either `source_account_id` or destination via the
recipient).

## Fields that matter [#fields-that-matter]

* `method_type` (`"ach" | "wire"`) — which rail this account is reachable on.
* `account_type` (`"checking" | "savings"`) — required for ACH origination.
* `routing_number` (`string`, 9 digits) — ABA routing number. Validated against
  the FRB list.
* `account_number_last4` (`string`, 4 digits) — only the last four are
  retained after tokenization.
* `institution_name`, `account_name`, `account_mask` — optional display
  metadata supplied by Plaid for UI presentation.

## Related [#related]

* [API reference: bank-accounts](/docs/reference/api/treasury/bank-accounts)
* [API reference: recipient-plaid](/docs/reference/api/treasury/recipient-plaid)
* [Guide: Invite a recipient](../guides/invite-recipient)


# Treasury concepts (/docs/treasury/concepts)



The Treasury surface is built around 5 core entities. Each page covers what the entity is, how its lifecycle progresses, and how it relates to the rest of the model.



<Cards>
  <Card title="Payout" href="./concepts/payout" description="The Payout entity in Treasury." />

  <Card title="Recipient" href="./concepts/recipient" description="The Recipient entity in Treasury." />

  <Card title="Bank Account" href="./concepts/bank-account" description="The Bank Account entity in Treasury." />

  <Card title="Settlement" href="./concepts/settlement" description="The Settlement entity in Treasury." />

  <Card title="Tax Document" href="./concepts/tax-document" description="The Tax Document entity in Treasury." />
</Cards>


# Payout (/docs/treasury/concepts/payout)



A **payout** is a money-movement instruction: a debit from one of your linked
funding accounts that arrives in a recipient's bank account over ACH, same-day
ACH, RTP, or wire. Payouts are created in two phases — `initiate` (which
returns a transaction in `pending` state and may require a 2FA code) and
`confirm` (which submits to the rail). Until confirmed they can be cancelled
without cost.

## Lifecycle [#lifecycle]

1. **`pending`** — `POST /treasury/send` returned a transaction ID. Funds are
   not yet moving. If your security rules require it, this state also returns
   an `approval_required` flag and you must collect a 6-digit `security_code`
   from the operator.
2. **`processing`** — `POST /treasury/send/confirm` accepted the transaction
   and handed it to the rail. RTP completes in seconds; ACH typically settles
   in 1–3 business days; wires same day.
3. **`completed`** — Rail acknowledged settlement. The associated
   [Settlement](./settlement) record is created and the `settlement.created`
   webhook fires.
4. **`failed`*&#x2A; / &#x2A;*`returned`** — Rail rejected or returned the payment
   (insufficient funds, bad routing, bank closure). The transaction stays
   visible via `GET /treasury/transactions/{id}`.
5. **`cancelled`** — `POST /treasury/send/cancel` ran before confirmation.
   No rail submission, no fee.

## Relationships [#relationships]

A payout belongs to one &#x2A;*[Recipient](./recipient)** (which owns the destination
[Bank Account](./bank-account)) and debits one of your linked funding
[Bank Accounts](./bank-account). It produces exactly one
[Settlement](./settlement) on success. If the recipient is a US contractor and
the year-to-date total crosses the IRS threshold, payouts also feed the
[Tax Document](./tax-document) (1099) calculation.

## Fields that matter [#fields-that-matter]

* `recipient_id` (`uuid`) — destination recipient.
* `source_account_id` (`string`) — your linked bank account being debited.
* `amount` (`integer`, USD cents, `> 0`) — the amount to send.
* `method` (`"ach" | "same_day_ach" | "rtp" | "wire"`) — rail. Affects fee
  and settlement window; RTP and wire are irreversible.
* `memo` (`string`, ≤500 chars) — appears on the recipient's bank statement
  where the rail supports it.
* `notes` (`string`, ≤2000 chars) — internal-only, never sent to the rail.

## Related [#related]

* [API reference](/docs/reference/api/treasury/treasury)
* [Guide: Send a payout](../guides/send-payout)
* [Guide: Generate a payout link](../guides/generate-payout-link)


# Recipient (/docs/treasury/concepts/recipient)



A **recipient** is the person or business you send payouts to. A recipient
record stores their identity (name, email, type), zero or more payment methods
(bank accounts), and tax-compliance fields (W-9 status, tokenized tax ID). You
either create the recipient yourself with banking pre-populated, or invite them
to enter their own banking via a one-time link — the
[invite flow](../guides/invite-recipient) is the recommended path because it
keeps you off the hook for collecting account numbers directly.

## Lifecycle [#lifecycle]

1. **Created** — `POST /treasury/recipients` with `name` + `email` (and
   optional initial `payment_methods`). Recipient is now addressable but not
   payable until at least one payment method is attached.
2. **Invited** — `POST /treasury/recipients/{id}/invite` emails the recipient
   a 72-hour link. Sending a new invite revokes any pending one.
3. **Linked** — Recipient submits banking through the invite (Plaid Link or
   manual entry). A payment method is attached, the recipient is now payable.
   For US contractors hitting the 1099 threshold you'll also collect a W-9 —
   see [Tax Document](./tax-document).
4. **Active** — Receives payouts. You can add up to 5 payment methods per
   recipient (`POST /treasury/recipients/{id}/payment-methods`).
5. **Archived** — `DELETE /treasury/recipients/{id}` soft-deletes. Historical
   payouts and tax documents remain queryable; no new payouts can be sent.

## Relationships [#relationships]

A recipient owns one-to-many &#x2A;*[Bank Accounts](./bank-account)*&#x2A; as payment
methods. It is the destination for many &#x2A;*[Payouts](./payout)*&#x2A; and the subject
of one &#x2A;*[Tax Document](./tax-document)** per tax year (when applicable).
Recipients are scoped to your company and environment (sandbox vs. production
recipients are isolated).

## Fields that matter [#fields-that-matter]

* `name` (`string`, ≤255) — display name. Required.
* `email` (`string`, RFC 5322) — used for invitations and W-9 requests.
  Required and must be unique per company.
* `type` (`"person" | "business"`) — drives 1099 vs. W-9 logic and tax-ID
  validation rules.
* `payment_methods[]` — initial bank accounts; can be empty if you plan to
  invite.
* `metadata` (`Record<string, string>`) — your own key/value tags, returned on
  every read.

## Related [#related]

* [API reference](/docs/reference/api/treasury/treasury)
* [Guide: Invite a recipient](../guides/invite-recipient)
* [Guide: Request a W-9](../guides/request-w9)


# Settlement (/docs/treasury/concepts/settlement)



A **settlement** is the daily roll-up of money the rail actually moved on your
behalf. It groups one or more completed [payouts](./payout) (and any reversals,
fees, and adjustments tied to them) into a single net amount that lands in —
or is debited from — your funding [bank account](./bank-account). One
settlement maps to one bank-statement line item, which is what you'll
ultimately reconcile against in your accounting system.

## Lifecycle [#lifecycle]

1. **`OPEN`** — Created automatically when the first eligible event of the
   period occurs. New payouts continue to accrue into it.
2. **`APPROVED`*&#x2A; / &#x2A;*`PROCESSING`** — Closed for new entries (either because
   the schedule rolled over or you called `PATCH /settlements/{id}` to close
   it manually) and queued for funding.
3. **`FUNDED`** — Net amount has hit your funding account. The
   `settlement.created` webhook fires when the record reaches this state, so
   you can post the journal entry on receipt.
4. **`EXCEPTION`** — Held for review (e.g. fee miscalculation, reversed
   funding). `is_exception: true` on the record; check the `exception` field
   for context.

## Relationships [#relationships]

Each settlement aggregates the [Payouts](./payout) and reversals that completed
within its window. It is **per-currency** (currently USD only) and &#x2A;*per-funding
[Bank Account](./bank-account)** — if you fund payouts from two different
business accounts you'll see two settlement streams. Use
`GET /treasury/transactions/{id}/settlement` to walk from a single payout back
to the settlement that contained it.

## Fields that matter [#fields-that-matter]

* `id` (`string`) — settlement ID. Stable.
* `status` (`string`) — current lifecycle state (see above).
* `net_amount` (`integer`, USD cents) — the line item that hits your bank
  statement. Already nets out fees, refunds, and adjustments.
* `total_amount` / `total_fees` (`integer`, USD cents) — gross movement and
  Easy's fee, useful for revenue reconciliation.
* `currency` (`string`) — `"USD"` today.
* `is_exception` (`boolean`) — true means manual review required.
* `auto_close_time` (`string` ISO-8601) — when this settlement will roll over
  if not closed earlier.

## Related [#related]

* [API reference: settlement](/docs/reference/api/treasury/settlement)
* [Guide: Send a payout](../guides/send-payout)


# Tax document (/docs/treasury/concepts/tax-document)



A **tax document** is the IRS-reportable record we hold for each US
[Recipient](./recipient) you've paid in a given tax year — typically a 1099-NEC
for contractors or 1099-MISC for other payments. The document is built from two
inputs you supply: the recipient's W-9 (collected via
`POST /treasury/recipients/{id}/request-w9`) and the cumulative payout total
for the year. Easy tracks both and produces the form when the year closes.

## Lifecycle [#lifecycle]

1. **`not_requested`** — Default state for a new recipient. No W-9 has been
   asked for and the recipient is below the IRS threshold.
2. **`requested`** — `POST /treasury/recipients/{id}/request-w9` has emailed
   the recipient. They have 72 hours to submit before the link expires.
3. **`received`** — Recipient submitted the form. Tax ID is tokenized at
   intake and stored only as a token + `tax_id_type` (`ssn` | `ein` | `itin`).
4. **`verified`** — Tax ID matches IRS TIN-matching service (where enabled
   for your account). The recipient is fully eligible for year-end issuance.
5. **`expired`** — Form aged out (W-9 is good for the life of the recipient
   unless their info changes; this state is reserved for partial submissions
   that never completed).

The form itself is generated from the totals in
`GET /treasury/recipients/tax-report` once the calendar year closes.

## Relationships [#relationships]

Exactly one tax document per [Recipient](./recipient) per tax year (for
recipients meeting the threshold). Built from the cumulative net of all
completed [Payouts](./payout) to that recipient in the year, sourced from
[Settlement](./settlement) records.

## Fields that matter [#fields-that-matter]

* `tax_id_type` (`"ssn" | "ein" | "itin" | "none"`) — discriminator for which
  form applies.
* `tax_id` (`string`, 4–11 chars) — raw value sent on intake; **never** stored
  raw. Subsequent reads return only the type and a token.
* `w9_status` — see lifecycle states above.
* `w9_received_at`, `w9_expires_at` (`string` ISO-8601) — audit timestamps.

## Related [#related]

* [API reference: tax-documents](/docs/reference/api/treasury/tax-documents)
* [API reference: tax](/docs/reference/api/treasury/tax)
* [Guide: Request a W-9](../guides/request-w9)


# Configure auto-transfers (/docs/treasury/guides/configure-auto-transfers)



## Goal [#goal]

Create a rule that automatically transfers funds — either internally between
two of your linked accounts, or externally out to a sweep account — when
either a balance threshold is crossed or a fixed schedule fires. Useful for
keeping a payout-funding account topped up, or sweeping excess balance to a
treasury account daily.

## Prerequisites [#prerequisites]

* Two linked [bank accounts](../concepts/bank-account): a source (debited)
  and a destination (credited). For external transfers the destination must
  be reachable on ACH or wire.
* API key with Treasury enabled.

## Implementation [#implementation]

### 1. Pick a rule type [#1-pick-a-rule-type]

| `rule_type`         | When the rule fires                                         |
| ------------------- | ----------------------------------------------------------- |
| `balance_threshold` | The source account's balance crosses the configured amount. |
| `schedule`          | A cron-like schedule fires (daily, weekly, monthly).        |

### 2. Create the rule [#2-create-the-rule]

Balance-threshold example — top up the payout account when it dips below $5k:

```ts
const { data: rule } = await client.createAutoTransferRule({
  rule_type: "balance_threshold",
  trigger_condition: {
    threshold_cents: 500_000,   // $5,000
    direction: "below",
  },
  transfer_amount: 1_000_000,   // $10,000 top-up
  transfer_type: "internal",
  source_account_id: "ba_treasury…",
  destination_account_id: "ba_payouts…",
});
```

Schedule example — sweep $20k daily at 5pm UTC:

```ts
await client.createAutoTransferRule({
  rule_type: "schedule",
  trigger_condition: {
    cron: "0 17 * * *",
    timezone: "UTC",
  },
  transfer_amount: 2_000_000,
  transfer_type: "external",
  source_account_id: "ba_payouts…",
  destination_account_id: "ba_corp_treasury…",
});
```

The endpoint is `POST /treasury/auto-transfer-rules`. `trigger_condition` is
a free-form object whose required keys depend on `rule_type` — start with
the shapes above.

### 3. Manage the rule [#3-manage-the-rule]

```ts
const { data: rules } = await client.listAutoTransferRules();
await client.updateAutoTransferRule(rule.id, { transfer_amount: 1_500_000 });
await client.deleteAutoTransferRule(rule.id);
```

### 4. Observe what fired [#4-observe-what-fired]

Each rule execution creates a transaction visible in
`client.listTransactions()` tagged with the rule that produced it. The same
`settlement.created` webhook fires when the resulting transfer settles.

## Tradeoffs [#tradeoffs]

* **External transfers go through the same rails as payouts.** That means
  ACH 1–3 days, same-day ACH same business day, RTP seconds, wire same day.
  The rule's trigger time is *initiation*, not arrival. Don't use a
  threshold rule with ACH to backstop a same-minute outflow.
* **No built-in cooldown.** If your threshold rule fires, transfers $10k,
  and the source dips below threshold *again* before the transfer arrives,
  the rule will fire a second time. Add a `cooldown` field in
  `trigger_condition` (or check via your own observability) to avoid loops.
* **Internal vs. external.** `internal` transfers are book-only between two
  Easy-managed accounts and settle instantly with no rail fee. `external`
  transfers leave the platform and incur the standard rail fee.

## Related [#related]

* [Concept: Bank account](../concepts/bank-account)
* [Concept: Settlement](../concepts/settlement)
* [API reference: auto-transfer-rules](/docs/reference/api/treasury/auto-transfer-rules)


# Generate a payout link (/docs/treasury/guides/generate-payout-link)



## Goal [#goal]

Generate a single-use link with a fixed amount that anyone can open, enter
their bank details, and receive the funds — without needing to first exist
as a recipient in your account. Useful for one-off contractor payments,
referral payouts, customer refunds where you don't have the bank info, or
any "we need to pay this person once" flow.

## Prerequisites [#prerequisites]

* API key with Treasury enabled.
* A linked funding [bank account](../concepts/bank-account) with balance to
  cover the link amount.

## Implementation [#implementation]

### 1. Generate the link [#1-generate-the-link]

```ts
const { data: link } = await client.generatePayoutLink({
  amount: 25_000,                         // $250.00, USD cents, integer > 0
  currency: "USD",                        // only USD today
  description: "Q3 referral bonus — order #4127", // ≤1000 chars
});

// link.url           — the shareable URL
// link.token         — the path token (also embedded in url)
// link.expires_at    — ISO-8601 expiry
// link.status        — "pending"
```

Underlying endpoint: `POST /treasury/payout-link/generate`.

### 2. Share the link [#2-share-the-link]

Email it, drop it into Slack, embed it in your own UI — it's a regular HTTPS
URL. The hosted page on the other end:

1. Asks the claimant to identify themselves (name + email).
2. Walks them through bank entry via Plaid Link.
3. On submit (`POST /treasury/payout-link/{token}/submit`), creates a
   recipient + payment method on your account and queues the payout.

### 3. Track redemption [#3-track-redemption]

```ts
const { data } = await client.getPayoutLink(link.token);
// data.status: "pending" | "claimed" | "completed" | "expired" | "cancelled"
// data.recipient_id  — set once claimed
// data.transaction_id — set once the payout is initiated
```

Or list all your links to build a redemption dashboard:

```ts
const { data: links } = await client.listPayoutLinks();
```

### 4. (Optional) React when the payout settles [#4-optional-react-when-the-payout-settles]

The standard `settlement.created` webhook fires when the underlying payout
funds — same plumbing as a directly-sent payout. There is no separate
"link.claimed" webhook today; poll `getPayoutLink` if you need an earlier
signal.

## Tradeoffs [#tradeoffs]

* **Single-use, fixed amount.** A link is for one specific payment. If you
  want recurring payments to the same contractor, create a regular
  [recipient](../concepts/recipient) and [send payouts](./send-payout).
* **Recipient is auto-created.** When the link is claimed, a recipient
  record appears in your account. Two claims on two links by the same
  person create two recipients — dedupe on email server-side if that
  matters to you.
* **No 2FA prompt at claim time.** Link redemption funds from your default
  source account and doesn't go through the operator-level approval flow
  that `createPayout` does. Keep individual link amounts low and use direct
  payouts for high-value transfers.

## Related [#related]

* [Concept: Payout](../concepts/payout)
* [API reference: payout-link](/docs/reference/api/treasury/payout-link)


# Treasury guides (/docs/treasury/guides)



Step-by-step recipes for the most common Treasury integrations. Each guide states the goal, lists prerequisites, and ships working code.



<Cards>
  <Card title="Send Payout" href="./guides/send-payout" description="Send Payout with Easy Treasury." />

  <Card title="Invite Recipient" href="./guides/invite-recipient" description="Invite Recipient with Easy Treasury." />

  <Card title="Generate Payout Link" href="./guides/generate-payout-link" description="Generate Payout Link with Easy Treasury." />

  <Card title="Configure Auto Transfers" href="./guides/configure-auto-transfers" description="Configure Auto Transfers with Easy Treasury." />

  <Card title="Request W9" href="./guides/request-w9" description="Request W9 with Easy Treasury." />
</Cards>


# Invite a recipient (/docs/treasury/guides/invite-recipient)



## Goal [#goal]

Create a recipient record without their banking, then email them a 72-hour
self-serve link where they enter their bank details through Plaid Link. The
recipient is fully payable when they finish — no account numbers ever pass
through your servers.

## Prerequisites [#prerequisites]

* An API key with Treasury enabled.
* The recipient's `name` and `email`.

## Implementation [#implementation]

### 1. Create the recipient (banking optional) [#1-create-the-recipient-banking-optional]

```ts
const { data: recipient } = await client.createRecipient({
  name: "Grace Hopper",
  email: "grace@example.com",
  type: "person",
  payment_methods: [], // empty — they'll add it via the invite
});
```

### 2. Send the invite [#2-send-the-invite]

```ts
await client.inviteRecipient({ recipient_id: recipient.id });
```

This emails the recipient a one-time link. The link is valid for 72 hours;
sending another invite to the same recipient revokes the previous one. The
underlying endpoint is `POST /treasury/recipients/{id}/invite`.

### 3. Recipient flows through Plaid Link [#3-recipient-flows-through-plaid-link]

The hosted page at the invite URL handles everything. Under the hood it calls
`POST /treasury/recipients/plaid/link-token` (using the `invitation_token`
from the URL, not your API key) and on success calls
`POST /treasury/recipients/plaid/exchange` to attach the verified bank
account.

You don't ship code for this step — it's a hosted flow. If you want to
embed it in your own UI later, the `recipient-plaid` endpoints are the same
contract.

### 4. Detect completion [#4-detect-completion]

Poll the recipient until a payment method appears:

```ts
const { data } = await client.getRecipient(recipient.id);
const ready = (data.payment_methods ?? []).length > 0;
```

You can list all pending invitations with
`client.listRecipientInvitations()` to surface a "waiting on Grace" UI.

### 5. (Optional) Capture tax info in the same flow [#5-optional-capture-tax-info-in-the-same-flow]

If the recipient is a US contractor and you'll cross the 1099 threshold,
chain a [W-9 request](./request-w9) right after the bank link:

```ts
if (ready) {
  await client.requestW9({ recipient_id: recipient.id });
}
```

## Tradeoffs [#tradeoffs]

* **You don't see the bank details.** Only `account_number_last4`,
  `routing_number`, and the institution name are returned. If a recipient
  disputes that you sent to the wrong account, the audit trail is the Plaid
  link event, not a visible account number.
* **Invitations expire.** 72 hours, full stop. For long-tail onboarding
  (contractors who sign up months before getting paid), trigger the invite
  on first payout instead of at recipient creation.
* **Manual entry alternative.** If your recipients can't or won't use Plaid,
  call `client.addRecipientPaymentMethod(...)` server-side with
  `routing_number` + `account_number`. The number is tokenized at intake but
  you've now seen it, which puts you in scope for the data handling
  requirements documented in [Compliance](/docs/reference/compliance).

## Related [#related]

* [Concept: Recipient](../concepts/recipient)
* [Concept: Bank account](../concepts/bank-account)
* [API reference: recipient-plaid](/docs/reference/api/treasury/recipient-plaid)


# Request a W-9 (/docs/treasury/guides/request-w9)



## Goal [#goal]

Email a US recipient a hosted W-9 form, capture their tax ID, and verify it.
Once on file, the recipient is eligible for year-end 1099 issuance based on
their cumulative payouts.

## Prerequisites [#prerequisites]

* An existing [recipient](../concepts/recipient) with a valid `email`.
* API key with Treasury + tax-documents enabled.

## Implementation [#implementation]

### 1. Send the request [#1-send-the-request]

```ts
await client.requestW9({ recipient_id: "rcp_123…" });
```

Endpoint: `POST /treasury/recipients/{id}/request-w9`. The recipient receives
an email with a hosted form. On submit, their tax ID is tokenized at intake
— your servers never see the raw value.

### 2. Check status [#2-check-status]

```ts
const { data: taxInfo } = await client.getRecipientTaxInfo("rcp_123…");
// taxInfo.tax_id_type: "ssn" | "ein" | "itin" | "none"
// taxInfo.w9_status: "not_requested" | "requested" | "received" | "verified" | "expired"
// taxInfo.w9_received_at, taxInfo.w9_expires_at
```

Statuses progress: `not_requested → requested → received → verified`. The
`verified` state means our TIN-matching service confirmed the ID against
IRS records (where enabled for your account).

### 3. Backfill from your own form (alternative) [#3-backfill-from-your-own-form-alternative]

If you've collected the W-9 outside the hosted flow — e.g. via DocuSign or
your own onboarding UI — you can post the tax-info fields directly:

```ts
await client.updateRecipientTaxInfo("rcp_123…", {
  tax_id_type: "ssn",
  tax_id: "123-45-6789",   // tokenized at intake; never stored raw
  w9_status: "received",
  w9_received_at: new Date().toISOString(),
});
```

Endpoint: `POST /treasury/recipients/{id}/tax-info`.

### 4. Pull the year-end report [#4-pull-the-year-end-report]

```ts
const { data: report } = await client.getRecipientTaxReport();
// One entry per recipient with cumulative payout totals + W-9 readiness.
```

Endpoint: `GET /treasury/recipients/tax-report`. Use this to drive your
1099 issuance — every recipient over the IRS threshold whose `w9_status`
isn't `received` or `verified` is a hole you need to chase before year-end.

## Tradeoffs [#tradeoffs]

* **You don't see the tax ID.** The full SSN/EIN is intentionally
  unreadable from your application after intake. If you need to surface it
  to the recipient (for them to confirm their own info), build a flow that
  re-prompts them rather than echoing it back.
* **`requested` does not block payouts.** A recipient with `w9_status:
  "requested"` can still receive payouts. If your policy is "no W-9, no
  pay," gate that yourself before calling `createPayout`.
* **Persons vs. businesses.** `tax_id_type` must match `recipient.type`:
  `ssn`/`itin` for `person`, `ein` for `business`. Wrong combinations are
  rejected at submission, not at recipient creation.

## Related [#related]

* [Concept: Tax document](../concepts/tax-document)
* [Concept: Recipient](../concepts/recipient)
* [API reference: tax-documents](/docs/reference/api/treasury/tax-documents)


# Send a payout (/docs/treasury/guides/send-payout)



## Goal [#goal]

Initiate, confirm, and track a single payout to a US bank account over ACH,
same-day ACH, RTP, or wire.

## Prerequisites [#prerequisites]

* A sandbox or production API key (`sk_sandbox_…` / `sk_live_…`).
* `@easylabs/node` installed and the client constructed.
* A linked funding [bank account](../concepts/bank-account) (visible in
  `client.listBankAccounts()`).
* A [recipient](../concepts/recipient) with at least one payment method —
  either created up-front with banking populated, or invited via the
  [self-serve invite flow](./invite-recipient).

## Implementation [#implementation]

### 1. Initiate [#1-initiate]

```ts
const { data: payout } = await client.createPayout({
  recipient_id: "rcp_123…",
  source_account_id: "ba_456…",
  amount: 12_500,         // $125.00, integer USD cents, > 0
  method: "ach",          // "ach" | "same_day_ach" | "rtp" | "wire"
  memo: "Sept. retainer", // ≤500 chars, appears on bank statement (rail-permitting)
  notes: "internal ref 9921", // ≤2000 chars, internal-only
});
// payout.status === "pending"
```

If your account has security rules requiring 2FA on payouts above a
threshold, the response will include `approval_required: true` and an
`approval_request_id`. Collect a 6-digit code from the operator and pass it on
confirm.

### 2. Confirm [#2-confirm]

```ts
await client.confirmPayout({
  transaction_id: payout.id,
  security_code: "482917", // omit if approval_required was false
});
```

After confirm, the payout is handed to the rail. From here it cannot be
cancelled — see [Tradeoffs](#tradeoffs).

### 3. Track [#3-track]

```ts
const { data } = await client.getTransaction(payout.id);
// data.status: "pending" | "processing" | "completed" | "failed" | "returned" | "cancelled"
```

Once `completed`, fetch the rolled-up settlement:

```ts
const { data: settlement } = await client.getTransactionSettlement(payout.id);
console.log(settlement.id, settlement.net_amount);
```

Or subscribe to the `settlement.created` webhook and post the journal entry on
receipt:

```ts
import { constructEvent } from "@easylabs/node";

app.post("/webhooks/easy", async (req, res) => {
  const event = constructEvent(req.rawBody, req.headers["easy-signature"], secret);
  if (event.type === "settlement.created") {
    // event.data.id, event.data.net_amount, event.data.status === "FUNDED"
  }
  res.sendStatus(200);
});
```

### 4. Cancel (only before confirm) [#4-cancel-only-before-confirm]

```ts
await client.cancelPayout({ transaction_id: payout.id });
```

`cancelPayout` is a no-op once the transaction has moved past `pending`.

## Tradeoffs [#tradeoffs]

* **Rail choice.** RTP and wire are **irreversible** the moment they're
  confirmed — there is no Easy-side rollback. ACH allows up to two business
  days for return processing but is slower (1–3 day settlement) and cheaper.
  Same-day ACH funds same business day for a per-transfer fee.
* **Idempotency.** `createPayout` is *not* implicitly idempotent. If you retry
  on a network error without checking, you may double-send. Persist the
  returned `transaction_id` before retrying, or check
  `client.listTransactions()` first.
* **Funding shortfall.** If your funding account lacks sufficient balance at
  rail submission time, the payout will reach `failed` rather than
  `completed` — listen for the status change rather than assuming success
  after `confirmPayout`.

## Related [#related]

* [Concept: Payout](../concepts/payout)
* [Concept: Settlement](../concepts/settlement)
* [API reference](/docs/reference/api/treasury/treasury)


# Account & operations (/docs/reference/api/account-and-operations)





<Cards>
  <Card title="Analytics" href="./analytics" description="Analytics endpoints" />

  <Card title="Branding" href="./branding" description="Branding endpoints" />

  <Card title="Categories" href="./categories" description="Categories endpoints" />

  <Card title="Comm Prefs" href="./comm-prefs" description="Comm Prefs endpoints" />

  <Card title="Companies" href="./companies" description="Companies endpoints" />

  <Card title="Custom Domains Dashboard" href="./custom-domains-dashboard" description="Custom Domains Dashboard endpoints" />

  <Card title="Dashboard" href="./dashboard" description="Dashboard endpoints" />

  <Card title="Files" href="./files" description="Files endpoints" />

  <Card title="Login Sessions" href="./login-sessions" description="Login Sessions endpoints" />

  <Card title="Merchant" href="./merchant" description="Merchant endpoints" />

  <Card title="Security Rules" href="./security-rules" description="Security Rules endpoints" />

  <Card title="Webhooks" href="./webhooks" description="Webhooks endpoints" />
</Cards>


# Billing (/docs/reference/api/billing)





<Cards>
  <Card title="Auto Pay" href="./auto-pay" description="Auto Pay endpoints" />

  <Card title="Coupons" href="./coupons" description="Coupons endpoints" />

  <Card title="Customer Portal" href="./customer-portal" description="Customer Portal endpoints" />

  <Card title="Customer Portal Config" href="./customer-portal-config" description="Customer Portal Config endpoints" />

  <Card title="Invoices" href="./invoices" description="Invoices endpoints" />

  <Card title="Product" href="./product" description="Product endpoints" />

  <Card title="Products" href="./products" description="Products endpoints" />

  <Card title="Promotion Codes" href="./promotion-codes" description="Promotion Codes endpoints" />

  <Card title="Recurring Payments" href="./recurring-payments" description="Recurring Payments endpoints" />

  <Card title="Subscription Plan" href="./subscription-plan" description="Subscription Plan endpoints" />

  <Card title="Subscriptions" href="./subscriptions" description="Subscriptions endpoints" />
</Cards>


# Payments (/docs/reference/api/payments)





<Cards>
  <Card title="Authorization" href="./authorization" description="Authorization endpoints" />

  <Card title="Checkout" href="./checkout" description="Checkout endpoints" />

  <Card title="Checkout Slug" href="./checkout-slug" description="Checkout Slug endpoints" />

  <Card title="Customer" href="./customer" description="Customer endpoints" />

  <Card title="Dispute" href="./dispute" description="Dispute endpoints" />

  <Card title="Embedded Checkout" href="./embedded-checkout" description="Embedded Checkout endpoints" />

  <Card title="Order" href="./order" description="Order endpoints" />

  <Card title="Payment Instrument" href="./payment-instrument" description="Payment Instrument endpoints" />

  <Card title="Payment Link" href="./payment-link" description="Payment Link endpoints" />

  <Card title="Sessions" href="./sessions" description="Sessions endpoints" />

  <Card title="Transfer" href="./transfer" description="Transfer endpoints" />
</Cards>


# Treasury (/docs/reference/api/treasury)





<Cards>
  <Card title="Auto Transfer Rules" href="./auto-transfer-rules" description="Auto Transfer Rules endpoints" />

  <Card title="Bank Accounts" href="./bank-accounts" description="Bank Accounts endpoints" />

  <Card title="Payout Link" href="./payout-link" description="Payout Link endpoints" />

  <Card title="Recipient Plaid" href="./recipient-plaid" description="Recipient Plaid endpoints" />

  <Card title="Settlement" href="./settlement" description="Settlement endpoints" />

  <Card title="Tax" href="./tax" description="Tax endpoints" />

  <Card title="Tax Documents" href="./tax-documents" description="Tax Documents endpoints" />

  <Card title="Treasury" href="./treasury" description="Treasury endpoints" />
</Cards>


# Customer Management (/docs/sdks/javascript/examples/customer-management)



This recipe shows how to use the typed `EasyApiClient` surface from `@easylabs/browser` to build a small "manage customers" UI — list, create, look up, paginate. It assumes you've already constructed a client per the [Quickstart](../quickstart).

A note on environments: `@easylabs/browser` is designed so the same client can run on the server (it's a thin `fetch` wrapper). For data-mutation flows like creating customers, decide deliberately whether the call belongs in the browser (with a key scoped accordingly) or behind your own backend endpoint. The examples below assume server-side execution unless noted.

## Goal [#goal]

Build the four common customer-management touch points:

1. List customers with pagination.
2. Look up a single customer by id.
3. Create a new customer.
4. Surface their payment instruments and active subscriptions.

## Implementation [#implementation]

### Setup [#setup]

```ts
import { createEasyClient, EasyApiError } from "@easylabs/browser";

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

### List customers [#list-customers]

`getCustomers` takes optional pagination params:

```ts
const { data: customers } = await easy.getCustomers({
  limit: 25,
  offset: 0,
});
```

For a "load more" UI, increment `offset` by `limit`. To fetch a specific subset by id:

```ts
const { data } = await easy.getCustomers({ ids: ["cus_abc", "cus_def"] });
```

### Look up one customer [#look-up-one-customer]

```ts
async function loadCustomer(id: string) {
  try {
    const { data } = await easy.getCustomer(id);
    return data;
  } catch (err) {
    if (err instanceof EasyApiError && err.status === 404) {
      return null;
    }
    throw err;
  }
}
```

### Create a customer [#create-a-customer]

`CreateCustomer` requires `first_name` and `last_name`; everything else is optional.

```ts
const { data: customer } = await easy.createCustomer({
  first_name: "Ada",
  last_name: "Lovelace",
  email: "ada@example.com",
  phone: "+15555550123",
  personal_address: {
    line1: "10 Downing St",
    city: "London",
    region: "GB",
    postal_code: "SW1A 2AA",
    country: "GB",
  },
  tags: { source: "signup_v2" },
});

console.log(customer.id);
```

### Fetch related resources [#fetch-related-resources]

A few convenience endpoints sit alongside the core CRUD methods:

```ts
const { data: instruments } = await easy.getCustomerPaymentInstruments(
  customer.id,
);

const { data: subscriptions } = await easy.getCustomerSubscriptions(
  customer.id,
  { status: "active" },
);

const { data: orders } = await easy.getCustomerOrders(customer.id, {
  limit: 10,
});

const { data: wallets } = await easy.getCustomerWallets(customer.id);
```

`getCustomerSubscriptions` returns a `Paginated<SubscriptionData>` so you can drive infinite scroll off `data.has_more` if your shape requires it.

### Update a customer [#update-a-customer]

`updateCustomer` accepts a partial:

```ts
await easy.updateCustomer(customer.id, {
  email: "ada+billing@example.com",
});
```

## Tradeoffs [#tradeoffs]

* **Browser vs. server.** `EasyApiClient` works in both contexts, but mutations from the browser ship your API key to every user who loads the page. For anything beyond read-only utility flows, run mutations server-side and expose a thin endpoint.
* **Pagination ceilings.** `limit` is bounded by the API (see your tier's limits). Don't request unbounded list calls in a hot loop — paginate explicitly.
* **Error shape.** Always branch on `EasyApiError.status` / `err.code` rather than string-matching `err.message`. The `message` includes the JSON-stringified error body and is intended for logs, not control flow.
* **Identity coupling.** A `CustomerData` object includes the underlying processor identity payload (`entity`, `_links`). Treat anything outside the documented top-level fields as opaque — it's there for advanced flows but not part of the stable contract.


# Payment Form (/docs/sdks/javascript/examples/payment-form)



This recipe shows how to build a fully custom card form with `@easylabs/browser` `0.2.0` — your own layout, your own styling, your own submit button — while keeping the PAN inside Easy Labs' iframed inputs. The flow is: mount three [Elements](../elements), tokenize on submit, then forward the token reference to your backend to create a payment instrument.

If you'd rather drop in the hosted checkout iframe (zero design work, zero PCI scope), use [Embedded Checkout](../embedded-checkout). If you want a wallet button instead of a card form, see [Wallet Checkout](../wallet-checkout).

## Goal [#goal]

Collect a one-time card payment from a custom form and turn it into a charged payment instrument. By the end you'll have:

* A browser page with three iframed card fields, live focus/complete/invalid styling, and a submit button.
* A `tokenize` call that produces a Basis Theory token reference.
* A `POST /api/payment-instruments` endpoint that exchanges the token reference for a charged payment instrument.

## Implementation [#implementation]

### 1. Browser markup [#1-browser-markup]

```html
<form id="card-form">
  <label for="card-number">Card number</label>
  <div id="card-number" class="el-host"></div>

  <div class="row">
    <div>
      <label for="card-exp">Expiration</label>
      <div id="card-exp" class="el-host"></div>
    </div>
    <div>
      <label for="card-cvc">CVC</label>
      <div id="card-cvc" class="el-host"></div>
    </div>
  </div>

  <button id="submit" type="submit">Pay $19.99</button>
  <p id="error" hidden></p>
</form>
```

```css
.el-host {
  border: 1px solid #d8d8df;
  border-radius: 8px;
  padding: 0.625rem 0.75rem;
  height: 44px;
  background: white;
}
.el-host.is-focused { border-color: #2563eb; box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.08); }
.el-host.is-complete { border-color: #16a34a; }
.el-host.is-invalid  { border-color: #dc2626; }
.row { display: grid; grid-template-columns: 1fr 1fr; gap: 0.75rem; }
```

### 2. Browser script [#2-browser-script]

```ts
import {
  createEasyClient,
  mountCardNumberElement,
  mountCardExpirationDateElement,
  mountCardVerificationCodeElement,
  tokenize,
} from "@easylabs/browser";

await createEasyClient({ apiKey: import.meta.env.VITE_EASY_API_KEY });

const stateClasses = {
  focus: "is-focused",
  complete: "is-complete",
  invalid: "is-invalid",
};

const cardNumber = mountCardNumberElement("#card-number", {
  placeholder: "1234 5678 9012 3456",
  classes: stateClasses,
});
const cardExpiration = mountCardExpirationDateElement("#card-exp", {
  placeholder: "MM / YY",
  classes: stateClasses,
});
const cardCvc = mountCardVerificationCodeElement("#card-cvc", {
  placeholder: "CVC",
  classes: stateClasses,
});

const form = document.querySelector<HTMLFormElement>("#card-form")!;
const errorEl = document.querySelector<HTMLParagraphElement>("#error")!;
const submitBtn = document.querySelector<HTMLButtonElement>("#submit")!;

form.addEventListener("submit", async (event) => {
  event.preventDefault();
  errorEl.hidden = true;
  submitBtn.disabled = true;
  submitBtn.textContent = "Processing…";

  try {
    const token = await tokenize({ cardNumber, cardExpiration, cardCvc });

    const res = await fetch("/api/payment-instruments", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ tokenId: token.id }),
    });
    if (!res.ok) throw new Error(`Server error: ${res.status}`);

    window.location.href = "/checkout/success";
  } catch (err) {
    errorEl.hidden = false;
    errorEl.textContent = (err as Error).message;
    submitBtn.disabled = false;
    submitBtn.textContent = "Pay $19.99";
  }
});

// On SPA route change, beforeunload, etc.:
window.addEventListener("beforeunload", () => {
  cardNumber.unmount();
  cardExpiration.unmount();
  cardCvc.unmount();
});
```

### 3. Server endpoint [#3-server-endpoint]

The browser hands you a Basis Theory token reference. Exchange it for a charged payment instrument server-side:

```ts
// server/payment-instruments.ts
import { createClient } from "@easylabs/node";

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

export async function createPaymentInstrument(req, res) {
  const { tokenId, cardholderName } = req.body;

  const { data: instrument } = await easy.createPaymentInstrument({
    type: "PAYMENT_CARD",
    identityId: req.session.customerId,
    tokenId,
    // `name` is required by `CreatePaymentInstrumentBase`. Pass the
    // cardholder name your form collected, or fall back to the
    // customer's stored name.
    name: cardholderName,
  });

  // Charge it, attach it to a subscription, save it for later — your call.
  res.json({ instrumentId: instrument.id });
}
```

### 4. Server-side reaction [#4-server-side-reaction]

For long-lived flows (subscriptions, scheduled charges, fulfilment) listen for the relevant webhooks rather than trusting the browser's success redirect. See [`@easylabs/node`'s webhook helpers](https://www.npmjs.com/package/@easylabs/node).

## Improvements you might add [#improvements-you-might-add]

* **Disable submit until all three are complete.** Track each element's `getState().complete` (or wire a `change` listener for each) and toggle `submitBtn.disabled` accordingly.
* **Pass `cardBrand` to the CVC element.** Read `state.brand` off the card-number `change` event and re-mount the CVC element with `{ cardBrand }` so length validation matches the network (Amex = 4 digits, others = 3).
* **Render a brand logo.** Subscribe to `cardNumber.on("change", ...)` and swap an inline SVG based on `state.brand`.
* **Surface server errors inline.** Catch `EasyApiError` on the server and forward `code` / `message` back to the page so the inline error reflects the API's reason rather than a generic 500.

## Tradeoffs [#tradeoffs]

* **Pro:** total control over layout, copy, validation timing, and submit affordance.
* **Pro:** PAN never reaches your origin — Basis Theory's iframes own it. PCI scope stays minimal (typically SAQ A-EP).
* **Con:** more code than [Embedded Checkout](../embedded-checkout). You own the form, the error UX, and the cleanup.
* **Con:** wallets (Apple Pay / Google Pay) are not built into this flow — add them separately via the wallet button factories. See [Wallet Checkout](../wallet-checkout).
* **Watch out:** always `unmount()` the elements on navigation. Forgetting leaks one iframe per mount.


# Vanilla JS integration (/docs/sdks/javascript/examples/vanilla)



A complete, runnable Vanilla JS example lives at `easy-sdk/examples/vanilla`. This page is a guided tour — it points to the most-relevant files in that example so you can see the SDK wired into a real project, not just isolated snippets.

> **Branch note (pre-0.2.0):** the file paths linked below reference the 0.2.0 example wiring (Elements + wallets) that ships with `@easylabs/browser` 0.2.0. Until that release lands on `main`, the linked files live on the [`feat/easy-browser-parity`](https://github.com/itseasyco/easy-sdk/tree/feat/easy-browser-parity/examples/vanilla) branch — replace `/main/` with `/feat/easy-browser-parity/` in any link below if it 404s. Once 0.2.0 merges, the `main` links resolve normally.

The example exercises every payment surface added in `0.2.0`:

* A custom card form built from `mountCardNumberElement`, `mountCardExpirationDateElement`, and `mountCardVerificationCodeElement`, then converted to a token via `tokenize`.
* An Apple Pay button via `createApplePayButton`.
* A Google Pay button via `createGooglePayButton`.

It is a Vite + TypeScript project (no framework), so it represents the "smallest possible" integration target for `@easylabs/browser`.

## Source code [#source-code]

* **Repository:** [`itseasyco/easy-sdk`](https://github.com/itseasyco/easy-sdk)
* **Path:** [`examples/vanilla`](https://github.com/itseasyco/easy-sdk/tree/main/examples/vanilla)

## What this example covers [#what-this-example-covers]

| Feature                 | How it's wired                                                                                                                                                                                 |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client bootstrap        | `await createEasyClient({ apiKey })` in `src/main.ts`. The API key is read from `import.meta.env.VITE_EASY_API_KEY`.                                                                           |
| Custom card form        | Three `mount*Element` calls bind iframes into `#card-number`, `#card-exp`, and `#card-cvc`. Each gets `classes: { focus, complete, invalid }` for live styling via the CSS in `src/style.css`. |
| Brand surfacing         | `cardNumber.on("change", ...)` writes the detected brand onto a `data-brand` attribute — the integrator could feed this into a card-network logo.                                              |
| Tokenization            | A "Create token" button calls `tokenize({ cardNumber, cardExpiration, cardCvc })` and prints the resulting `{ id, type, fingerprint }` to a `<pre>`.                                           |
| Apple Pay               | `createApplePayButton` mounts into `#apple-pay-slot` with a `merchantSession` callback that POSTs to `/api/apple-pay/session` (your backend wires this to Apple's `paymentSession` endpoint).  |
| Google Pay              | `createGooglePayButton` mounts into `#google-pay-slot`. The button defers to `isReadyToPay` and only renders when the device supports it.                                                      |
| Graceful unavailability | If `apple.isAvailable` is false the slot renders a "not available in this browser" hint. Google Pay does the same on a short timer (its readiness flips async).                                |

## Key files [#key-files]

| File                                                                                                               | Demonstrates                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`examples/vanilla/index.html`](https://github.com/itseasyco/easy-sdk/tree/main/examples/vanilla/index.html)       | Container markup for the card form and wallet slots. Also loads Apple's `apple-pay-sdk.js` and Google's `pay.js` — both wallets need their vendor SDKs present. |
| [`examples/vanilla/src/main.ts`](https://github.com/itseasyco/easy-sdk/tree/main/examples/vanilla/src/main.ts)     | App bootstrap: `createEasyClient`, three `mount*Element` calls, `tokenize`, plus both wallet button factories. The whole integration in one file.               |
| [`examples/vanilla/src/style.css`](https://github.com/itseasyco/easy-sdk/tree/main/examples/vanilla/src/style.css) | Stripe-like state styling — `.el-host.is-focused`, `.is-complete`, `.is-invalid` paired with the `classes` option on each element.                              |
| [`examples/vanilla/package.json`](https://github.com/itseasyco/easy-sdk/tree/main/examples/vanilla/package.json)   | Project manifest. Run `dev`, `build`, `preview` via the standard Vite scripts.                                                                                  |
| [`examples/vanilla/tsconfig.json`](https://github.com/itseasyco/easy-sdk/tree/main/examples/vanilla/tsconfig.json) | TypeScript config — minimum settings for Vite + ESM.                                                                                                            |

## Run it locally [#run-it-locally]

```bash
git clone https://github.com/itseasyco/easy-sdk.git
cd easy-sdk
pnpm install
pnpm --filter vanilla-example dev
```

Drop a sandbox key into `examples/vanilla/.env.local`:

```bash
VITE_EASY_API_KEY=sk_test_...
```

Vite will print a local URL (typically `http://localhost:5173`). Without the key the page still renders — the elements will surface an `error` event when they try to mount, so the surface is visible without paid setup.

To consume the SDK from your own project rather than the workspace, install it directly:

```bash
pnpm add @easylabs/browser
```

## Adapting it [#adapting-it]

* **Drop the surfaces you don't need.** The example wires all three (Embedded Checkout is shown elsewhere); strip the wallet sections if you only need a custom card form, or strip the card section if wallets are enough.
* **Add a backend.** The browser SDK can't (and shouldn't) mint sessions on its own. Add a tiny server endpoint — Express, Hono, Cloudflare Worker, anything — that exchanges the token reference for a payment instrument or a checkout session.
* **Wire `merchantSession` for real.** The example's `merchantSession` callback POSTs to `/api/apple-pay/session`. That endpoint must call Apple's `paymentSession` URL with your merchant identity certificate. Apple refuses to validate from the browser.
* **Move the API key out of source.** Vite exposes `import.meta.env.VITE_*` variables at build time. Use `VITE_EASY_API_KEY` for the sandbox key in development; in production, mint sessions on your backend with `sk_live_*` and never ship that key to the browser.


# E-commerce Flow (/docs/sdks/node/examples/ecommerce-flow)



A canonical "buy a product" flow with `@easylabs/node`: customer + payment instrument captured from the frontend, charged via `checkout`, fulfilment metadata attached to the resulting order, refund issued on cancellation.

## Goal [#goal]

Single endpoint that turns a cart-and-card payload from the browser into a charged order, idempotently. The frontend tokenizes the card with the Easy Labs frontend SDK and posts only the resulting `tokenId` plus the cart — your server never touches PAN data.

## Implementation [#implementation]

### 1. Create products + prices once [#1-create-products--prices-once]

```ts
import { createClient } from "@easylabs/node";
const easy = await createClient({ apiKey: process.env.EASY_API_KEY! });

const product = await easy.createProduct({ name: "Notebook", active: true });
const price = await easy.createPrice({
  product_id: product.data.id,
  active: true,
  recurring: false,
  currency: "USD",
  unit_amount: 2499,
  tax_behavior: "exclusive",
});
```

Persist `price.data.id` in your catalog table.

### 2. Charge endpoint [#2-charge-endpoint]

```ts
// POST /api/checkout
type Body = {
  buyer: { first_name: string; last_name: string; email: string };
  card: { tokenId: string; name: string };
  cart: { price_id: string; quantity: number }[];
  cart_id: string;
};

export async function checkout(body: Body) {
  const result = await easy.checkout({
    customer_creation: true,
    customer_details: {
      first_name: body.buyer.first_name,
      last_name: body.buyer.last_name,
      email: body.buyer.email,
    },
    source: {
      type: "PAYMENT_CARD",
      tokenId: body.card.tokenId,
      name: body.card.name,
    },
    line_items: body.cart,
    metadata: { cart_id: body.cart_id },
  });

  if (result.data.orderId) {
    await easy.updateOrderTags(result.data.orderId, {
      cart_id: body.cart_id,
      fulfilment_state: "queued",
    });
  }

  return result.data;
}
```

### 3. Mark fulfilment complete [#3-mark-fulfilment-complete]

```ts
async function markShipped(orderId: string, trackingNumber: string) {
  const { data: order } = await easy.getOrder(orderId);
  await easy.updateOrderTags(orderId, {
    ...order.tags,
    fulfilment_state: "shipped",
    tracking_number: trackingNumber,
  });
}
```

### 4. Cancel + refund [#4-cancel--refund]

```ts
async function cancelAndRefund(orderId: string, reason: string) {
  const { data: order } = await easy.getOrder(orderId);
  if (!order.transfer) throw new Error("Order has no captured transfer.");
  await easy.createRefund(order.transfer.id, {
    refund_amount: order.transfer.amount,
    tags: { reason, source: "support_console" },
  });
  await easy.updateOrderTags(orderId, {
    ...order.tags,
    fulfilment_state: "cancelled",
    cancellation_reason: reason,
  });
}
```

## Tradeoffs [#tradeoffs]

* **`checkout` does a lot.** It creates the customer, instrument, order, and transfer in one call. If you need to insert validation between steps (KYC, fraud rules, address verification), call `createCustomer` → `createPaymentInstrument` → `createTransfer` separately and wrap them in your own state machine.
* **Idempotency.** `checkout` doesn't accept an idempotency key today. Dedupe at the application layer — store `cart_id` in `metadata` and refuse a second submission that maps to the same cart.
* **Returning customers.** Switch the call to `customer_creation: false` and pass the saved `identity_id` + a stored `instrument_id` (string) so you charge a saved card without prompting again.
* **Subscriptions in the same cart.** If the cart contains a recurring price, `result.data.subscriptions` is populated — link those subscription IDs back to your local user record.
* **Refund accumulation.** Partial refunds add up against the original capture; the API returns 422 if you exceed it.


# Fastify integration (/docs/sdks/node/examples/fastify)



A complete, runnable Fastify example lives at `easy-sdk/examples/node`. This page is a guided tour — it points to the most-relevant files in that example so you can see the SDK wired into a real project, not just isolated snippets.

## Source code [#source-code]

* **Repository:** [`itseasyco/easy-sdk`](https://github.com/itseasyco/easy-sdk)
* **Path:** [`examples/node`](https://github.com/itseasyco/easy-sdk/tree/main/examples/node)
* **README:** [`examples/node/README.md`](https://github.com/itseasyco/easy-sdk/blob/main/examples/node/README.md)

## What this example covers [#what-this-example-covers]

* Initializing the SDK once at startup as a Fastify plugin.
* Customer CRUD (`getCustomers`, `getCustomer`, `createCustomer`, `updateCustomer`).
* Storing payment instruments (`createPaymentInstrument`, `updatePaymentInstrument`).
* Charging via the all-in-one `checkout` flow — both the `customer_creation: true` and `customer_creation: false` branches.
* Product + price CRUD (`createProduct`, `createPrice`, archive).
* Subscription lifecycle (`createSubscription`, `cancelSubscription`).
* Direct transfers (`createTransfer`, `getTransfer`).
* Generated OpenAPI documentation served at `/documentation` so you can poke every endpoint from a browser.

## Key files [#key-files]

| File                                                                                                                                                                                                                                                   | Demonstrates                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| [`src/server.ts`](https://github.com/itseasyco/easy-sdk/blob/main/examples/node/src/server.ts)                                                                                                                                                         | Fastify bootstrap: `helmet`, `sensible`, Swagger UI, autoloaded plugins and routes.            |
| [`src/plugins/easy-client.ts`](https://github.com/itseasyco/easy-sdk/blob/main/examples/node/src/plugins/easy-client.ts)                                                                                                                               | Wraps `createClient` in a Fastify plugin and decorates the instance with `fastify.easyClient`. |
| [`src/routes/customers/index.ts`](https://github.com/itseasyco/easy-sdk/blob/main/examples/node/src/routes/customers/index.ts)                                                                                                                         | List / get / create / update via `fastify.easyClient.getCustomers(...)`, etc.                  |
| [`src/routes/checkout/index.ts`](https://github.com/itseasyco/easy-sdk/blob/main/examples/node/src/routes/checkout/index.ts)                                                                                                                           | Splits `CreateCheckoutSession` on `customer_creation` to expose two endpoints.                 |
| [`src/routes/subscriptions/index.ts`](https://github.com/itseasyco/easy-sdk/blob/main/examples/node/src/routes/subscriptions/index.ts)                                                                                                                 | Subscription create + cancel.                                                                  |
| [`src/routes/products/index.ts`](https://github.com/itseasyco/easy-sdk/blob/main/examples/node/src/routes/products/index.ts), [`src/routes/prices/index.ts`](https://github.com/itseasyco/easy-sdk/blob/main/examples/node/src/routes/prices/index.ts) | Catalog management.                                                                            |

The plugin is the most-copied file:

```ts
// src/plugins/easy-client.ts
import { createClient } from "@easylabs/node";
import type { FastifyPluginAsync } from "fastify";
import fp from "fastify-plugin";

declare module "fastify" {
  interface FastifyInstance {
    easyClient: Awaited<ReturnType<typeof createClient>>;
  }
}

const easyClientPlugin: FastifyPluginAsync = async (fastify) => {
  if (!process.env.EASY_API_KEY) {
    throw new Error("EASY_API_KEY environment variable is required");
  }
  const client = await createClient({ apiKey: process.env.EASY_API_KEY });
  fastify.decorate("easyClient", client);
};

export default fp(easyClientPlugin, { name: "easy-client" });
```

## Run it locally [#run-it-locally]

```bash
git clone https://github.com/itseasyco/easy-sdk.git
cd easy-sdk
pnpm install
pnpm --filter node-example build  # builds the workspace deps

cd examples/node
echo "EASY_API_KEY=sk_test_..." > .env.local
pnpm dev
# Visit http://localhost:8008/documentation
```

## Adapting it [#adapting-it]

* **Webhooks.** The example doesn't ship a webhook route. Add one with `fastify.addContentTypeParser("application/json", { parseAs: "string" }, …)` so you can pass the raw body to `EasyWebhooks.constructEvent`. See [Webhooks](../webhooks#fastify) for the full snippet.
* **Per-request error handling.** Today routes catch errors locally and return `{ error: "..." }`. Switch to a global `setErrorHandler` that branches on `err instanceof EasyApiError` (status + code) for a consistent API surface.
* **Multi-tenant.** Replace the singleton plugin with a request-scoped factory keyed on tenant ID — see [Authentication → Multi-tenant](../authentication#multi-tenant-authentication).
* **Strip `__dev`.** The example sets `__dev: true` for local convenience. In production, omit it — the SDK picks the URL from your key prefix.


# Next.js integration (/docs/sdks/node/examples/nextjs)



A complete, runnable Next.js example lives at `easy-sdk/examples/next-example`. This page is a guided tour — it points to the most-relevant files in that example so you can see the SDK wired into a real project, not just isolated snippets.

## Source code [#source-code]

* **Repository:** [`itseasyco/easy-sdk`](https://github.com/itseasyco/easy-sdk)
* **Path:** [`examples/next-example`](https://github.com/itseasyco/easy-sdk/tree/main/examples/next-example)

## What this example covers [#what-this-example-covers]

* Customer signup with a synced local user record (Prisma) and an Easy customer.
* Admin dashboards backed by Server Components + Server Actions hitting the SDK.
* Product / price catalog management (create, edit, archive — both products and prices).
* Subscription lifecycle (list, create, cancel).
* Order detail pages with refund / fulfilment actions.
* Disputes triage screen.
* Revenue + analytics widgets.
* Profile screen with stored payment instruments.

## Key files [#key-files]

| File                                                                                                                                                     | Demonstrates                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| [`src/lib/easy-sync.ts`](https://github.com/itseasyco/easy-sdk/blob/main/examples/next-example/src/lib/easy-sync.ts)                                     | Lazy singleton (`getEasyClient`) wrapping `createClient` so a single SDK instance is reused across server-side modules. |
| [`src/app/api/auth/signup/route.ts`](https://github.com/itseasyco/easy-sdk/blob/main/examples/next-example/src/app/api/auth/signup/route.ts)             | Route Handler that creates a local user + an Easy customer in one step.                                                 |
| [`src/app/admin/products/actions.ts`](https://github.com/itseasyco/easy-sdk/blob/main/examples/next-example/src/app/admin/products/actions.ts)           | Server Actions calling `createProduct`, `updateProduct`, `archiveProduct`.                                              |
| [`src/app/admin/subscriptions/actions.ts`](https://github.com/itseasyco/easy-sdk/blob/main/examples/next-example/src/app/admin/subscriptions/actions.ts) | `createSubscription`, `cancelSubscription` from a Server Action invoked by a Client Component.                          |
| [`src/app/admin/orders/[id]/actions.ts`](https://github.com/itseasyco/easy-sdk/blob/main/examples/next-example/src/app/admin/orders/\[id]/actions.ts)    | Order detail mutations (`updateOrderTags`, refund flows).                                                               |
| [`src/app/admin/disputes/actions.ts`](https://github.com/itseasyco/easy-sdk/blob/main/examples/next-example/src/app/admin/disputes/actions.ts)           | Dispute triage (`acceptDispute`, `updateDispute`, evidence upload).                                                     |
| [`src/app/checkout/page.tsx`](https://github.com/itseasyco/easy-sdk/blob/main/examples/next-example/src/app/checkout/page.tsx)                           | Buyer-side checkout wiring (delegates to `@easylabs/react` for the UI).                                                 |

The lazy-singleton pattern is what most teams copy first:

```ts
// src/lib/easy-sync.ts
import { createClient } from "@easylabs/node";

let easyClient: Awaited<ReturnType<typeof createClient>> | null = null;

async function getEasyClient() {
  if (easyClient) return easyClient;
  if (!process.env.EASY_API_KEY) throw new Error("EASY_API_KEY is required");
  easyClient = await createClient({ apiKey: process.env.EASY_API_KEY });
  return easyClient;
}
```

Call `getEasyClient()` from any Server Component, Server Action, or Route Handler. Never import this module from a Client Component — the SDK is server-only.

## Run it locally [#run-it-locally]

```bash
git clone https://github.com/itseasyco/easy-sdk.git
cd easy-sdk
pnpm install
pnpm --filter next-example db:init   # provisions the local Prisma DB

cd examples/next-example
echo "EASY_API_KEY=sk_test_..." > .env.local
pnpm dev
# http://localhost:3000
```

## Adapting it [#adapting-it]

* **Cache the SDK at module scope.** Next.js may hot-reload modules in dev — the `let easyClient` cache survives normal renders but resets on reload. That's fine; the validation cost is low. In production it's effectively a process singleton.
* **Pin the runtime.** Set `export const runtime = "nodejs"` on Route Handlers and Server Actions that use the SDK — `@easylabs/node` depends on `node:crypto` / `FormData` and won't run on the Edge runtime.
* **Webhooks.** The example doesn't include a webhook route. Add one as a Route Handler with `await req.text()` to capture the raw body, then `EasyWebhooks.constructEvent(rawBody, sig, secret)`. See [Webhooks](../webhooks#nextjs-route-handler).
* **Tenant scoping.** Replace the singleton with a `Map<tenantId, Promise<EasyClient>>` cache keyed on the merchant ID resolved from the session.
* **Strip the `NEXT_PUBLIC_` prefix.** The example reads `NEXT_PUBLIC_EASY_API_KEY` for local dev convenience — do not deploy with a public-prefixed secret. Read from a non-public env var on the server.


# Refunds (/docs/sdks/node/examples/refunds)



Refunding orders end-to-end with `@easylabs/node` — covering full and partial refunds, automatic accept-on-dispute, and tying the reversal back to your local ledger.

## Goal [#goal]

A reusable refund service that:

1. Resolves the originating transfer from an order, invoice, or charge.
2. Applies a partial or full reversal.
3. Persists the reversal ID against your domain object for accounting.
4. Reacts to `dispute.created` webhooks by pre-emptively refunding low-value disputes.

## Implementation [#implementation]

### 1. Refund service [#1-refund-service]

```ts
import { createClient } from "@easylabs/node";
// EasyApiError ships from @easylabs/common; @easylabs/node re-exports the
// *type* but not the runtime value, so `instanceof` needs the common import.
import { EasyApiError } from "@easylabs/common";
const easy = await createClient({ apiKey: process.env.EASY_API_KEY! });

type RefundReason = "customer_request" | "duplicate" | "fraud" | "shipping_delay" | "dispute_received";

export async function refundOrder(
  orderId: string,
  amountCents: number | "full",
  reason: RefundReason,
  approvedBy: string,
) {
  const { data: order } = await easy.getOrder(orderId);
  if (!order.transfer) throw new Error("Order has no captured transfer.");
  if (order.transfer.state !== "SUCCEEDED") {
    throw new Error(`Cannot refund transfer in state ${order.transfer.state}.`);
  }

  const refund_amount = amountCents === "full" ? order.transfer.amount : amountCents;

  try {
    const reversal = await easy.createRefund(order.transfer.id, {
      refund_amount,
      tags: {
        reason,
        approved_by: approvedBy,
        order_number: order.order_number,
      },
    });

    // Persist reversal.data.id against the order in your DB
    return reversal.data;
  } catch (err) {
    if (err instanceof EasyApiError && err.status === 422) {
      // Probably trying to refund more than was captured
      throw new Error(`Refund rejected: ${err.message}`);
    }
    throw err;
  }
}
```

### 2. Auto-refund small disputes [#2-auto-refund-small-disputes]

```ts
import { EasyWebhooks } from "@easylabs/node";

export async function handleWebhook(rawBody: string, sigHeader: string) {
  const event = EasyWebhooks.constructEvent(
    rawBody,
    sigHeader,
    process.env.EASY_WEBHOOK_SECRET!,
  );

  if (event.type === "dispute.created") {
    const dispute = event.data as { id: string; amount: number; transfer?: { id: string } };
    if (dispute.amount < 1000 && dispute.transfer) {
      // Cheaper to refund than to fight
      await easy.createRefund(dispute.transfer.id, {
        refund_amount: dispute.amount,
        tags: { reason: "dispute_received", dispute_id: dispute.id },
      });
      await easy.acceptDispute(dispute.id);
    }
  }
}
```

### 3. Reconcile a reversal back to your ledger [#3-reconcile-a-reversal-back-to-your-ledger]

```ts
const reversal = await refundOrder(orderId, "full", "customer_request", "agent_42");
console.log({
  ledger_entry: "refund",
  amount_cents: reversal.amount,
  parent_transfer: reversal.parent_transfer,
  reversal_id: reversal.id,
  state: reversal.state,
});
```

## Tradeoffs [#tradeoffs]

* **No dedicated list endpoint.** To find every reversal for a transfer, list transfers and filter by `type === "REVERSAL"` and `parent_transfer === originalId`, or follow `_links.reversals.href` on the parent.
* **Partial-refund accumulation.** Multiple partial refunds add up against the original capture. The API returns 422 once you exceed it — handle that case in your service.
* **Pending state.** A new reversal starts as `state: "PENDING"` and only flips to `SUCCEEDED` when the funds clear back. Don't notify the customer "refunded" until you've seen the `payment.updated` (or refund-specific) webhook flip the state.
* **Disputes vs refunds.** A refund issued *after* a dispute is opened may not stop the dispute fee — `acceptDispute` is the cleanest way to close the case in the cardholder's favor.
* **Subscription invoice refunds.** Refunding a subscription's invoice transfer doesn't cancel the subscription. If the customer wants to stop billing too, also call `cancelSubscription(subId, { at_period_end: false })`.


# Subscription System (/docs/sdks/node/examples/subscription-system)



A complete subscription system on `@easylabs/node`: pricing catalog, signup with trial, in-flight upgrade with proration preview, metered usage reporting, dunning, and cancellation at period end.

## Goal [#goal]

Everything you need to ship a B2B SaaS with monthly + yearly tiers, optional metered add-ons, and graceful failed-payment handling — all driven by the SDK plus webhooks.

## Implementation [#implementation]

### 1. Catalog [#1-catalog]

```ts
const product = await easy.createProduct({ name: "Pro plan", active: true });

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

const yearly = await easy.createPrice({
  product_id: product.data.id,
  active: true,
  recurring: true,
  currency: "USD",
  unit_amount: 49000, // $490 — 2 months free
  interval: "year",
  interval_count: 1,
  tax_behavior: "exclusive",
});

const meteredApiCalls = await easy.createPrice({
  product_id: product.data.id,
  active: true,
  recurring: true,
  currency: "USD",
  unit_amount: 1, // $0.01 per unit
  interval: "month",
  interval_count: 1,
  tax_behavior: "exclusive",
  pricing_model: "metered",
});
```

### 2. Signup with a 14-day trial [#2-signup-with-a-14-day-trial]

```ts
const sub = await easy.createSubscription({
  identity_id: customer.id,
  items: [
    { price_id: monthly.data.id, quantity: 1 },
    { price_id: meteredApiCalls.data.id }, // qty driven by usage reports
  ],
  instrument_id: paymentInstrumentId,
  trial_period_days: 14,
  metadata: { plan: "pro_monthly" },
});
```

### 3. Upgrade with proration preview [#3-upgrade-with-proration-preview]

```ts
const preview = await easy.getSubscriptionProrationPreview(sub.data.id, {
  items: [{ price_id: yearly.data.id, quantity: 1 }],
  remove_items: [
    sub.data.items.find((i) => i.price_id === monthly.data.id)!.id,
  ],
});

// Show preview.data to the user, then commit:
await easy.updateSubscription(sub.data.id, {
  items: [{ price_id: yearly.data.id, quantity: 1 }],
  remove_items: [
    sub.data.items.find((i) => i.price_id === monthly.data.id)!.id,
  ],
  proration_behavior: "create_prorations",
});
```

### 4. Metered usage [#4-metered-usage]

```ts
import { randomUUID } from "node:crypto";

async function reportApiCall(subscriptionId: string, itemId: string) {
  await easy.reportSubscriptionUsage(subscriptionId, {
    subscription_item_id: itemId,
    quantity: 1,
    action: "increment",
    timestamp: new Date().toISOString(),
    idempotency_key: randomUUID(),
  });
}

// Period summary for an in-app dashboard:
const summary = await easy.getSubscriptionUsageSummary(sub.data.id, {
  subscription_item_id: meteredItemId,
  from: periodStart,
  to: periodEnd,
});
```

### 5. Dunning [#5-dunning]

```ts
await easy.createOrReplaceDunningConfig({
  retry_mode: "smart",
  smart_retry_attempts: 8,
  smart_retry_window: "2_weeks",
  subscription_terminal_action: "cancel",
  invoice_terminal_action: "uncollectible",
  payment_failed_email_enabled: true,
  expiring_card_email_enabled: true,
  card_expiry_warn_days: 30,
});
```

Wire your webhook handler to react to `invoice.payment_failed`, `subscription.paused`, and `subscription.deleted` — see [Webhooks](../webhooks).

### 6. Cancellation at period end [#6-cancellation-at-period-end]

```ts
await easy.cancelSubscription(sub.data.id, { at_period_end: true });
```

### 7. Discount on retention [#7-discount-on-retention]

```ts
const winback = await easy.createCoupon({
  duration: "repeating",
  duration_in_months: 3,
  percent_off: 50,
  name: "Winback offer",
});
await easy.applySubscriptionDiscount(sub.data.id, { coupon_id: winback.data.id });
```

## Tradeoffs [#tradeoffs]

* **Trial accounting.** Pass `trial_period_days` (or `trial_end`) at create time *and* set `instrument_id` so the card is on file for the first paid charge. Listen for `subscription.trial_will_end` to nudge users 3 days out.
* **Proration policy.** `"create_prorations"` issues credits/charges immediately; `"none"` defers everything to the next invoice. Preview first if your users are price-sensitive.
* **Metered idempotency.** Reuse the upstream event ID (e.g. webhook delivery ID) as `idempotency_key` so retries don't double-bill.
* **Cancellation timing.** `at_period_end: true` keeps service active until renewal; omit it for instant termination + final invoice.
* **Multiple plans on one subscription.** A single `SubscriptionData` may carry many `items` (e.g. base seat + metered calls + storage). Use `addSubscriptionItem` / `removeSubscriptionItem` for granular changes.


# Analytics (/docs/sdks/node/resources/analytics)



Analytics endpoints aggregate transactions, disputes, settlements, revenue, and revenue-recovery activity over a date range. Each method accepts the same `AnalyticsQuery` and returns an open-ended JSON shape suitable for dashboards or warehouse loads.

## Methods [#methods]

```ts
easy.getTransactionAnalytics(params?);     // GET /analytics/transactions
easy.getDisputeAnalytics(params?);         // GET /analytics/disputes
easy.getSettlementAnalytics(params?);      // GET /analytics/settlements
easy.getRevenueAnalytics(params?);         // GET /analytics/revenue
easy.getRevenueRecoveryAnalytics(params?); // GET /analytics/revenue-recovery
```

`AnalyticsQuery`:

```ts
type AnalyticsQuery = {
  period?: "day" | "week" | "month";
  start_date?: string;   // ISO date or datetime
  end_date?: string;
};
```

```ts
const monthly = await easy.getRevenueAnalytics({
  period: "month",
  start_date: "2026-01-01",
  end_date: "2026-04-30",
});

const weekly = await easy.getDisputeAnalytics({
  period: "week",
  start_date: "2026-04-01",
});
```

## Object shape [#object-shape]

Each analytics method returns `ApiResponse<Record<string, unknown>>` — the SDK does not narrow the response shape because the aggregations are computed server-side and may include slice-specific fields. Refer to the API reference for the canonical schema of each report. {/* TODO: tighten the analytics response types as the schemas stabilize. */}

## Examples [#examples]

### Daily revenue chart for the current quarter [#daily-revenue-chart-for-the-current-quarter]

```ts
const start = "2026-04-01";
const end = "2026-06-30";
const daily = await easy.getRevenueAnalytics({ period: "day", start_date: start, end_date: end });
// pipe daily.data into your charting library
```

### Build a recovery-rate KPI [#build-a-recovery-rate-kpi]

```ts
const recovery = await easy.getRevenueRecoveryAnalytics({
  period: "month",
  start_date: "2026-01-01",
  end_date: "2026-12-31",
});
// recovery.data shape is open — inspect once and code your KPI extractor against the live response.
```

### Snapshot for a board deck [#snapshot-for-a-board-deck]

```ts
const [tx, disputes, settlements] = await Promise.all([
  easy.getTransactionAnalytics({ period: "month" }),
  easy.getDisputeAnalytics({ period: "month" }),
  easy.getSettlementAnalytics({ period: "month" }),
]);
```


# Authorizations (/docs/sdks/node/resources/authorizations)



An authorization is a hold on funds you can later capture in part or in full. Use it for marketplaces, hotels, rentals, or any flow where the final amount isn't known when the customer pays.

## Methods [#methods]

```ts
easy.listAuthorizations(params?);                   // GET    /authorizations
easy.getAuthorization(authorizationId);             // GET    /authorizations/:id
easy.captureAuthorization(authorizationId, amount); // POST   /authorizations/:id/capture
easy.voidAuthorization(authorizationId);            // POST   /authorizations/:id/void
```

```ts
const auths = await easy.listAuthorizations({ limit: 25 });
const { data: auth } = await easy.getAuthorization(auths.data[0].id);

// Capture a portion of the held amount:
await easy.captureAuthorization(auth.id, 7500); // smallest currency unit

// Or release the hold without capturing:
await easy.voidAuthorization(auth.id);
```

There is no `createAuthorization` method on the SDK — authorizations are produced by upstream charge APIs (auth-and-capture flows initiated through `checkout` or the embedded checkout) rather than created directly.

`captureAuthorization` requires the `amount` to be ≤ `auth.amount_requested`. Capturing 0 is not permitted; void instead.

## Object shape [#object-shape]

`AuthorizationData`:

| Field                                 | Type                                                                         | Notes                                                      |
| ------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `id`                                  | `string`                                                                     |                                                            |
| `amount` / `amount_requested`         | `number`                                                                     | Captured amount and original hold, smallest currency unit. |
| `currency`                            | `string`                                                                     | ISO 4217.                                                  |
| `state`                               | `"PENDING" \| "SUCCEEDED" \| "FAILED" \| "VOIDED" \| "CAPTURED"` (or string) |                                                            |
| `source` / `destination` / `merchant` | `string \| null`                                                             |                                                            |
| `failure_code` / `failure_message`    | `string \| null`                                                             | Populated on `FAILED`.                                     |
| `trace_id`                            | `string \| null`                                                             |                                                            |
| `tags`                                | `Record<string, string> \| null`                                             |                                                            |
| `expires_at`                          | `string \| null`                                                             | After this, the network releases the hold automatically.   |
| `captured_at` / `voided_at`           | `string \| null`                                                             |                                                            |

## Examples [#examples]

### Capture less than the original hold [#capture-less-than-the-original-hold]

```ts
await easy.captureAuthorization(authId, finalCartTotalCents);
```

### Auto-void expiring holds [#auto-void-expiring-holds]

```ts
const stale = (await easy.listAuthorizations({ limit: 100 })).data.filter(
  (a) => a.state === "PENDING" && a.expires_at && Date.parse(a.expires_at) < Date.now(),
);
for (const a of stale) await easy.voidAuthorization(a.id);
```

### React to an authorization webhook [#react-to-an-authorization-webhook]

```ts
if (event.type === "authorization.updated") {
  const auth = event.data as { id: string; state: string };
  if (auth.state === "SUCCEEDED") {
    await easy.captureAuthorization(auth.id, finalAmountCents);
  }
}
```


# Checkout (/docs/sdks/node/resources/checkout)



`checkout` is the all-in-one charge endpoint: in a single request it can create a customer, create a payment instrument, create line-item-backed orders / subscriptions, and capture the transfer. It exists as one method on the SDK — `easy.checkout(...)` — backed by `POST /checkout`.

For embedded UI flows, see [Embedded Checkout](./embedded-checkout). For shareable hosted pages, see [Payment Links](./payment-links).

## Methods [#methods]

### `checkout(session)` [#checkoutsession]

`POST /checkout`. Returns `ApiResponse<{ transfer?: TransferData; orderId?: string; subscriptions: (SubscriptionData & { order_id: string; order_number: string })[] }>`.

The request body is a discriminated union (`CreateCheckoutSession`):

```ts
type CreateCheckoutSession =
  | {
      customer_creation: true;
      customer_details: CreateCustomer;
      source: Omit<CreatePaymentInstrument, "identityId">;
      line_items: { price_id: string; quantity: number }[];
      metadata?: Record<string, string>;
    }
  | {
      customer_creation: false;
      identity_id: string;
      source: Omit<CreatePaymentInstrument, "identityId"> | string; // existing instrument ID or new instrument
      line_items: { price_id: string; quantity: number }[];
      metadata?: Record<string, string>;
    };
```

### New customer [#new-customer]

```ts
const result = await easy.checkout({
  customer_creation: true,
  customer_details: {
    first_name: "Ada",
    last_name: "Lovelace",
    email: "ada@example.com",
  },
  source: {
    type: "PAYMENT_CARD",
    tokenId: cardTokenFromFrontend,
    name: "Ada Lovelace",
  },
  line_items: [{ price_id: "PR_...", quantity: 1 }],
  metadata: { cart_id: "cart_42" },
});

console.log(result.data.transfer?.id, result.data.subscriptions);
```

### Existing customer + new card [#existing-customer--new-card]

```ts
await easy.checkout({
  customer_creation: false,
  identity_id: customer.id,
  source: {
    type: "PAYMENT_CARD",
    tokenId: cardTokenFromFrontend,
    name: "Ada Lovelace",
  },
  line_items: [{ price_id: "PR_...", quantity: 2 }],
});
```

### Existing customer + saved instrument [#existing-customer--saved-instrument]

```ts
await easy.checkout({
  customer_creation: false,
  identity_id: customer.id,
  source: instrumentId, // string ID of a previously stored instrument
  line_items: [{ price_id: "PR_...", quantity: 1 }],
});
```

## Object shape [#object-shape]

The successful response shape:

| Field           | Type                                                | Notes                                                                                  |
| --------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `transfer`      | `TransferData \| undefined`                         | The captured charge — undefined for subscription-only carts where billing is deferred. |
| `orderId`       | `string \| undefined`                               | The order created for one-time line items.                                             |
| `subscriptions` | `(SubscriptionData & { order_id, order_number })[]` | One subscription per recurring price in the cart.                                      |

`line_items` may freely mix one-time and recurring prices — Easy Labs charges the one-time amount up front via `transfer` and creates one subscription per recurring price.

## Examples [#examples]

### Mixed cart (one-time + subscription) [#mixed-cart-one-time--subscription]

```ts
await easy.checkout({
  customer_creation: false,
  identity_id: customer.id,
  source: instrumentId,
  line_items: [
    { price_id: "PR_setup_fee_oneTime", quantity: 1 },
    { price_id: "PR_monthly_plan", quantity: 1 },
  ],
});
```

### Surface decline reasons [#surface-decline-reasons]

```ts
// EasyApiError is the runtime class from @easylabs/common; @easylabs/node
// re-exports the *type* but not the value, so import from common directly.
import { EasyApiError } from "@easylabs/common";

try {
  await easy.checkout({ /* … */ });
} catch (err) {
  if (err instanceof EasyApiError && err.status === 402) {
    // Card declined — show the message from err.details to the buyer.
  } else {
    throw err;
  }
}
```


# Compliance Forms (/docs/sdks/node/resources/compliance-forms)



Compliance forms (e.g. card-network agreements, sponsor disclosures) are issued to your company by Easy Labs and must be signed before certain product capabilities are unlocked. The SDK lets you list pending and historical forms, fetch one by ID, and submit a signature.

## Methods [#methods]

```ts
easy.listComplianceForms();                      // GET /compliance-forms
easy.getComplianceForm(formId);                  // GET /compliance-forms/:id
easy.signComplianceForm(formId, body);           // PUT /compliance-forms/:id/sign
```

```ts
const forms = await easy.listComplianceForms();
const pending = forms.data.filter((f) => f.status !== "signed");

for (const f of pending) {
  await easy.signComplianceForm(f.id, {
    name: "Ada Lovelace",
    title: "CEO",
  });
}
```

## Object shape [#object-shape]

`ComplianceFormData`:

| Field                          | Type                      | Notes                                       |
| ------------------------------ | ------------------------- | ------------------------------------------- |
| `id`                           | `string`                  |                                             |
| `type`                         | `string`                  | The form template, e.g. card-network terms. |
| `status`                       | `string`                  | `pending`, `signed`, etc.                   |
| `signed_at`                    | `string \| null`          | ISO timestamp.                              |
| `signed_name` / `signed_title` | `string \| null`          |                                             |
| `due_at`                       | `string \| null`          | Deadline before features lock.              |
| `metadata`                     | `Record<string, unknown>` |                                             |

`SignComplianceForm` body: `{ name: string; title: string }`.

## Examples [#examples]

### Block deploys when a form is overdue [#block-deploys-when-a-form-is-overdue]

```ts
const forms = await easy.listComplianceForms();
const overdue = forms.data.filter(
  (f) => f.status !== "signed" && f.due_at && Date.parse(f.due_at) < Date.now(),
);
if (overdue.length) {
  throw new Error(`Sign these compliance forms first: ${overdue.map((f) => f.type).join(", ")}`);
}
```

### Audit who signed what [#audit-who-signed-what]

```ts
const forms = await easy.listComplianceForms();
console.table(
  forms.data.filter((f) => f.signed_at).map((f) => ({
    type: f.type,
    signed_by: `${f.signed_name} (${f.signed_title})`,
    signed_at: f.signed_at,
  })),
);
```


# Coupons (/docs/sdks/node/resources/coupons)



A coupon is a reusable discount template — percentage-off or fixed-amount, applied once / for N months / forever. Coupons are attached to subscriptions via [`applySubscriptionDiscount`](./subscriptions#discounts) or surfaced to buyers through [promotion codes](./promotion-codes).

## Methods [#methods]

```ts
easy.createCoupon(body);          // POST   /coupons
easy.listCoupons(params?);        // GET    /coupons
easy.getCoupon(couponId);         // GET    /coupons/:id
easy.updateCoupon(couponId, body); // PATCH  /coupons/:id
easy.deleteCoupon(couponId);      // DELETE /coupons/:id
```

`CreateCoupon` is a discriminated union — pass `percent_off` **or** `amount_off + currency`, never both:

```ts
// Percentage off
await easy.createCoupon({
  duration: "repeating",
  duration_in_months: 3,
  percent_off: 25,
  name: "Q2 promo",
  max_redemptions: 1000,
  valid_until: "2026-06-30T23:59:59Z",
  applies_to_products: ["PD_pro"],
  metadata: { campaign: "spring_2026" },
});

// Fixed amount off (smallest currency unit)
await easy.createCoupon({
  duration: "once",
  amount_off: 1000,
  currency: "USD",
  name: "$10 welcome credit",
});
```

`UpdateCoupon` is intentionally narrow — only `name`, `active`, and `metadata` are mutable. To change the discount itself, create a new coupon and migrate users.

## Object shape [#object-shape]

`CouponData`:

| Field                 | Type                                 | Notes                                     |
| --------------------- | ------------------------------------ | ----------------------------------------- |
| `id`                  | `string`                             |                                           |
| `name`                | `string \| null`                     |                                           |
| `duration`            | `"once" \| "repeating" \| "forever"` |                                           |
| `duration_in_months`  | `number \| null`                     | Only set when `duration === "repeating"`. |
| `percent_off`         | `number \| null`                     | 0–100.                                    |
| `amount_off`          | `number \| null`                     | Smallest currency unit.                   |
| `currency`            | `string \| null`                     | Required with `amount_off`.               |
| `max_redemptions`     | `number \| null`                     | Lifetime cap.                             |
| `times_redeemed`      | `number`                             | Counter.                                  |
| `valid_until`         | `string \| null`                     | ISO timestamp.                            |
| `applies_to_products` | `string[] \| null`                   | Restrict eligibility.                     |
| `active`              | `boolean`                            |                                           |
| `metadata`            | `Record<string, unknown>`            |                                           |

## Examples [#examples]

### Forever 50%-off VIP coupon [#forever-50-off-vip-coupon]

```ts
const coupon = await easy.createCoupon({
  duration: "forever",
  percent_off: 50,
  name: "VIP",
});
```

### Pause a coupon without deleting redemptions [#pause-a-coupon-without-deleting-redemptions]

```ts
await easy.updateCoupon(couponId, { active: false });
```

### List active coupons [#list-active-coupons]

```ts
const all = await easy.listCoupons({ limit: 100 });
const active = all.data.filter((c) => c.active);
```


# Customers (/docs/sdks/node/resources/customers)



A customer is the buyer-side identity that owns payment instruments, orders, subscriptions, and wallets. Create one before charging via the standalone resource flow, or skip ahead and let `checkout({ customer_creation: true })` create the customer + instrument inline.

## Methods [#methods]

### `createCustomer(customer)` [#createcustomercustomer]

`POST /customer`. Returns `ApiResponse<CustomerData>`.

```ts
const { data: customer } = await easy.createCustomer({
  first_name: "Ada",
  last_name: "Lovelace",
  email: "ada@example.com",
  phone: "+15555550101",
  personal_address: {
    line1: "1 Pioneer Way",
    city: "Menlo Park",
    region: "CA",
    postal_code: "94025",
    country: "USA",
  },
  tags: { signup_source: "web" },
});
```

### `updateCustomer(customerId, partial)` [#updatecustomercustomerid-partial]

`PATCH /customer/:id`. Accepts a `Partial<CreateCustomer>`.

```ts
await easy.updateCustomer(customer.id, { phone: "+15555550199" });
```

### `getCustomer(customerId)` [#getcustomercustomerid]

`GET /customer/:id`.

### `getCustomers(params?)` [#getcustomersparams]

`GET /customer`. Standard `PaginationParams` (`limit`, `offset`, `ids[]`).

```ts
const { data: customers } = await easy.getCustomers({ limit: 50, offset: 0 });
```

### `getCustomerPaymentInstruments(customerId)` [#getcustomerpaymentinstrumentscustomerid]

`GET /customer/:id/instruments`. Returns the customer's stored cards and bank accounts.

### `getCustomerOrders(customerId, params?)` [#getcustomerorderscustomerid-params]

`GET /customer/:id/orders`.

### `getCustomerSubscriptions(customerId, params?)` [#getcustomersubscriptionscustomerid-params]

`GET /customer/:id/subscriptions`. Adds an optional `status?: SubscriptionStatus` filter alongside pagination, and returns a `Paginated<SubscriptionData>` envelope (`{ data, total, limit, offset }`).

```ts
const page = await easy.getCustomerSubscriptions(customer.id, {
  status: "ACTIVE",
  limit: 25,
});
console.log(page.data.total, page.data.data.length);
```

### `getCustomerWallets(customerId, params?)` [#getcustomerwalletscustomerid-params]

`GET /customer/:id/wallets`. Connected crypto wallets.

## Object shape [#object-shape]

`CustomerData` mirrors the underlying entity record: top-level `id`, `created_at`, `updated_at`, `tags` (string-valued bag including `company_id`), `entity` (the full PII / merchant-onboarding record), `identity_roles`, and `_links`. Refer to the API reference for the canonical schema; the SDK re-exports the type as `CustomerData` from `@easylabs/node`.

## Examples [#examples]

### Idempotent upsert by email [#idempotent-upsert-by-email]

The API does not enforce email uniqueness — implement upsert in user code by listing first:

```ts
async function upsertCustomerByEmail(email: string, defaults: { first_name: string; last_name: string }) {
  const all = await easy.getCustomers({ limit: 100 });
  const existing = all.data.find((c) => c.entity.email === email);
  if (existing) return existing;
  const { data } = await easy.createCustomer({ ...defaults, email });
  return data;
}
```

### Walk every order for a customer [#walk-every-order-for-a-customer]

```ts
async function ordersFor(customerId: string) {
  const limit = 100;
  let offset = 0;
  const acc = [];
  while (true) {
    const { data } = await easy.getCustomerOrders(customerId, { limit, offset });
    acc.push(...data);
    if (data.length < limit) break;
    offset += limit;
  }
  return acc;
}
```

### Tag-driven partial update [#tag-driven-partial-update]

```ts
await easy.updateCustomer(customer.id, {
  tags: { ...customer.tags, kyc_status: "verified" },
});
```


# Disputes (/docs/sdks/node/resources/disputes)



A dispute is opened by the cardholder's bank to challenge a charge. The SDK lets you list and read disputes, attach tags, accept the chargeback, upload evidence files, and submit the response back to the network.

## Methods [#methods]

```ts
easy.getDisputes(params?);                          // GET    /disputes
easy.getDispute(disputeId);                         // GET    /disputes/:id
easy.updateDispute(disputeId, tags);                // PATCH  /disputes/:id (tags only)
easy.acceptDispute(disputeId);                      // POST   /disputes/:id/accept
easy.uploadDisputeEvidence(disputeId, file);        // POST   /disputes/:id/evidence (multipart)
easy.listDisputeEvidence(disputeId);                // GET    /disputes/:id/evidence
easy.submitDisputeEvidence(disputeId);              // POST   /disputes/:id/submit
```

### Read [#read]

```ts
const disputes = await easy.getDisputes({ limit: 50 });
const { data: dispute } = await easy.getDispute(disputes.data[0].id);
```

### Tag for triage [#tag-for-triage]

`updateDispute` only writes `tags`. The body shape is the new tag bag (server replaces, does not merge):

```ts
await easy.updateDispute(disputeId, {
  triage_owner: "agent_42",
  intended_response: "challenge",
});
```

### Accept the chargeback [#accept-the-chargeback]

Forfeits the disputed funds and closes the case in the bank's favor — no evidence is sent.

```ts
await easy.acceptDispute(disputeId);
```

### Upload + submit evidence [#upload--submit-evidence]

`uploadDisputeEvidence` sends `multipart/form-data` and bypasses the SDK's JSON content-type. Each file must be a `Blob` or `File` (Node 22's global `File` works), max 1 MB, allowed types `image/jpeg`, `image/png`, `application/pdf`.

```ts
import { readFile } from "node:fs/promises";

const bytes = await readFile("./receipt.pdf");
await easy.uploadDisputeEvidence(
  disputeId,
  new File([bytes], "receipt.pdf", { type: "application/pdf" }),
);

await easy.uploadDisputeEvidence(disputeId, /* … another file … */);

const evidence = await easy.listDisputeEvidence(disputeId);
console.log(`Attached ${evidence.data.length} files.`);

// When ready, submit the bundle:
await easy.submitDisputeEvidence(disputeId);
```

Once submitted, the response is locked in — uploads after `submitDisputeEvidence` are rejected.

## Object shape [#object-shape]

`DisputeData` mirrors the underlying processor record (snake\_case identifiers, state, amounts, network reason codes, deadlines). Refer to the API reference for the canonical schema; the SDK re-exports it as `DisputeData` from `@easylabs/node`. `DisputeEvidenceData` is currently typed as `{ id: string; [key: string]: unknown }` — refer to the API reference for the file metadata fields. {/* TODO: tighten DisputeEvidenceData once the schema stabilizes. */}

## Examples [#examples]

### Webhook-driven response workflow [#webhook-driven-response-workflow]

```ts
import { EasyWebhooks } from "@easylabs/node";

if (event.type === "dispute.created") {
  const dispute = event.data as { id: string; amount: number };
  if (dispute.amount < 1000) {
    await easy.acceptDispute(dispute.id); // not worth fighting
  } else {
    await easy.updateDispute(dispute.id, { triage_owner: "queue:dispute_team" });
  }
}
```

### Bulk-list open disputes [#bulk-list-open-disputes]

```ts
let offset = 0;
const open = [];
while (true) {
  const page = await easy.getDisputes({ limit: 100, offset });
  open.push(...page.data);
  if (page.data.length < 100) break;
  offset += 100;
}
```


# Dunning (/docs/sdks/node/resources/dunning)



Dunning controls what happens when a recurring charge fails: how often Easy Labs retries, what email goes out, what the recovery page looks like, and what the subscription / invoice transitions to once retries are exhausted. Revenue-recovery *automations* layer on top — event-triggered, condition-gated, multi-action workflows (e.g. "after `invoice_overdue`, if amount > $500, email Sales").

## Methods [#methods]

### Dunning config [#dunning-config]

The dunning config is a singleton per company.

```ts
easy.createOrReplaceDunningConfig(body); // POST  /dunning-config
easy.getDunningConfig();                 // GET   /dunning-config
easy.updateDunningConfig(body);          // PATCH /dunning-config
```

```ts
await easy.createOrReplaceDunningConfig({
  retry_mode: "smart",
  smart_retry_attempts: 8,
  smart_retry_window: "2_weeks",
  bank_debit_retries_enabled: true,
  bank_debit_retry_schedule: [3, 7, 14],     // days after failure
  subscription_terminal_action: "cancel",     // "cancel" | "unpaid" | "past_due" | "pause"
  invoice_terminal_action: "uncollectible",   // "past_due" | "uncollectible"
  payment_failed_email_enabled: true,
  expiring_card_email_enabled: true,
  card_expiry_warn_days: 30,
  payment_failed_recovery_page_mode: "hosted",
  expiring_card_recovery_page_mode: "custom_link",
  expiring_card_custom_link_url: "https://app.example.com/billing/update-card",
});
```

Switch to `retry_mode: "custom"` to drive the cadence yourself with `custom_retry_schedule: number[]` (days after failure).

### Revenue-recovery automations [#revenue-recovery-automations]

```ts
easy.listRevenueRecoveryAutomations();             // GET    /revenue-recovery-automations
easy.createRevenueRecoveryAutomation(body);        // POST   /revenue-recovery-automations
easy.updateRevenueRecoveryAutomation(id, body);    // PATCH  /revenue-recovery-automations/:id
easy.deleteRevenueRecoveryAutomation(id);          // DELETE /revenue-recovery-automations/:id
easy.listRevenueRecoveryAutomationRuns(id);        // GET    /revenue-recovery-automations/:id/runs
```

```ts
await easy.createRevenueRecoveryAutomation({
  name: "Big-ticket overdue → Sales",
  trigger_type: "invoice_overdue",
  conditions: [
    { type: "invoice_amount", operator: "more_than", amount_cents: 50000 },
  ],
  actions: [
    {
      type: "email_team_member",
      delay_days: 0,
      recipient_email: "sales@example.com",
      note: "High-value overdue invoice — please follow up.",
    },
  ],
  active: true,
});
```

## Object shape [#object-shape]

### `DunningConfig` [#dunningconfig]

A single document. Highlights:

| Field                                                                                    | Type                                                            | Notes                                             |
| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------- |
| `retry_mode`                                                                             | `"smart" \| "custom"`                                           |                                                   |
| `smart_retry_attempts`                                                                   | `4 \| 8`                                                        | When `retry_mode = "smart"`.                      |
| `smart_retry_window`                                                                     | `"1_week" \| "2_weeks" \| "3_weeks" \| "1_month" \| "2_months"` |                                                   |
| `custom_retry_schedule`                                                                  | `number[]`                                                      | Days after failure, when `retry_mode = "custom"`. |
| `bank_debit_retries_enabled` / `bank_debit_retry_schedule`                               | `boolean` / `number[]`                                          | Bank-debit-specific retry policy.                 |
| `subscription_terminal_action`                                                           | `"cancel" \| "unpaid" \| "past_due" \| "pause"`                 | What happens when retries are exhausted.          |
| `invoice_terminal_action`                                                                | `"past_due" \| "uncollectible"`                                 |                                                   |
| `payment_failed_email_enabled` / `expiring_card_email_enabled` / `email_action_required` | `boolean`                                                       |                                                   |
| `card_expiry_warn_days`                                                                  | `number`                                                        |                                                   |
| `payment_failed_recovery_page_mode` / `expiring_card_recovery_page_mode`                 | `"hosted" \| "custom_link"`                                     |                                                   |
| `payment_failed_custom_link_url` / `expiring_card_custom_link_url`                       | `string \| null`                                                |                                                   |

### Revenue-recovery automation [#revenue-recovery-automation]

`CreateRevenueRecoveryAutomation`:

| Field          | Type                                                                                                                                           |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `trigger_type` | `"invoice_due_date_upcoming" \| "invoice_finalized" \| "invoice_overdue" \| "subscription_payment_failed" \| "subscription_canceled"`          |
| `conditions[]` | `{ type: "invoice_amount" \| "invoice_metadata" \| "product_on_invoice"; operator?, amount_cents?, key?, value?, product_id?, product_name? }` |
| `actions[]`    | `{ type: "email_team_member" \| "mark_invoice_uncollectible"; delay_days?, recipient_user_id?, recipient_email?, recipient_name?, note? }`     |
| `active`       | `boolean`                                                                                                                                      |

The list endpoint and run records are currently typed as `Record<string, unknown>[]` pending a stronger schema. {/* TODO: lock down the automation list/run shape once it stabilizes. */}

## Examples [#examples]

### Switch to custom retry cadence [#switch-to-custom-retry-cadence]

```ts
await easy.updateDunningConfig({
  retry_mode: "custom",
  custom_retry_schedule: [1, 3, 7, 14, 30],
});
```

### Disable a dunning automation without deleting it [#disable-a-dunning-automation-without-deleting-it]

```ts
await easy.updateRevenueRecoveryAutomation(automationId, { active: false });
```

### Audit recent runs [#audit-recent-runs]

```ts
const runs = await easy.listRevenueRecoveryAutomationRuns(automationId);
console.table(runs.data);
```


# Embedded Checkout (/docs/sdks/node/resources/embedded-checkout)



Embedded checkout creates a server-side session that the browser opens in an iframe. The session carries a one-time `client_secret` so the iframe-side validation and confirmation calls can be authorized without your secret API key.

`@easylabs/node` is a server-side SDK — `createClient({ apiKey })` validates a secret API key, so the package itself must never be loaded in a browser bundle. Two of the methods on this resource — `validateEmbeddedCheckoutSession` and `confirmEmbeddedCheckoutSession` — still authenticate with the session's `client_secret` rather than the API key (the SDK suppresses the API-key header for those two requests), but you call them from your own server endpoints, which the iframe reaches via your own `fetch`. If you'd rather hit `POST /embedded-checkout/validate` and `POST /embedded-checkout/confirm` directly from the browser with the `client_secret`, that's also supported — just don't reach for the Node SDK to do it.

## Methods [#methods]

### `createEmbeddedCheckoutSession(data)` [#createembeddedcheckoutsessiondata]

`POST /embedded-checkout`. Returns `ApiResponse<EmbeddedCheckoutSessionData>`.

```ts
const { data: session } = await easy.createEmbeddedCheckoutSession({
  line_items: [{ price_id: "PR_...", quantity: 1 }],
  mode: "payment",                 // or "subscription"
  return_url: "https://app.example.com/checkout/return",
  success_url: "https://app.example.com/checkout/success",
  cancel_url: "https://app.example.com/checkout/cancel",
  customer_email: "ada@example.com",
  payment_methods: ["card"],       // include "crypto" to accept Solana Pay
  metadata: { cart_id: "cart_42" },
});

// Hand session.client_secret to the iframe; render session.url.
```

### `getEmbeddedCheckoutSession(sessionId)` [#getembeddedcheckoutsessionsessionid]

`GET /embedded-checkout/:id`. Returns `EmbeddedCheckoutSessionStatus` — `status` (`"open" | "complete" | "expired"`), `payment_status`, `amount_total`, `line_items`, `customer_email`, `metadata`, `created_at`, `completed_at`.

### `getCryptoPaymentStatus(sessionId)` [#getcryptopaymentstatussessionid]

`GET /embedded-checkout/:id/crypto-status`. Poll for the on-chain confirmation when `payment_methods` includes `"crypto"`.

### `validateEmbeddedCheckoutSession(body)&#x60; &#x2A;(server-side, client-secret authed)* [#validateembeddedcheckoutsessionbody-server-side-client-secret-authed]

`POST /embedded-checkout/validate`. Lives on the server-side client returned by `createClient`, but authenticates with the session's `client_secret` rather than the API key — the SDK suppresses the `x-easy-api-key` header for this single call. Rate-limited (\~30 req/min per session). Returns the resolved session config — branding, line items, allowed origins. Expose this through your own server endpoint that the iframe calls.

### `confirmEmbeddedCheckoutSession(body)&#x60; &#x2A;(server-side, client-secret authed)* [#confirmembeddedcheckoutsessionbody-server-side-client-secret-authed]

`POST /embedded-checkout/confirm`. Same auth model as `validateEmbeddedCheckoutSession`: server-side method, `client_secret`-authed, API-key header suppressed. Submits the tokenized payment source and finalizes the session.

### `getEmbeddedCheckoutConfig()` [#getembeddedcheckoutconfig]

`GET /embedded-checkout/config`. Server-only. Returns the company's allowed-origins config.

### `updateEmbeddedCheckoutConfig(body)` [#updateembeddedcheckoutconfigbody]

`PATCH /embedded-checkout/config`. Pass `{ allowed_origins: ["https://app.example.com", "https://*.example.com"] }`. An empty array disables embedding entirely.

## Object shape [#object-shape]

`EmbeddedCheckoutSessionData` (returned by create):

| Field            | Type                             | Notes                                               |
| ---------------- | -------------------------------- | --------------------------------------------------- |
| `id`             | `string`                         | Session ID.                                         |
| `client_secret`  | `string`                         | One-time secret for the browser. Do not log.        |
| `url`            | `string`                         | URL to embed in the iframe.                         |
| `amount_total`   | `number`                         | Smallest currency unit.                             |
| `currency`       | `string`                         |                                                     |
| `status`         | `string`                         | Initial status.                                     |
| `expires_at`     | `string`                         | ISO timestamp.                                      |
| `crypto_payment` | `CryptoPaymentInfo \| undefined` | Present when `payment_methods` includes `"crypto"`. |

`EmbeddedCheckoutConfig`: `id`, `company_id`, `allowed_origins: string[]`, `created_at`, `updated_at`.

## Examples [#examples]

### Create + render [#create--render]

```ts
// app/api/checkout/route.ts
export async function POST(req: Request) {
  const { priceId } = await req.json();
  const { data } = await easy.createEmbeddedCheckoutSession({
    line_items: [{ price_id: priceId, quantity: 1 }],
    mode: "payment",
    return_url: "https://app.example.com/checkout/return",
  });
  return Response.json({ clientSecret: data.client_secret, url: data.url });
}
```

### Authorize an embedding origin [#authorize-an-embedding-origin]

```ts
await easy.updateEmbeddedCheckoutConfig({
  allowed_origins: [
    "https://app.example.com",
    "https://*.example.com", // wildcard subdomains
  ],
});
```

### Poll a crypto session [#poll-a-crypto-session]

```ts
async function awaitCryptoConfirmation(sessionId: string, deadlineMs: number) {
  while (Date.now() < deadlineMs) {
    const { data } = await easy.getCryptoPaymentStatus(sessionId);
    if (data.status === "confirmed") return data;
    if (data.status === "failed" || data.status === "expired") throw new Error(data.status);
    await new Promise((r) => setTimeout(r, 3000));
  }
  throw new Error("timeout");
}
```


# Invoices (/docs/sdks/node/resources/invoices)



Invoices are itemized bills you send to a buyer with a due date — either to be paid online (`charge_automatically`) or via the hosted invoice page (`send_invoice`). The SDK covers the full lifecycle: create, list, send, charge, remind, void, and pull the data you'd need to render the PDF yourself.

## Methods [#methods]

```ts
easy.createInvoice(body);                  // POST   /invoices
easy.listInvoices(query?);                 // GET    /invoices
easy.getInvoice(invoiceId);                // GET    /invoices/:id
easy.updateInvoice(invoiceId, body);       // PATCH  /invoices/:id
easy.sendInvoice(invoiceId, body?);        // POST   /invoices/:id/send
easy.payInvoice(invoiceId, body?);         // POST   /invoices/:id/pay
easy.remindInvoice(invoiceId);             // POST   /invoices/:id/remind
easy.voidInvoice(invoiceId);               // POST   /invoices/:id/void
easy.getInvoicePdfData(invoiceId);         // GET    /invoices/:id/pdf
```

### Create [#create]

```ts
const invoice = await easy.createInvoice({
  to_email: "ada@example.com",
  to_company_name: "Analytical Engines Co.",
  collection_method: "send_invoice",
  currency: "USD",
  due_date: "2026-06-15",
  issue_date: "2026-05-15",
  items: [
    { description: "Consulting (May)", quantity: 20, unit_price: 25000 }, // $250/hr × 20
  ],
  tax_rate: 8.5,                       // percentage
  notes: "Net-30, thanks!",
  terms: "Pay by ACH or card.",
  attach_pdf: true,
});
```

### List with filters [#list-with-filters]

```ts
const overdue = await easy.listInvoices({
  status: "OVERDUE",
  collection_method: "send_invoice",
  due_date_to: new Date().toISOString(),
  limit: 100,
});
```

### Send [#send]

```ts
await easy.sendInvoice(invoice.data.id, {
  cc_recipients: ["billing@example.com"],
  attach_pdf: true,
});
```

### Charge an open invoice [#charge-an-open-invoice]

```ts
import { randomUUID } from "node:crypto";

await easy.payInvoice(invoice.data.id, {
  instrument_id: paymentInstrumentId, // omit to use the customer's default
  amount: 50000,                      // omit to charge full balance
  idempotency_key: randomUUID(),
});
```

### Remind, void, or void-and-write-off [#remind-void-or-void-and-write-off]

```ts
await easy.remindInvoice(invoiceId);    // sends reminder email
await easy.voidInvoice(invoiceId);      // marks VOID; cannot be undone
```

## Object shape [#object-shape]

`InvoiceData` (subset of the most-touched fields):

| Field                                                                                     | Type                                       | Notes                                                                                               |
| ----------------------------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `id` / `invoice_number`                                                                   | `string \| null`                           | Number assigned on finalization.                                                                    |
| `status`                                                                                  | `InvoiceStatus`                            | `DRAFT`, `OPEN`, `SENT`, `VIEWED`, `OVERDUE`, `PARTIALLY_PAID`, `PAID`, `UNPAID`, `VOID`, `VOIDED`. |
| `collection_method`                                                                       | `"charge_automatically" \| "send_invoice"` |                                                                                                     |
| `currency`                                                                                | `string`                                   |                                                                                                     |
| `to_email` / `to_company_name` / `to_contact_name` / `to_address`                         | various                                    | Recipient.                                                                                          |
| `subtotal_amount` / `tax_amount` / `discount_amount` / `shipping_amount` / `total_amount` | `number`                                   | Smallest currency unit.                                                                             |
| `amount_paid` / `amount_due`                                                              | `number`                                   | Running totals.                                                                                     |
| `due_date` / `issue_date` / `paid_at` / `voided_at` / `last_sent_at` / `last_viewed_at`   | `string \| null`                           | ISO timestamps.                                                                                     |
| `items`                                                                                   | `InvoiceItem[]`                            | Line items.                                                                                         |
| `is_recurring` / `recurrence_interval` / `recurrence_end_date`                            | various                                    | Recurring invoice config.                                                                           |
| `auto_reminders`                                                                          | `boolean`                                  | Enable scheduled reminders.                                                                         |
| `tax_ids` / `custom_fields` / `branding_overrides`                                        | various                                    |                                                                                                     |
| `pdf_storage_path`                                                                        | `string \| null`                           | Where the rendered PDF lives.                                                                       |

## Examples [#examples]

### Recurring monthly invoice [#recurring-monthly-invoice]

```ts
await easy.createInvoice({
  to_email: "ops@example.com",
  collection_method: "send_invoice",
  due_date: "2026-06-30",
  is_recurring: true,
  recurrence_interval: "MONTHLY",
  recurrence_end_date: "2027-05-31",
  recurrence_auto_send: true,
  items: [{ description: "Retainer", quantity: 1, unit_price: 500000 }],
});
```

### Sweep all overdue invoices nightly [#sweep-all-overdue-invoices-nightly]

```ts
const overdue = await easy.listInvoices({ status: "OVERDUE", limit: 100 });
for (const inv of overdue.data) {
  if (inv.collection_method === "send_invoice") {
    await easy.remindInvoice(inv.id);
  } else {
    await easy.payInvoice(inv.id, { idempotency_key: `retry:${inv.id}:${new Date().toISOString().slice(0, 10)}` });
  }
}
```

### Render the PDF yourself [#render-the-pdf-yourself]

`getInvoicePdfData` returns a normalized payload (currently typed as `Record<string, unknown>`) shaped for client-side PDF generation. Pipe it into your renderer of choice:

```ts
const { data } = await easy.getInvoicePdfData(invoiceId);
// hand `data` to your PDF template (e.g. react-pdf, puppeteer, weasyprint)
```


# Orders (/docs/sdks/node/resources/orders)



An order is the application-level record of a purchase: who bought what, for how much, against which payment instrument, and which transfer captured the funds. Orders are produced by `checkout`, embedded checkout, payment links, and subscription invoicing — there is no `createOrder` method.

## Methods [#methods]

### `getOrder(orderId)` [#getorderorderid]

`GET /orders/:id`.

### `getOrders(params?)` [#getordersparams]

`GET /orders`. Standard pagination.

### `updateOrderTags(orderId, tags)` [#updateordertagsorderid-tags]

`PATCH /orders/:id`. The only mutable field is `tags`. Pass the full tag bag you want stored — server replaces, it does not merge.

```ts
await easy.updateOrderTags(orderId, {
  fulfilment_state: "shipped",
  tracking_number: "1Z999AA10123456784",
});
```

To list orders for a single customer, use [`getCustomerOrders`](./customers#getcustomerorderscustomerid-params).

## Object shape [#object-shape]

`OrderData` includes:

| Field                                                 | Type                      | Notes                                                   |
| ----------------------------------------------------- | ------------------------- | ------------------------------------------------------- |
| `id` / `order_number`                                 | `string`                  | UUID + human-friendly number.                           |
| `subtotal_cents` / `tax_amount_cents` / `total_cents` | `number`                  | All in the smallest currency unit.                      |
| `currency`                                            | `string`                  | ISO 4217.                                               |
| `merchant_id` / `company_id`                          | `string`                  |                                                         |
| `source`                                              | `string`                  | `"checkout"`, `"payment_link"`, `"subscription"`, etc.  |
| `payment_instrument`                                  | `PaymentInstrumentData`   | Instrument used.                                        |
| `transfer`                                            | `TransferData \| null`    | The capture (null for declined / cancelled orders).     |
| `payment_link_id`                                     | `string \| null`          | Set when sourced from a payment link.                   |
| `purchase_items`                                      | `PurchaseItemData[]`      | Line items with embedded `price_data` + `product_data`. |
| `buyer_details`                                       | object                    | `email`, `phone`, name, billing address.                |
| `shipping_address` / `billing_address`                | `Address \| null`         |                                                         |
| `failure_code` / `failure_message`                    | `string \| null`          | Populated on declines.                                  |
| `tax_rate_id`                                         | `string \| null`          |                                                         |
| `metadata` / `tags`                                   | `Record<string, unknown>` |                                                         |

## Examples [#examples]

### Reconcile recent orders [#reconcile-recent-orders]

```ts
const orders = await easy.getOrders({ limit: 100 });
for (const o of orders.data) {
  if (!o.transfer || o.transfer.state !== "SUCCEEDED") continue;
  // post o.total_cents to your ledger keyed on o.order_number
}
```

### Attach fulfilment metadata when a webhook fires [#attach-fulfilment-metadata-when-a-webhook-fires]

```ts
import { EasyWebhooks } from "@easylabs/node";

// Inside your webhook handler:
const event = EasyWebhooks.constructEvent(rawBody, sigHeader, secret);
if (event.type === "checkout.session.completed") {
  const order = event.data as { id: string; order_number: string };
  await easy.updateOrderTags(order.id, {
    fulfilment_state: "queued",
    queued_at: new Date().toISOString(),
  });
}
```

### Surface a declined order to support [#surface-a-declined-order-to-support]

```ts
const { data: order } = await easy.getOrder(orderId);
if (order.failure_code) {
  console.warn(`Order ${order.order_number} failed: ${order.failure_message} (${order.failure_code})`);
}
```


# Payment Instruments (/docs/sdks/node/resources/payment-instruments)



A payment instrument is a tokenized card or bank account attached to a customer (`identityId`). Card and bank PANs never touch your servers — collect them through the Easy frontend SDK or Basis Theory and pass the resulting `tokenId` here.

## Methods [#methods]

### `createPaymentInstrument(data)` [#createpaymentinstrumentdata]

`POST /payment`. Validates that `tokenId` is present, then sends one of two discriminated bodies:

```ts
// Card
await easy.createPaymentInstrument({
  type: "PAYMENT_CARD",
  identityId: customer.id,
  tokenId: tokenFromFrontend,
  name: "Ada Lovelace",
  address: {
    line1: "1 Pioneer Way",
    city: "Menlo Park",
    region: "CA",
    postal_code: "94025",
    country: "USA",
  },
});

// Bank account
await easy.createPaymentInstrument({
  type: "BANK_ACCOUNT",
  identityId: customer.id,
  tokenId: tokenFromFrontend,
  name: "Ada Lovelace",
  accountType: "PERSONAL_CHECKING",
  attempt_bank_account_validation_check: true,
});
```

The SDK throws synchronously if `tokenId` is missing or `type` is unrecognized.

### `updatePaymentInstrument(paymentInstrumentId, data)` [#updatepaymentinstrumentpaymentinstrumentid-data]

`PATCH /payment/:id`. Accepts an `UpdatePaymentInstrument` shape:

```ts
await easy.updatePaymentInstrument(piId, {
  enabled: false,
  account_updater_enabled: true,
  network_token_enabled: true,
  address: { line1: "2 Pioneer Way", city: "Menlo Park", region: "CA", postal_code: "94025", country: "USA", line2: null },
  tags: { source: "manual_review" },
});
```

### `getCustomerPaymentInstruments(customerId)` [#getcustomerpaymentinstrumentscustomerid]

Listed under [Customers](./customers) — there is no top-level "list all instruments" endpoint; always scope by customer.

## Object shape [#object-shape]

Two response shapes show up depending on which endpoint you hit:

* `FinixPaymentInstrumentData` — returned by `createPaymentInstrument`. Mirrors the underlying processor record (snake\_case identifiers, `_links`, `instrument_type`, etc.).
* `PaymentInstrumentData` — returned by listing endpoints and `updatePaymentInstrument`. The application-level shape: `id`, `identity_id`, `type` (`"PAYMENT_CARD" | "BANK_ACCOUNT"`), brand / `last_four` / `expiration_*` for cards, `bank_code` / `masked_account_number` / `account_type` / `bank_account_validation_check` for bank accounts, plus `enabled`, `account_updater_enabled`, `network_token_enabled`, `address`, `tags`.

## Examples [#examples]

### Disable an instrument without deleting it [#disable-an-instrument-without-deleting-it]

```ts
await easy.updatePaymentInstrument(instrumentId, { enabled: false });
```

Disabled instruments stay attached to the customer for audit but cannot be charged.

### Re-trigger bank-account validation [#re-trigger-bank-account-validation]

```ts
await easy.updatePaymentInstrument(bankAccountId, {
  attempt_bank_account_validation_check: true,
});
```

### Choose the default for a customer [#choose-the-default-for-a-customer]

The default-instrument decision is currently part of charge calls (`payInvoice({ instrument_id })`, `createSubscription({ instrument_id })`, etc.) rather than a dedicated method on the instrument itself. {/* TODO: confirm whether a dedicated "set default" endpoint exists. */}


# Payment Links (/docs/sdks/node/resources/payment-links)



Payment links are hosted, no-code checkout pages — share a URL and Easy Labs handles collection, instrument capture, branding, and receipts. Use them for invoicing-as-a-link, donation pages, single-product sales, or multi-use storefronts.

## Methods [#methods]

### `createPaymentLink(payload)` [#createpaymentlinkpayload]

`POST /payment-link`. Returns `ApiResponse<{ id: string }>` — fetch the full link with `getPaymentLink` if you need the URL.

```ts
// `products[].id` references a Product you've already created (see
// /resources/products-pricing). Each entry then lists one or more
// `product_prices` by Price ID, with the quantity to bill.
const { data } = await easy.createPaymentLink({
  nickname: "Conference ticket",
  amount_type: "FIXED",
  products: [
    {
      id: "PROD_vip_pass",
      product_prices: [{ id: "PR_vip_pass_25000", quantity: 1 }],
    },
  ],
  allowed_payment_methods: ["PAYMENT_CARD"],
  payment_limit: 100,
  collect_buyer_details: "more",
});
const link = await easy.getPaymentLink(data.id);
console.log(link.data.link_url);
```

### `getPaymentLinks(params?)` [#getpaymentlinksparams]

`GET /payment-link/`. Standard pagination.

### `getPaymentLink(paymentLinkId)` [#getpaymentlinkpaymentlinkid]

`GET /payment-link/:id`.

### `updatePaymentLink(paymentLinkId, body)` [#updatepaymentlinkpaymentlinkid-body]

`PATCH /payment-link/:id`. Accepts `UpdatePaymentLinkPayload` (all `CreatePaymentLinkPayload` fields are optional).

```ts
await easy.updatePaymentLink(linkId, { branding_overrides: { brand_color: "#0F172A" } });
```

### `deletePaymentLink(paymentLinkId)` [#deletepaymentlinkpaymentlinkid]

`DELETE /payment-link/:id`.

### `getPaymentLinkPayments(paymentLinkId, params?)` [#getpaymentlinkpaymentspaymentlinkid-params]

`GET /payment-link/:id/payments`. Returns the orders that closed against the link.

## Object shape [#object-shape]

`PaymentLinkData` carries the rendered hosted-page configuration plus runtime state: `id`, `link_url`, `link_expires_at`, `state` (`"DRAFT" | "ACTIVE" | "INACTIVE" | "EXPIRED"`), `payment_count`, `payment_limit`, `payment_frequency` (`"ONE_TIME" | "RECURRING"`), `is_multiple_use`, `items[]` (with `price_details`), `amount_details` (`amount_type`, totals, optional min/max for variable links), `branding`, `branding_overrides`, `additional_details` (`collect_*`, return URLs, expiration), `buyer_details` once the buyer has filled them in, and the standard `tags` bag.

## Examples [#examples]

### Variable-amount donation link [#variable-amount-donation-link]

```ts
// For a VARIABLE-amount link, omit the product `id` and pass an empty
// `product_prices` array — the buyer chooses the amount within
// `min_amount` / `max_amount`.
await easy.createPaymentLink({
  nickname: "Donations",
  amount_type: "VARIABLE",
  products: [{ product_prices: [] }],
  min_amount: 500,
  max_amount: 100000,
  payment_limit: null, // unlimited
});
```

### Single-use invoice replacement [#single-use-invoice-replacement]

```ts
// Pre-create a Product + Price for "Invoice #2024-117" via createProduct /
// createPrice, then reference the resulting IDs here.
const link = await easy.createPaymentLink({
  amount_type: "FIXED",
  products: [
    {
      id: "PROD_invoice_2024_117",
      product_prices: [{ id: "PR_invoice_2024_117", quantity: 1 }],
    },
  ],
  payment_limit: 1,
  collect_buyer_details: "more",
});
```

### Reconcile payments for a link [#reconcile-payments-for-a-link]

```ts
const orders = await easy.getPaymentLinkPayments(linkId, { limit: 100 });
for (const o of orders.data) {
  console.log(o.order_number, o.total_cents, o.identity?.entity.email);
}
```


# Products & Pricing (/docs/sdks/node/resources/products-pricing)



Products are the catalog rows ("Pro plan", "Setup fee"); prices attach a currency, amount, and (for recurring prices) an interval to a product. Subscriptions and checkout line items reference *prices*, not products — a single product typically has several active prices (monthly vs. yearly, USD vs. EUR, etc.).

## Methods [#methods]

### Products [#products]

```ts
easy.createProduct(body);                 // POST /products
easy.getProduct(productId);               // GET /products/:id
easy.getProducts(params?);                // GET /products
easy.updateProduct(productId, body);      // PATCH /products/:id
easy.archiveProduct(productId);           // PATCH /products/:id/archive
easy.getProductWithPrices(productId);     // GET /products/:id/prices
easy.getProductWithPrice(productId, priceId); // GET /products/:id/prices/:priceId
```

`createProduct` payload:

```ts
await easy.createProduct({
  name: "Pro plan",
  active: true,
  description: "Everything in Free, plus team seats.",
  image_url: "https://cdn.example.com/pro.png",
  statement_descriptor: "EXAMPLE PRO",
  unit_label: "seat",
  metadata: { tier: "pro" },
  default_price_id: undefined, // set after you create a price
});
```

`updateProduct` accepts `Partial<CreateProduct>` — including switching `default_price_id` once you have one. `archiveProduct` flips it to inactive without deleting historical orders.

### Prices [#prices]

```ts
easy.createPrice(body);                   // POST /product-prices
easy.getPrice(priceId);                   // GET /product-prices/:id
easy.getPrices(params?);                  // GET /product-prices
easy.updatePrice(priceId, body);          // PATCH /product-prices/:id
easy.archivePrice(priceId);               // PATCH /product-prices/:id/archive
```

`CreatePrice` is a discriminated union on `recurring`:

```ts
// Recurring
await easy.createPrice({
  product_id: "PD_...",
  active: true,
  recurring: true,
  currency: "USD",
  unit_amount: 2900,                // $29.00
  interval: "month",
  interval_count: 1,
  tax_behavior: "exclusive",
  pricing_model: "per_unit",
  trial_period_days: 14,
});

// One-time
await easy.createPrice({
  product_id: "PD_...",
  active: true,
  recurring: false,
  currency: "USD",
  unit_amount: 4999,
  tax_behavior: "exclusive",
});
```

`updatePrice` accepts only the fields the API treats as editable in flight: `active`, `metadata`, `description`. Everything else (amount, currency, interval) is immutable — create a new price and switch the product's `default_price_id`.

## Object shape [#object-shape]

### `ProductData` [#productdata]

`id`, `name`, `description`, `active`, `image_url`, `statement_descriptor`, `unit_label`, `default_price_id`, `metadata`, `created_at`, `updated_at`, plus `company_id` (stripped on the nested `getProductWithPrices` response via `PickExcept`).

### `PriceData` [#pricedata]

| Field               | Type                                                                                                   | Notes                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
| `id`                | `string`                                                                                               |                                                  |
| `product_id`        | `string`                                                                                               |                                                  |
| `currency`          | `CurrencyCode`                                                                                         | ISO 4217.                                        |
| `unit_amount`       | `number`                                                                                               | Smallest currency unit.                          |
| `recurring`         | `boolean`                                                                                              |                                                  |
| `interval`          | `"day" \| "week" \| "month" \| "year" \| null`                                                         | Null on one-time prices.                         |
| `interval_count`    | `number \| null`                                                                                       | E.g. `3` with `interval: "month"` for quarterly. |
| `pricing_model`     | `"per_unit" \| "tiered_volume" \| "tiered_graduated" \| "package" \| "metered" \| "flat_rate" \| null` |                                                  |
| `trial_period_days` | `number \| null`                                                                                       |                                                  |
| `tax_behavior`      | `"exclusive" \| "inclusive"`                                                                           |                                                  |
| `tax_rate_id`       | `string \| null`                                                                                       |                                                  |
| `description`       | `string \| null`                                                                                       |                                                  |
| `metadata`          | `Record<string, unknown>`                                                                              |                                                  |
| `active`            | `boolean`                                                                                              |                                                  |

## Examples [#examples]

### Spin up a new monthly plan [#spin-up-a-new-monthly-plan]

```ts
const product = await easy.createProduct({ name: "Team plan", active: true });
const price = await easy.createPrice({
  product_id: product.data.id,
  active: true,
  recurring: true,
  currency: "USD",
  unit_amount: 4900,
  interval: "month",
  interval_count: 1,
  tax_behavior: "exclusive",
});
await easy.updateProduct(product.data.id, { default_price_id: price.data.id });
```

### Migrate to a new price (deprecate the old one) [#migrate-to-a-new-price-deprecate-the-old-one]

```ts
const newPrice = await easy.createPrice({ /* … */ });
await easy.updateProduct(productId, { default_price_id: newPrice.data.id });
await easy.archivePrice(oldPriceId);
```

### Read product + every price in one round-trip [#read-product--every-price-in-one-round-trip]

```ts
const { data } = await easy.getProductWithPrices(productId);
for (const p of data.prices) {
  console.log(p.id, p.unit_amount, p.interval);
}
```


# Promotion Codes (/docs/sdks/node/resources/promotion-codes)



Promotion codes are the buyer-facing strings ("`SPRING25`") that resolve to a [coupon](./coupons). One coupon can have multiple codes (e.g. campaign- or partner-specific), each with its own redemption limits, expiry, and eligibility rules.

## Methods [#methods]

```ts
easy.createPromotionCode(body);                // POST   /promotion-codes
easy.listPromotionCodes(params?);              // GET    /promotion-codes
easy.getPromotionCode(promotionCodeId);        // GET    /promotion-codes/:id
easy.updatePromotionCode(promotionCodeId, body); // PATCH  /promotion-codes/:id
easy.deletePromotionCode(promotionCodeId);     // DELETE /promotion-codes/:id
easy.validatePromotionCode(body);              // POST   /promotion-codes/validate
```

```ts
const promo = await easy.createPromotionCode({
  coupon_id: coupon.data.id,
  code: "SPRING25",
  active: true,
  max_redemptions: 500,
  valid_until: "2026-06-30T23:59:59Z",
  first_time_only: true,
  minimum_amount: 5000,        // require $50 minimum cart
  metadata: { campaign: "spring_2026" },
});
```

`UpdatePromotionCode` is narrow: only `active` and `metadata` are mutable. To change the coupon, code, or redemption rules, create a new promotion code.

## Validation [#validation]

`validatePromotionCode` previews whether a code would apply for a given customer / amount before you let them apply it. Returns `{ valid, promotion_code?, coupon?, discount_preview?, reason? }`:

```ts
const { data } = await easy.validatePromotionCode({
  code: userInput,
  identity_id: customer.id,    // optional
  amount: cartTotalCents,      // optional
});

if (!data.valid) {
  throw new Error(data.reason ?? "Invalid promo code");
}
console.log(data.discount_preview); // { amount_off } or { percent_off }
```

The corresponding redemption happens when you call `applySubscriptionDiscount(subId, { promotion_code: "SPRING25" })`.

## Object shape [#object-shape]

`PromotionCodeData`:

| Field             | Type                      | Notes                                                        |
| ----------------- | ------------------------- | ------------------------------------------------------------ |
| `id`              | `string`                  |                                                              |
| `coupon_id`       | `string`                  | The coupon this code resolves to.                            |
| `code`            | `string`                  | The buyer-facing string.                                     |
| `active`          | `boolean`                 |                                                              |
| `max_redemptions` | `number \| null`          | Per-code cap.                                                |
| `times_redeemed`  | `number`                  |                                                              |
| `valid_until`     | `string \| null`          | ISO timestamp.                                               |
| `first_time_only` | `boolean`                 | If true, only redeemable on a customer's first subscription. |
| `minimum_amount`  | `number \| null`          | Smallest currency unit.                                      |
| `metadata`        | `Record<string, unknown>` |                                                              |

## Examples [#examples]

### Validate-then-apply at checkout [#validate-then-apply-at-checkout]

```ts
const validation = await easy.validatePromotionCode({
  code: input,
  identity_id: customer.id,
  amount: cart.totalCents,
});
if (!validation.data.valid) return reply.code(400).send({ error: validation.data.reason });
await easy.applySubscriptionDiscount(subId, { promotion_code: input });
```

### Disable a code mid-campaign [#disable-a-code-mid-campaign]

```ts
await easy.updatePromotionCode(promoId, { active: false });
```

### Per-partner unique codes [#per-partner-unique-codes]

```ts
const codes = ["PARTNERA", "PARTNERB", "PARTNERC"];
for (const code of codes) {
  await easy.createPromotionCode({
    coupon_id: couponId,
    code,
    metadata: { partner: code.toLowerCase() },
  });
}
```


# Refunds (/docs/sdks/node/resources/refunds)



A refund is a reversal of an existing transfer. The Easy API models it as a child transfer (`type: "REVERSAL"`, `parent_transfer` pointing at the original) created against the original transfer's `/reversals` collection.

## Methods [#methods]

### `createRefund(transferId, body)` [#createrefundtransferid-body]

`POST /transfer/:id/reversals`. Returns `ApiResponse<TransferData>` — the reversal transfer itself.

```ts
// Full refund
await easy.createRefund(transferId, { refund_amount: originalAmount });

// Partial refund
await easy.createRefund(transferId, { refund_amount: 500 });

// With tags for reconciliation
await easy.createRefund(transferId, {
  refund_amount: 500,
  tags: { reason: "shipping_delay", approved_by: "agent_42" },
});
```

`refund_amount` is in the smallest currency unit (cents for USD). The API enforces the partial-refund accumulation limit — issuing more than the original captured amount returns 422.

There is no dedicated "list refunds" method. List transfers and filter by `type === "REVERSAL"` and `parent_transfer === originalTransferId`, or follow the `_links.reversals.href` on the parent transfer.

## Object shape [#object-shape]

The returned `TransferData` carries:

* `type: "REVERSAL"` — distinguishes it from forward charges.
* `parent_transfer: string` — the ID of the transfer being reversed.
* `parent_transfer_trace_id: string | null` — convenience trace.
* `amount` — the refunded amount in smallest currency units.
* `state` — `PENDING` initially, transitioning to `SUCCEEDED` when the funds clear back.
* `tags` — anything you passed in `body.tags`.

Refer to [Transfers](./transfers) for the rest of the field list.

## Examples [#examples]

### Refund-on-cancel [#refund-on-cancel]

```ts
async function cancelAndRefund(orderId: string, reason: string) {
  const { data: order } = await easy.getOrder(orderId);
  if (!order.transfer) throw new Error("Order has no captured transfer.");
  return easy.createRefund(order.transfer.id, {
    refund_amount: order.transfer.amount,
    tags: { reason, source: "support_console" },
  });
}
```

### Partial refund driven by a webhook [#partial-refund-driven-by-a-webhook]

When you receive a `dispute.created` event you may want to refund preemptively rather than fight:

```ts
async function refundDisputedTransfer(transferId: string) {
  const { data: t } = await easy.getTransfer(transferId);
  return easy.createRefund(transferId, {
    refund_amount: t.amount,
    tags: { reason: "dispute_received" },
  });
}
```

### Reconcile the reversal back to your ledger [#reconcile-the-reversal-back-to-your-ledger]

```ts
const reversal = await easy.createRefund(transferId, { refund_amount: 250 });
console.log({
  original: reversal.data.parent_transfer,
  reversal: reversal.data.id,
  state: reversal.data.state,
});
```


# Settlements (/docs/sdks/node/resources/settlements)



A settlement bundles a batch of transfers into a single payout to your bank. The SDK exposes read-only listing plus a manual `closeSettlement` action used by platforms that drive their own batch boundaries.

## Methods [#methods]

```ts
easy.getSettlements(params?);          // GET   /settlements
easy.getSettlement(settlementId);      // GET   /settlements/:id
easy.closeSettlement(settlementId);    // PATCH /settlements/:id
```

```ts
const recent = await easy.getSettlements({ limit: 25 });
const { data: settlement } = await easy.getSettlement(recent.data[0].id);

// Manually close an open settlement for a same-day payout:
await easy.closeSettlement(settlement.id);
```

## Object shape [#object-shape]

`SettlementData` mirrors the underlying processor record (snake\_case fields, `_links`, batch-level totals and counts). Refer to the API reference for the canonical schema; the SDK re-exports the type as `SettlementData` from `@easylabs/node`.

## Examples [#examples]

### Reconcile a settlement against your ledger [#reconcile-a-settlement-against-your-ledger]

```ts
const { data } = await easy.getSettlement(settlementId);
// Compare data.total_amount / data.fee_amount / data.transfer_count to your records.
```

### Sweep recently closed settlements [#sweep-recently-closed-settlements]

```ts
const settlements = await easy.getSettlements({ limit: 100 });
for (const s of settlements.data) {
  // post each to your accounting system using s.id as the idempotency key
}
```


# Subscriptions (/docs/sdks/node/resources/subscriptions)



A subscription is a recurring billing relationship between a customer and one or more prices. The SDK exposes the full lifecycle — create, update items, pause/resume, apply discounts, report metered usage, preview proration, cancel — plus one-time charges that ride along on the next invoice.

## Methods [#methods]

### Lifecycle [#lifecycle]

```ts
easy.createSubscription(body);                       // POST /subscriptions
easy.getSubscription(id);                            // GET /subscriptions/:id
easy.getSubscriptions(params?);                      // GET /subscriptions
easy.updateSubscription(id, body);                   // PATCH /subscriptions/:id
easy.cancelSubscription(id, { at_period_end? });     // DELETE /subscriptions/:id
easy.pauseSubscription(id, { behavior, resumes_at? }); // POST /subscriptions/:id/pause
easy.resumeSubscription(id);                         // POST /subscriptions/:id/resume
easy.getSubscriptionProrationPreview(id, params?);   // GET /subscriptions/:id/proration-preview
```

```ts
const { data: sub } = await easy.createSubscription({
  identity_id: customer.id,
  items: [{ price_id: "PR_monthly", quantity: 1 }],
  instrument_id: paymentInstrumentId,
  proration_behavior: "create_prorations",
  trial_period_days: 14,
  metadata: { plan: "pro_monthly" },
});

// Schedule cancellation at period end:
await easy.cancelSubscription(sub.id, { at_period_end: true });

// Pause until a date:
await easy.pauseSubscription(sub.id, {
  behavior: "mark_uncollectible",
  resumes_at: "2026-08-01T00:00:00Z",
});

await easy.resumeSubscription(sub.id);
```

`pauseSubscription`'s `behavior` is `"void" | "keep_as_draft" | "mark_uncollectible"` — controls how invoices generated during the pause are handled.

### Items [#items]

```ts
easy.addSubscriptionItem(subId, { price_id, quantity? });
easy.updateSubscriptionItem(subId, itemId, { quantity });
easy.removeSubscriptionItem(subId, itemId);
```

### Discounts [#discounts]

```ts
easy.applySubscriptionDiscount(subId, body);      // POST /subscriptions/:id/discounts
easy.listSubscriptionDiscounts(subId);            // GET  /subscriptions/:id/discounts
easy.removeSubscriptionDiscount(subId, discountId); // DELETE
```

`body` is exactly one of:

```ts
{ coupon_id: string; subscription_item_id?: string }
| { promotion_code: string; subscription_item_id?: string }
```

### One-time charges [#one-time-charges]

```ts
await easy.createOneTimeCharge(subId, {
  price_id: "PR_setup_fee",
  quantity: 1,
  description: "Implementation fee",
  due_date: "2026-06-01",
});
```

The charge attaches to the subscription's next invoice without changing recurring items.

### Metered usage [#metered-usage]

```ts
await easy.reportSubscriptionUsage(subId, {
  subscription_item_id: itemId,
  quantity: 42,
  action: "increment",                  // or "set"
  timestamp: new Date().toISOString(),
  idempotency_key: deliveryEventId,
});

await easy.getSubscriptionUsageSummary(subId, {
  subscription_item_id: itemId,
  from: "2026-04-01",
  to: "2026-04-30",
});

await easy.getSubscriptionUsageReconciliation(subId, {
  subscription_item_id: itemId,
  period_start: "2026-04-01",
  period_end: "2026-04-30",
});
```

### Proration preview [#proration-preview]

Run a dry-run before applying item changes:

```ts
const preview = await easy.getSubscriptionProrationPreview(subId, {
  items: [{ price_id: "PR_higher_tier", quantity: 1 }],
  remove_items: [oldItemId],
  proration_date: new Date().toISOString(),
});
```

## Object shape [#object-shape]

`SubscriptionData`:

| Field                                                             | Type                                | Notes                                                                                                 |
| ----------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `id`                                                              | `string`                            |                                                                                                       |
| `identity_id` / `instrument_id`                                   | `string \| string \| null`          |                                                                                                       |
| `status`                                                          | `SubscriptionStatus`                | `TRIALING`, `ACTIVE`, `PAST_DUE`, `CANCELED`, `UNPAID`, `PAUSED`, `INCOMPLETE`, `INCOMPLETE_EXPIRED`. |
| `items`                                                           | `SubscriptionItem[]`                | Each with `price_id`, optional `price`, `quantity`, `metadata`.                                       |
| `current_period_start` / `current_period_end`                     | `string \| null`                    | ISO timestamps.                                                                                       |
| `trial_start` / `trial_end`                                       | `string \| null`                    |                                                                                                       |
| `billing_cycle_anchor`                                            | `string \| null`                    |                                                                                                       |
| `cancel_at` / `cancel_at_period_end` / `canceled_at` / `ended_at` | various                             | Cancellation state.                                                                                   |
| `pause_collection`                                                | `{ behavior, resumes_at } \| null`  |                                                                                                       |
| `latest_invoice_id`                                               | `string \| null`                    |                                                                                                       |
| `proration_behavior`                                              | `ProrationBehavior \| null`         |                                                                                                       |
| `credit_balance`                                                  | `number`                            |                                                                                                       |
| `pending_update`                                                  | `SubscriptionPendingUpdate \| null` |                                                                                                       |

## Examples [#examples]

### Upgrade with proration preview [#upgrade-with-proration-preview]

```ts
const previewed = await easy.getSubscriptionProrationPreview(subId, {
  items: [{ price_id: "PR_pro_yearly", quantity: 1 }],
  remove_items: [currentMonthlyItemId],
});
// Show previewed.data to the user, then commit:
await easy.updateSubscription(subId, {
  items: [{ price_id: "PR_pro_yearly", quantity: 1 }],
  remove_items: [currentMonthlyItemId],
  proration_behavior: "create_prorations",
});
```

### Apply a 3-month coupon [#apply-a-3-month-coupon]

```ts
const coupon = await easy.createCoupon({
  duration: "repeating",
  duration_in_months: 3,
  percent_off: 25,
  name: "Q2 promo",
});
await easy.applySubscriptionDiscount(subId, { coupon_id: coupon.data.id });
```

### Idempotent metered usage from a webhook [#idempotent-metered-usage-from-a-webhook]

```ts
await easy.reportSubscriptionUsage(subId, {
  subscription_item_id: itemId,
  quantity: 1,
  action: "increment",
  idempotency_key: webhookDeliveryId, // repeat-safe
});
```


# Transfers (/docs/sdks/node/resources/transfers)



A transfer is the money-movement record produced by a charge. Most transfers are created indirectly (by `checkout`, `payInvoice`, subscription billing, or `captureAuthorization`); this resource lets you create raw transfers, list and read them, update tags, and reverse them via [refunds](./refunds).

## Methods [#methods]

### `createTransfer(data)` [#createtransferdata]

`POST /transfer`.

```ts
const { data: transfer } = await easy.createTransfer({
  amount: 4999,           // smallest currency unit (cents for USD)
  currency: "USD",
  source: instrumentId,   // payment-instrument ID to debit
  tags: { internal_order_id: "ord_42" },
});
```

### `updateTransfer(transferId, data)` [#updatetransfertransferid-data]

`PATCH /transfer/:id`. The body is a free-form `Record<string, unknown>` — currently used to attach or replace `tags`.

```ts
await easy.updateTransfer(transfer.id, { tags: { fulfilment: "shipped" } });
```

### `getTransfer(transferId)` [#gettransfertransferid]

`GET /transfer/:id`.

### `getTransfers(params?)` [#gettransfersparams]

`GET /transfer`. Standard pagination.

### `createRefund(transferId, body)` [#createrefundtransferid-body]

See [refunds](./refunds) — under the hood this issues a `POST /transfer/:id/reversals` and the response is itself a `TransferData` with `type: "REVERSAL"`.

## Object shape [#object-shape]

`TransferData` is the underlying processor record. The fields you'll touch most:

| Field                              | Type                     | Notes                                                          |
| ---------------------------------- | ------------------------ | -------------------------------------------------------------- |
| `id`                               | `string`                 | Transfer ID.                                                   |
| `amount` / `amount_requested`      | `number`                 | In smallest currency units.                                    |
| `currency`                         | `string`                 | ISO 4217.                                                      |
| `source` / `destination`           | `string` \| `null`       | Payment-instrument IDs.                                        |
| `state`                            | `TransferState`          | `PENDING`, `SUCCEEDED`, `FAILED`, `CANCELED`, `DISPUTED`, etc. |
| `type`                             | `TransferType`           | `DEBIT`, `CREDIT`, `REVERSAL`, `FEE`, `DISPUTE`.               |
| `subtype`                          | `TransferSubtype`        | E.g. `API`, `PUSH`, `PLATFORM`.                                |
| `failure_code` / `failure_message` | `string` \| `null`       | Populated on `FAILED`.                                         |
| `fee` / `supplemental_fee`         | `number`                 | Processor + platform fees.                                     |
| `parent_transfer`                  | `string` \| `null`       | Set on reversals to point at the original.                     |
| `tags`                             | `Record<string, string>` | Application metadata.                                          |
| `_links`                           | object                   | HATEOAS links — `reversals`, `disputes`, `fees`, etc.          |

## Examples [#examples]

### Find every refund issued against a transfer [#find-every-refund-issued-against-a-transfer]

```ts
const refunds = (await easy.getTransfers({ limit: 100 })).data.filter(
  (t) => t.type === "REVERSAL" && t.parent_transfer === originalId,
);
```

### Tag a charge with your internal order number [#tag-a-charge-with-your-internal-order-number]

```ts
await easy.updateTransfer(transferId, {
  tags: { internal_order_id: "ord_42", channel: "web" },
});
```

### Read failure details [#read-failure-details]

```ts
const { data: t } = await easy.getTransfer(transferId);
if (t.state === "FAILED") {
  console.error(t.failure_code, t.failure_message);
}
```


# Treasury (/docs/sdks/node/resources/treasury)



Treasury is Easy Labs' send / withdraw / move-money toolkit, sitting alongside the standard payment flows. It handles outbound payouts to recipients (ACH, wire, RTP, same-day ACH), inter-account transfers, deposits via wire instructions or bank pulls, recurring payouts, security rules, multi-step approvals, and 1099 / W-9 collection.

The SDK groups Treasury into eleven sub-areas. Methods all live on the same client — `easy.treasurySend(...)`, `easy.listTreasuryRecipients(...)`, etc. — but most response payloads are currently typed loosely (`{ id: string; [key: string]: unknown }`) pending schema lock-down.

## Methods [#methods]

### Send [#send]

```ts
easy.treasurySend(body);              // POST /treasury/send
easy.confirmTreasurySend(body);       // POST /treasury/send/confirm
easy.cancelTreasurySend(body);        // POST /treasury/send/cancel
```

```ts
const tx = await easy.treasurySend({
  recipient_id: recipient.id,
  amount: 250000,                       // smallest currency unit
  source_account_id: bankAccount.id,
  method: "ach",                        // "wire" | "ach" | "same_day_ach" | "rtp"
  memo: "May retainer",
});

await easy.confirmTreasurySend({
  transaction_id: tx.data.id,
  security_code: "123456",              // when a security rule requires it
});
```

### Internal transfer (between owned accounts) [#internal-transfer-between-owned-accounts]

```ts
easy.treasuryTransfer(body);          // POST /treasury/transfer
easy.confirmTreasuryTransfer(body);   // POST /treasury/transfer/confirm
```

### Deposit [#deposit]

```ts
easy.getTreasuryWireInstructions();   // GET  /treasury/deposit/wire-instructions
easy.treasuryDepositBankPull(body);   // POST /treasury/deposit/bank-pull
```

### Withdraw [#withdraw]

```ts
easy.treasuryWithdraw(body);          // POST /treasury/withdraw
easy.confirmTreasuryWithdraw(body);   // POST /treasury/withdraw/confirm
```

### Transactions [#transactions]

```ts
easy.listTreasuryTransactions(params?);          // GET   /treasury/transactions
easy.getTreasuryTransaction(id);                 // GET   /treasury/transactions/:id
easy.updateTreasuryTransaction(id, body);        // PATCH /treasury/transactions/:id
easy.getTreasuryTransactionSettlement(id);       // GET   /treasury/transactions/:id/settlement
easy.exportTreasuryTransactions(params?);        // GET   /treasury/transactions/export
```

### Dashboard [#dashboard]

```ts
easy.getTreasuryDashboardSummary();   // GET /treasury/dashboard/summary
```

### Recipients [#recipients]

```ts
easy.listTreasuryRecipients(params?);
easy.createTreasuryRecipient(body);
easy.getTreasuryRecipient(id);
easy.updateTreasuryRecipient(id, body);
easy.deleteTreasuryRecipient(id);
easy.addTreasuryRecipientPaymentMethod(id, body);
easy.inviteTreasuryRecipient(id);
easy.setTreasuryRecipientAutoPay(id, body);
easy.requestTreasuryRecipientW9(id);
easy.getTreasuryRecipientTaxInfo(id);
easy.setTreasuryRecipientTaxInfo(id, body);
easy.listTreasuryRecipientInvitations();
easy.acceptTreasuryRecipientInvite(body);
easy.importTreasuryRecipients(body?);
easy.getTreasuryRecipientTaxReport();
easy.getTreasuryRecipientPlaidLinkToken(body);
easy.exchangeTreasuryRecipientPlaidToken(body);
```

```ts
const recipient = await easy.createTreasuryRecipient({
  name: "Ada Lovelace",
  email: "ada@example.com",
  type: "person",
  payment_methods: [
    { method_type: "ach", account_type: "checking", routing_number: "021000021", account_number: "1234567890" },
  ],
  metadata: { internal_id: "vendor_42" },
});

await easy.setTreasuryRecipientAutoPay(recipient.data.id, {
  amount: 500000,
  frequency: "monthly",
  start_date: "2026-06-01",
  source_account_id: bankAccountId,
  method: "ach",
  memo: "Monthly retainer",
});
```

### Bank accounts [#bank-accounts]

```ts
easy.listTreasuryBankAccounts();
easy.getTreasuryBankAccountLinkToken();
easy.linkTreasuryBankAccount(body);
easy.deleteTreasuryBankAccount(id);
```

### Recurring payments [#recurring-payments]

```ts
easy.listTreasuryRecurringPayments(params?);
easy.createTreasuryRecurringPayment(body);
easy.getTreasuryRecurringPayment(id);
easy.updateTreasuryRecurringPayment(id, body);
easy.deleteTreasuryRecurringPayment(id);
```

### Auto-transfer rules [#auto-transfer-rules]

```ts
easy.listTreasuryAutoTransferRules();
easy.createTreasuryAutoTransferRule(body);
easy.updateTreasuryAutoTransferRule(id, body);
easy.deleteTreasuryAutoTransferRule(id);
```

### Security rules + approvals [#security-rules--approvals]

```ts
easy.listTreasurySecurityRules();
easy.createTreasurySecurityRule(body);
easy.updateTreasurySecurityRule(id, body);
easy.deleteTreasurySecurityRule(id);

easy.createTreasuryApprovalRequest(body);
easy.resolveTreasuryApprovalRequest(id, { action: "approve" /* or "deny" */, reason });
```

### Payout links + categories [#payout-links--categories]

```ts
easy.listTreasuryPayoutLinks(params?);
easy.generateTreasuryPayoutLink(body);
easy.getTreasuryPayoutLink(token);
easy.submitTreasuryPayoutLink(token, body);

easy.listTreasuryCategories();
easy.createTreasuryCategory({ name, color? });
easy.deleteTreasuryCategory(id);
easy.getTreasuryCategoryUsage(id);
```

## Object shape [#object-shape]

The Treasury request types are tightly typed (see `CreateTreasuryRecipientParams`, `TreasurySendParams`, etc.); response payloads are intentionally permissive in this SDK release:

```ts
type TreasuryTransactionData = { id: string; [key: string]: unknown };
type TreasuryRecipientData   = { id: string; name: string; email: string; type: "person" | "business"; [key: string]: unknown };
type TreasuryBankAccountData = { id: string; [key: string]: unknown };
// ...etc
```

Refer to the API reference for the canonical Treasury schemas. {/* TODO: tighten the TreasuryDashboardSummary, TreasurySecurityRuleData, TreasuryAutoTransferRuleData, etc. shapes in a follow-up release. */}

## Examples [#examples]

### Send + confirm with a security code [#send--confirm-with-a-security-code]

```ts
const send = await easy.treasurySend({
  recipient_id, amount: 1500000, source_account_id, method: "wire",
});
// Out of band, your approver retrieves a code, then:
await easy.confirmTreasurySend({ transaction_id: send.data.id, security_code: "123456" });
```

### Plaid-linked recipient onboarding [#plaid-linked-recipient-onboarding]

```ts
const linkToken = await easy.getTreasuryRecipientPlaidLinkToken({ invitation_token });
// Hand linkToken.data.link_token to Plaid Link in the recipient's browser.
// On success, exchange the public token:
await easy.exchangeTreasuryRecipientPlaidToken({
  invitation_token,
  public_token,
  account_id,
  institution_name,
  account_name,
  account_mask,
});
```

### Approval flow [#approval-flow]

```ts
const tx = await easy.treasurySend({ /* … */ });
const approval = await easy.createTreasuryApprovalRequest({
  transaction_id: tx.data.id,
  security_rule_id: ruleId,
});

// In the approver's UI:
await easy.resolveTreasuryApprovalRequest(approval.data.id, { action: "approve" });
```


# Wallet Checkout (/docs/sdks/node/resources/wallet-checkout)



{/* TODO: One-paragraph description of the resource. */}

## Methods [#methods]

{/* TODO: list / retrieve / create / update / delete — code blocks per method. */}

## Object shape [#object-shape]

{/* TODO: Table of fields with types; link to API reference for the canonical schema. */}

## Examples [#examples]

{/* TODO: Two or three realistic snippets (e.g. listing with filters, idempotent create, partial update). */}


# Webhook Endpoints (/docs/sdks/node/resources/webhook-endpoints)



Webhook endpoints are HTTPS URLs that receive event deliveries. Register up to 5 active endpoints per company, each subscribed to all events (`["*"]`) or a specific subset of `EASY_EVENT_TYPES`. The signing secret is returned **only on creation** — store it immediately.

For verifying inbound deliveries, see the top-level [Webhooks](../webhooks) page.

## Methods [#methods]

```ts
easy.registerWebhookEndpoint(body);                  // POST   /webhooks
easy.listWebhookEndpoints();                         // GET    /webhooks
easy.updateWebhookEndpoint(endpointId, body);        // PATCH  /webhooks/:id
easy.deleteWebhookEndpoint(endpointId);              // DELETE /webhooks/:id
easy.listWebhookDeliveries(query?);                  // GET    /webhooks/deliveries
easy.listEndpointDeliveries(endpointId, query?);     // GET    /webhooks/:id/deliveries
```

### Register [#register]

```ts
const ep = await easy.registerWebhookEndpoint({
  url: "https://api.example.com/webhooks/easy",
  events: ["payment.created", "subscription.updated", "invoice.paid"], // or ["*"]
});

console.log(ep.data.id);
console.log(ep.data.secret); // <-- store this NOW; it's never returned again
```

The URL must be HTTPS and cannot resolve to private / loopback addresses. The maximum is 5 active endpoints per company.

### List, update, delete [#list-update-delete]

```ts
const all = await easy.listWebhookEndpoints();
await easy.updateWebhookEndpoint(ep.data.id, { active: false });
await easy.deleteWebhookEndpoint(ep.data.id);
```

### Inspect deliveries [#inspect-deliveries]

`listWebhookDeliveries` is the cross-endpoint delivery log. `listEndpointDeliveries(endpointId, query)` is the same shape scoped to one endpoint (no `endpoint_id` or `include_counts` parameters there).

```ts
const deliveries = await easy.listWebhookDeliveries({
  event_type: "invoice.payment_failed",
  success: false,
  created_after: "2026-04-01T00:00:00Z",
  limit: 100,
  include_counts: true,
});

console.log(deliveries.data.total, deliveries.data.event_counts, deliveries.data.failed_count);
```

## Object shape [#object-shape]

`RegisteredWebhookEndpoint extends WebhookEndpoint`:

| Field                  | Type                                | Notes                                      |
| ---------------------- | ----------------------------------- | ------------------------------------------ |
| `id`                   | `string`                            |                                            |
| `url`                  | `string`                            |                                            |
| `events`               | `string[]`                          | `["*"]` or specific event types.           |
| `active`               | `boolean`                           |                                            |
| `status`               | `"enabled" \| "disabled" \| string` |                                            |
| `consecutive_failures` | `number`                            | Endpoints auto-disable after repeated 5xx. |
| `last_triggered_at`    | `string \| null`                    |                                            |
| `secret`               | `string`                            | **Only on the create response.**           |

`WebhookDelivery`: `id`, `endpoint_id`, `event_type`, `payload` (`WebhookEvent`), `attempt`, `attempt_number`, `status_code`, `response_code`, `response_body`, `response_body_hash`, `response_time`, `error`, `success`, `created_at`, `next_retry_at`.

`WebhookDeliveriesListQuery`: `event_type?`, `success?`, `attempt?`, `attempt_number?`, `created_after?`, `created_before?`, `endpoint_id?`, `limit?`, `offset?`, `include_counts?`.

## Examples [#examples]

### Bootstrap a fresh endpoint at deploy time [#bootstrap-a-fresh-endpoint-at-deploy-time]

```ts
const all = await easy.listWebhookEndpoints();
const expectedUrl = `${process.env.PUBLIC_URL}/webhooks/easy`;
const existing = all.data.find((e) => e.url === expectedUrl);

if (!existing) {
  const created = await easy.registerWebhookEndpoint({
    url: expectedUrl,
    events: ["*"],
  });
  // Persist created.data.secret in a secret manager — you can't read it back later.
  process.env.EASY_WEBHOOK_SECRET = created.data.secret;
}
```

### Replay a failed delivery's payload locally [#replay-a-failed-deliverys-payload-locally]

```ts
const failed = await easy.listEndpointDeliveries(endpointId, {
  success: false,
  limit: 1,
});
const delivery = failed.data.deliveries[0];
console.log(delivery.payload); // typed WebhookEvent
```

### Rotate an endpoint's URL [#rotate-an-endpoints-url]

```ts
await easy.updateWebhookEndpoint(endpointId, {
  url: "https://api.example.com/v2/webhooks/easy",
});
```

### Rotate the signing secret [#rotate-the-signing-secret]

There is no rotate-secret endpoint. Delete the old endpoint and register a new one to issue a fresh secret:

```ts
const replacement = await easy.registerWebhookEndpoint({
  url: existing.url,
  events: existing.events as any,
});
await easy.deleteWebhookEndpoint(existing.id);
// store replacement.data.secret
```


# E-commerce Flow (/docs/sdks/python/examples/ecommerce-flow)



An end-to-end recipe for a typical e-commerce order: tokenize a card
on the front-end, save it as a payment instrument, charge it once, and
fulfill the order from a webhook.

## Goal [#goal]

You're selling discrete goods, not subscriptions. The flow you want is:

1. Customer enters card details — tokenized client-side via Basis Theory
   (the `client.basis_theory_public_api_key` is what your front-end
   uses).
2. Your server creates a `Customer`, attaches the card as a
   `PaymentInstrument`, and charges the cart in one shot via
   `client.checkout.create(...)`.
3. The `payment.created` webhook fires; your handler marks the order
   paid and triggers fulfillment.

## Implementation [#implementation]

### 1. Server: tokenize → checkout in one call [#1-server-tokenize--checkout-in-one-call]

```python
import os
import uuid
from easylabs import Client, EasyError, RateLimitError

client = Client(api_key=os.environ["EASY_API_KEY"])


def place_order(*, user, cart, card_token):
    """Charge the user once for `cart`. Idempotent on cart.id."""
    try:
        result = client.checkout.create(
            customer={
                "first_name": user.first_name,
                "last_name": user.last_name,
                "email": user.email,
            },
            payment_instrument={
                "type": "PAYMENT_CARD",
                "name": user.full_name,
                "token_id": card_token,        # from Basis Theory in the browser
            },
            items=[
                {"price_id": item.price_id, "quantity": item.quantity}
                for item in cart.items
            ],
            idempotency_key=f"order-{cart.id}",
        )
    except RateLimitError as e:
        raise RetryAfter(e.retry_after_seconds or 5)
    except EasyError as e:
        raise OrderFailed(e.code, e.message, e.details)

    return {
        "order_id": result.order_id,
        "transfer_id": result.transfer.id if result.transfer else None,
    }
```

### 2. Webhook handler: mark paid, fulfill [#2-webhook-handler-mark-paid-fulfill]

```python
from easylabs import Webhooks, InvalidRequestError

SECRET = os.environ["EASY_WEBHOOK_SECRET"]


def receive_webhook(request):
    try:
        event = Webhooks.construct_event(
            payload=request.body,
            signature=request.headers.get("x-easy-webhook-signature", ""),
            secret=SECRET,
        )
    except InvalidRequestError:
        return ("invalid", 400)

    # Idempotent: skip if we've already processed this event.
    if WebhookSeen.exists(event.id):
        return ("", 204)
    WebhookSeen.record(event.id)

    if event.type == "payment.created":
        transfer = event.data
        order_id = (transfer.get("tags") or {}).get("order_id")
        if order_id:
            mark_order_paid(order_id, transfer["id"])
            enqueue_fulfillment(order_id)

    return ("", 204)
```

### 3. Refund path [#3-refund-path]

```python
def refund_order(order):
    return client.transfers.create_refund(
        order.transfer_id,
        refund_amount=order.total_cents,
        tags={"reason": "customer_request"},
        idempotency_key=f"refund-{order.id}-full",
    )
```

## Tradeoffs [#tradeoffs]

* **Idempotency keys are non-negotiable.** Without them, a retry on a
  flaky network can charge the customer twice. The keys above are
  deterministic per cart / order.
* **Webhooks must be idempotent on `event.id`.** Easy Labs retries on
  non-2xx responses; the same event will arrive more than once if your
  handler is slow or the network blips.
* **Don't poll.** If you find yourself calling
  `client.transfers.retrieve(...)` in a loop, you're papering over
  webhook plumbing that's failing somewhere.
* **For two-step "auth then capture" flows** (e.g. ship-then-charge),
  swap `client.checkout.create(...)` for an authorization-only checkout
  and use [`client.authorizations`](../resources/authorizations).


# Refunds (/docs/sdks/python/examples/refunds)



An end-to-end recipe for issuing refunds — full and partial — including
idempotency, webhook follow-up, and retry handling.

## Goal [#goal]

Refunds are reversals on transfers (see the
[Refunds resource page](../resources/refunds)). The SDK exposes them as
`client.transfers.create_refund(...)`, not a separate `client.refunds`
namespace. This recipe covers:

* Full refund of a single transfer.
* Partial refund with metadata for ops tooling.
* Retry-safe webhook flow that reacts to `refund.updated`.

## Implementation [#implementation]

### 1. Full refund [#1-full-refund]

```python
import os
from easylabs import Client

client = Client(api_key=os.environ["EASY_API_KEY"])


def full_refund(transfer_id):
    transfer = client.transfers.retrieve(transfer_id)
    return client.transfers.create_refund(
        transfer.id,
        refund_amount=transfer.amount,
        tags={"reason": "customer_request", "kind": "full"},
        idempotency_key=f"refund-{transfer.id}-full",
    )
```

### 2. Partial refund with reason tracking [#2-partial-refund-with-reason-tracking]

```python
def partial_refund(*, transfer_id, amount_cents, reason, ticket_id):
    return client.transfers.create_refund(
        transfer_id,
        refund_amount=amount_cents,
        tags={
            "reason": reason,
            "ticket_id": ticket_id,
            "kind": "partial",
        },
        idempotency_key=f"refund-{transfer_id}-{ticket_id}",
    )
```

### 3. Retry-safe call wrapper [#3-retry-safe-call-wrapper]

```python
import time
from easylabs import RateLimitError, ServerError, EasyError


def with_retries(fn, attempts=5):
    for i in range(attempts):
        try:
            return fn()
        except RateLimitError as e:
            time.sleep(e.retry_after_seconds or 1)
        except ServerError:
            time.sleep(min(2 ** i, 30))
    return fn()  # last attempt; let it raise
```

Wrap any of the refund calls in `with_retries(...)` to survive transient
issues without losing idempotency.

### 4. React to refund webhooks [#4-react-to-refund-webhooks]

```python
from easylabs import Webhooks, InvalidRequestError

SECRET = os.environ["EASY_WEBHOOK_SECRET"]


def receive(request):
    try:
        event = Webhooks.construct_event(
            payload=request.body,
            signature=request.headers.get("x-easy-webhook-signature", ""),
            secret=SECRET,
        )
    except InvalidRequestError:
        return ("invalid", 400)

    if event.type == "refund.updated":
        refund = event.data
        if refund.get("state") == "SUCCEEDED":
            mark_refund_completed(refund["id"], refund["amount"])
        elif refund.get("state") == "FAILED":
            alert_ops(refund["id"], refund.get("failure_message"))

    return ("", 204)
```

## Tradeoffs [#tradeoffs]

* **Always pass `idempotency_key`.** A network blip during refund
  creation that retries without an idempotency key will refund the
  customer twice — and chargebacks for double refunds are the worst.
* **Don't poll for completion.** Refunds may take seconds (cards) to
  several days (ACH). Wait for the `refund.updated` webhook to flip
  to `SUCCEEDED`.
* **Reverse-then-resell is rarely what you want.** If the customer
  bought the wrong item, refund + create a new order rather than
  trying to mutate the original.
* **Disputes ≠ refunds.** If the cardholder has already opened a
  chargeback, manage it via [`client.disputes`](../resources/disputes)
  — issuing a refund on a disputed transfer can leave you double-paying.


# Subscription System (/docs/sdks/python/examples/subscription-system)



An end-to-end recipe for a SaaS subscription system: catalog setup,
sign-up, mid-cycle upgrades with proration, pause, and cancel-at-period-
end. All using the Python SDK.

## Goal [#goal]

You're building a SaaS app with monthly + annual plans, optional
add-on seats, and a self-service "Manage subscription" page.

The data model:

* **Products** — one per plan tier ("Free", "Pro", "Team").
* **Prices** — recurring monthly / annual price per tier, plus a
  per-seat add-on price.
* **Subscriptions** — one per customer; items reference prices.

## Implementation [#implementation]

### 1. Bootstrap the catalog (one-time) [#1-bootstrap-the-catalog-one-time]

```python
import os
from easylabs import Client

client = Client(api_key=os.environ["EASY_API_KEY"])

pro = client.products.create(name="Pro", description="Pro tier")
team = client.products.create(name="Team", description="Team tier")

pro_monthly = client.product_prices.create(
    product_id=pro.id,
    currency="USD",
    unit_amount=2900,
    recurring=True, interval="month", interval_count=1,
)
pro_annual = client.product_prices.create(
    product_id=pro.id,
    currency="USD",
    unit_amount=29000,
    recurring=True, interval="year", interval_count=1,
)
seat_addon = client.product_prices.create(
    product_id=team.id,
    currency="USD",
    unit_amount=1500,
    recurring=True, interval="month", interval_count=1,
)
```

### 2. Sign-up flow — checkout + start subscription atomically [#2-sign-up-flow--checkout--start-subscription-atomically]

```python
def signup(*, user, plan_price_id, card_token):
    return client.checkout.create(
        customer={
            "first_name": user.first_name,
            "last_name": user.last_name,
            "email": user.email,
        },
        payment_instrument={
            "type": "PAYMENT_CARD",
            "name": user.full_name,
            "token_id": card_token,
        },
        subscriptions=[{"items": [{"price_id": plan_price_id, "quantity": 1}]}],
        idempotency_key=f"signup-{user.id}",
    )
```

Persist `result.subscriptions[0]["id"]` against the user record so you
can manage the subscription later.

### 3. Mid-cycle plan change with proration preview [#3-mid-cycle-plan-change-with-proration-preview]

```python
def preview_upgrade(*, sub_id, new_price_id, old_item_id):
    return client.subscriptions.proration_preview(
        sub_id,
        items=[{"price_id": new_price_id, "quantity": 1}],
        remove_items=[old_item_id],
    )

def apply_upgrade(*, sub_id, new_price_id, old_item_id):
    client.subscriptions.add_item(
        sub_id, price_id=new_price_id,
        idempotency_key=f"upgrade-{sub_id}-add-{new_price_id}",
    )
    client.subscriptions.remove_item(
        sub_id, old_item_id,
        idempotency_key=f"upgrade-{sub_id}-remove-{old_item_id}",
    )
```

### 4. Add seats to a Team subscription [#4-add-seats-to-a-team-subscription]

```python
def set_seat_count(*, sub_id, seat_item_id, seats):
    client.subscriptions.update_item(
        sub_id, seat_item_id,
        quantity=seats,
        idempotency_key=f"seats-{sub_id}-{seats}",
    )
```

### 5. Apply a coupon [#5-apply-a-coupon]

```python
def apply_coupon(*, sub_id, coupon_id):
    client.subscriptions.apply_discount(
        sub_id,
        coupon_id=coupon_id,
        idempotency_key=f"discount-{sub_id}-{coupon_id}",
    )
```

### 6. Pause / resume / cancel [#6-pause--resume--cancel]

```python
def pause(sub_id, resumes_at):
    client.subscriptions.pause(
        sub_id, behavior="mark_uncollectible", resumes_at=resumes_at,
    )

def resume(sub_id):
    client.subscriptions.resume(sub_id)

def cancel(sub_id, immediate=False):
    client.subscriptions.cancel(
        sub_id,
        at_period_end=not immediate,
    )
```

### 7. React to lifecycle webhooks [#7-react-to-lifecycle-webhooks]

```python
def on_event(event):
    if event.type == "subscription.trial_will_end":
        send_trial_ending_email(event.data["identity_id"])

    elif event.type == "invoice.payment_failed":
        notify_dunning(event.data["customer_id"], event.data["id"])

    elif event.type == "subscription.deleted":
        downgrade_account(event.data["identity_id"])
```

## Tradeoffs [#tradeoffs]

* **Always preview proration before applying.** Show the user the exact
  amount they'll be charged today; surprise charges drive disputes.
* **Use `cancel(at_period_end=True)` for self-service cancellations.**
  It avoids refund accounting, leaves the customer with paid access
  until the cycle ends, and gives you a window to send a save-attempt
  email.
* **Configure dunning before going live.** See the
  [Dunning](../resources/dunning) page — without it, failed renewals
  silently retry once and then cancel.
* **One subscription per customer is simplest.** Multiple parallel
  subscriptions per customer are supported but make the UI and
  invoicing materially harder.


# Analytics (/docs/sdks/python/resources/analytics)



Read aggregated metrics for your account. All five methods take the
same shape (`period`, `start_date`, `end_date`) and return the raw
`data` payload as a `dict` — the response shape varies per metric, so
the SDK doesn't strongly type it.

Namespace: `client.analytics`.

| Method                  | Underlying endpoint               |
| ----------------------- | --------------------------------- |
| `transactions(...)`     | `GET /analytics/transactions`     |
| `disputes(...)`         | `GET /analytics/disputes`         |
| `settlements(...)`      | `GET /analytics/settlements`      |
| `revenue(...)`          | `GET /analytics/revenue`          |
| `revenue_recovery(...)` | `GET /analytics/revenue-recovery` |

## Methods [#methods]

Every method has the same signature:

```python
client.analytics.transactions(
    period=None,                           # e.g. "7d", "30d", "month"
    start_date=None,                       # ISO-8601
    end_date=None,                         # ISO-8601
)
```

Pass `period=` for a relative window or `start_date=` + `end_date=` for
an explicit range. Returns a `dict` whose shape depends on the metric.

### `transactions` [#transactions]

```python
data = client.analytics.transactions(period="30d")
print(data["total_count"], data["total_volume_cents"])
```

### `disputes` [#disputes]

```python
data = client.analytics.disputes(start_date="2026-01-01", end_date="2026-04-01")
```

### `settlements` [#settlements]

```python
data = client.analytics.settlements(period="7d")
```

### `revenue` [#revenue]

```python
data = client.analytics.revenue(period="month")
```

### `revenue_recovery` [#revenue_recovery]

```python
data = client.analytics.revenue_recovery(period="90d")
```

## Object shape [#object-shape]

Responses come back as `dict[str, Any]` rather than typed models —
analytics endpoints intentionally have flexible, metric-specific
shapes. See the
[Easy Labs API reference](https://docs.itseasy.co/api) for the
canonical schema per endpoint.

## Examples [#examples]

### Build a daily revenue dashboard widget [#build-a-daily-revenue-dashboard-widget]

```python
revenue = client.analytics.revenue(period="30d")
print(f"30-day revenue: ${revenue['total_cents'] / 100:,.2f}")
```

### Compare disputes month over month [#compare-disputes-month-over-month]

```python
this_month = client.analytics.disputes(period="month")
last_month = client.analytics.disputes(
    start_date="2026-04-01",
    end_date="2026-04-30",
)
delta = this_month["count"] - last_month["count"]
log.info("disputes vs. last month: %+d", delta)
```

### Audit recovery effectiveness [#audit-recovery-effectiveness]

```python
recovery = client.analytics.revenue_recovery(period="90d")
print(recovery)
```


# Authorizations (/docs/sdks/python/resources/authorizations)



An `Authorization` represents a hold on a customer's payment instrument
that hasn't been captured yet — useful for two-step "auth then capture"
flows (rentals, marketplaces, pre-orders).

Namespace: `client.authorizations`. Authorizations are typically
*created* via the checkout flow with `auth_only=True`; this resource
exposes the read + capture/void endpoints.

## Methods [#methods]

### `list` [#list]

```python
auths = client.authorizations.list(limit=50, offset=0)
batch = client.authorizations.list(ids=["auth_1", "auth_2"])
```

Returns `list[Authorization]`.

### `retrieve` [#retrieve]

```python
auth = client.authorizations.retrieve("auth_123")
```

### `capture` [#capture]

```python
captured = client.authorizations.capture(
    "auth_123",
    amount=2000,                           # ≤ original auth amount
    idempotency_key="capture-auth_123-1",
)
```

Captures funds against the existing hold. `amount` is required and is
the amount you want to actually charge (in the smallest currency unit).

### `void` [#void]

```python
voided = client.authorizations.void(
    "auth_123",
    idempotency_key="void-auth_123-1",
)
```

Releases the hold without charging.

## Object shape [#object-shape]

`Authorization`:

| Field                      | Type                     |
| -------------------------- | ------------------------ |
| `id`                       | `str`                    |
| `state`                    | `str \| None`            |
| `amount`                   | `int \| None`            |
| `currency`                 | `str \| None`            |
| `captured_amount`          | `int \| None`            |
| `voided`                   | `bool \| None`           |
| `transfer_id`              | `str \| None`            |
| `payment_instrument_id`    | `str \| None`            |
| `expires_at`               | `str \| None`            |
| `tags`                     | `dict[str, Any] \| None` |
| `created_at`, `updated_at` | `str \| None`            |

## Examples [#examples]

### Auth on order, capture on ship [#auth-on-order-capture-on-ship]

```python
# 1. (Checkout flow elsewhere creates the auth — auth_id returned)

# 2. When the order ships, capture the actual amount
client.authorizations.capture(
    auth_id,
    amount=order.shipped_total_cents,
    idempotency_key=f"capture-{auth_id}",
)
```

### Void a hold after the customer cancels [#void-a-hold-after-the-customer-cancels]

```python
client.authorizations.void(
    auth_id,
    idempotency_key=f"void-{auth_id}",
)
```

### Sweep expiring authorizations [#sweep-expiring-authorizations]

```python
import datetime as dt

soon = dt.datetime.now(dt.timezone.utc) + dt.timedelta(days=1)
for a in client.authorizations.list(limit=200):
    if a.expires_at and a.expires_at <= soon.isoformat():
        log.warning("auth %s expires at %s", a.id, a.expires_at)
```


# Checkout (/docs/sdks/python/resources/checkout)



The `client.checkout` resource creates a one-shot, server-side checkout
that combines a payment, an order, and (optionally) subscriptions in a
single API call. Use it when you already have a tokenized payment
instrument and want to charge + record + subscribe atomically.

Namespace: `client.checkout`.

Other checkout surfaces live next door:

* [Payment Links](./payment-links) — share a hosted URL.
* [Embedded Checkout](./embedded-checkout) — render a session in your own UI.

## Methods [#methods]

### `create` [#create]

```python
result = client.checkout.create(
    customer={
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com",
    },
    payment_instrument={
        "type": "PAYMENT_CARD",
        "name": "Ada Lovelace",
        "token_id": "tok_abc",
    },
    items=[
        {"price_id": "price_widget", "quantity": 2},
    ],
    idempotency_key="checkout-cart-2025-01-01-001",
)

print(result.transfer.id if result.transfer else None)
print(result.order_id)
```

Returns: `CheckoutResponse`. All fields are accepted via `**kwargs`;
see the [Easy Labs API reference](https://docs.itseasy.co/api) for the
full request schema.

## Object shape [#object-shape]

`CheckoutResponse`:

| Field           | Type                            | Notes                                                         |
| --------------- | ------------------------------- | ------------------------------------------------------------- |
| `transfer`      | `Transfer \| None`              | The charge created by the call.                               |
| `order_id`      | `str \| None` (alias `orderId`) | The `Order` produced (look up with `client.orders.retrieve`). |
| `subscriptions` | `list[dict[str, Any]] \| None`  | Any subscriptions started in the same call.                   |
| `order`         | `dict[str, Any] \| None`        | Full order payload when expanded.                             |
| `customer`      | `dict[str, Any] \| None`        | The customer that was created or matched.                     |

## Examples [#examples]

### Charge a returning customer with a saved instrument [#charge-a-returning-customer-with-a-saved-instrument]

```python
result = client.checkout.create(
    identity_id="ident_123",
    payment_instrument_id="pi_abc",
    items=[{"price_id": "price_widget", "quantity": 1}],
    idempotency_key=f"order-{order_id}",
)

if result.transfer and result.transfer.state == "SUCCEEDED":
    fulfill_order(result.order_id)
```

### Combine a one-time charge with a subscription start [#combine-a-one-time-charge-with-a-subscription-start]

```python
result = client.checkout.create(
    customer={"first_name": "Ada", "last_name": "L.", "email": "a@b.c"},
    payment_instrument={"type": "PAYMENT_CARD", "name": "Ada", "token_id": "tok_abc"},
    items=[{"price_id": "price_setup_fee", "quantity": 1}],
    subscriptions=[{"items": [{"price_id": "price_monthly"}]}],
    idempotency_key="signup-ada-2025-01-01",
)

setup_charge = result.transfer
new_subs = result.subscriptions or []
```


# Compliance Forms (/docs/sdks/python/resources/compliance-forms)



Compliance forms are the regulatory documents (W-9, terms of service,
processor agreements, etc.) the operator is asked to sign before, or
during, doing business on the Easy Labs platform.

Namespace: `client.compliance_forms`.

## Methods [#methods]

### `list` [#list]

```python
forms = client.compliance_forms.list()
```

Returns `list[ComplianceForm]`. No pagination — the full list is
returned in one call.

### `retrieve` [#retrieve]

```python
form = client.compliance_forms.retrieve("form_123")
```

### `sign` [#sign]

```python
signed = client.compliance_forms.sign(
    "form_123",
    signer_name="Ada Lovelace",
    signer_title="CEO",
    signed_at="2026-05-01T15:30:00Z",
    idempotency_key="sign-form_123-2026-05-01",
)
```

PUT-based — accepts arbitrary fields via `**kwargs` for processor-
specific metadata. Returns the updated `ComplianceForm`.

## Object shape [#object-shape]

`ComplianceForm` follows the canonical API shape. Common fields:

| Field                      | Notes                                 |
| -------------------------- | ------------------------------------- |
| `id`                       | Always present.                       |
| `type`                     | Form type (`"w9"`, `"terms"`, etc.).  |
| `status`                   | `"pending"`, `"signed"`, `"expired"`. |
| `signed_at`                | ISO-8601 once signed.                 |
| `created_at`, `updated_at` | Standard.                             |

## Examples [#examples]

### Render a "things you still need to sign" panel [#render-a-things-you-still-need-to-sign-panel]

```python
forms = client.compliance_forms.list()
pending = [f for f in forms if (f.status or "").lower() == "pending"]
for f in pending:
    print(f.id, f.type)
```

### Sign during onboarding [#sign-during-onboarding]

```python
client.compliance_forms.sign(
    form_id,
    signer_name=user.full_name,
    signer_title=user.title or "Owner",
    signed_at=dt.datetime.now(dt.timezone.utc).isoformat(),
    idempotency_key=f"sign-{form_id}-{user.id}",
)
```


# Coupons (/docs/sdks/python/resources/coupons)



A `Coupon` is a reusable discount template — a flat amount or a
percentage off, optionally limited by duration, redemption count, or a
redeem-by date. Coupons are applied to subscriptions either directly
(`subscription.apply_discount(coupon_id=...)`) or wrapped in a
[Promotion Code](./promotion-codes) for end-user-facing flows.

Namespace: `client.coupons`.

## Methods [#methods]

### `create` [#create]

```python
# Percentage off
coupon = client.coupons.create(
    name="25% off",
    percent_off=25,
    duration="forever",
    idempotency_key="coupon-25-forever",
)

# Flat-amount off (one currency)
coupon = client.coupons.create(
    name="$10 off",
    amount_off=1000,
    currency="USD",
    duration="once",
)

# Time-boxed
coupon = client.coupons.create(
    name="Spring promo",
    percent_off=15,
    duration="repeating",
    duration_in_months=3,
    redeem_by="2026-06-01T00:00:00Z",
    max_redemptions=500,
)
```

Pass exactly one of `percent_off` or `amount_off`. Returns: `Coupon`.

### `list` [#list]

```python
coupons = client.coupons.list(limit=50, offset=0)
```

### `retrieve` [#retrieve]

```python
coupon = client.coupons.retrieve("cou_123")
```

### `update` [#update]

```python
coupon = client.coupons.update("cou_123", name="25% off (legacy)")
```

Most fields are immutable on the server — typically you'll only update
the display `name` and `metadata`.

### `delete` [#delete]

```python
client.coupons.delete("cou_123")
```

## Object shape [#object-shape]

`Coupon`:

| Field                                  | Type                                                 |
| -------------------------------------- | ---------------------------------------------------- |
| `id`                                   | `str`                                                |
| `name`, `code`                         | `str \| None`                                        |
| `duration`                             | `str \| None` (`"once"`, `"forever"`, `"repeating"`) |
| `duration_in_months`                   | `int \| None`                                        |
| `amount_off`                           | `int \| None`                                        |
| `percent_off`                          | `float \| None`                                      |
| `currency`                             | `str \| None`                                        |
| `max_redemptions`                      | `int \| None`                                        |
| `times_redeemed`                       | `int \| None`                                        |
| `redeem_by`                            | `str \| None` (ISO-8601)                             |
| `valid`                                | `bool \| None`                                       |
| `metadata`, `created_at`, `updated_at` | Standard.                                            |

## Examples [#examples]

### Apply a coupon to an existing subscription [#apply-a-coupon-to-an-existing-subscription]

```python
discount = client.subscriptions.apply_discount(
    "sub_123",
    coupon_id="cou_25_off",
)
```

### Time-boxed campaign that auto-expires [#time-boxed-campaign-that-auto-expires]

```python
client.coupons.create(
    name="Black Friday 2026",
    percent_off=30,
    duration="once",
    redeem_by="2026-12-01T08:00:00Z",
    max_redemptions=1000,
)
```


# Customers (/docs/sdks/python/resources/customers)



A `Customer` represents one end-user of your business — the person you
charge, subscribe, refund, or invoice. Customers are the parent of
payment instruments, orders, subscriptions, and wallets, all of which
are reachable as helper methods on this resource.

Namespace: `client.customers`.

## Methods [#methods]

### `create` [#create]

```python
customer = client.customers.create(
    first_name="Ada",
    last_name="Lovelace",
    email="ada@example.com",
    phone="+15551234567",
    personal_address={
        "line1": "1 Babbage St",
        "city": "London",
        "country": "GB",
    },
    tags={"plan": "founder"},
    idempotency_key="customer-ada-2025-01-01",
)
```

Returns: `Customer`. Only `first_name` and `last_name` are required.

### `update` [#update]

```python
customer = client.customers.update(
    "cus_123",
    phone="+15559999999",
    tags={"plan": "growth"},
)
```

Accepts arbitrary fields via `**kwargs` and PATCHes them. Returns
the updated `Customer`.

### `retrieve` [#retrieve]

```python
customer = client.customers.retrieve("cus_123")
```

### `list` [#list]

```python
customers = client.customers.list(limit=50, offset=0)

# Look up specific customers by ID
batch = client.customers.list(ids=["cus_1", "cus_2"])
```

Returns `list[Customer]`. See [Pagination](../pagination) for offset
walking patterns.

### `payment_instruments` [#payment_instruments]

```python
instruments = client.customers.payment_instruments("cus_123")
```

Returns `list[PaymentInstrument]` for the customer.

### `orders` [#orders]

```python
orders = client.customers.orders("cus_123", limit=20)
```

Returns `list[Order]`.

### `subscriptions` [#subscriptions]

```python
page = client.customers.subscriptions("cus_123", status="active", limit=20)
print(page["total"])
for sub in page["data"]:           # list[Subscription]
    print(sub.id, sub.status)
```

Returns the paginated envelope `{ data, total, limit, offset }` as a
plain `dict` — `data` contains `Subscription` models.

### `wallets` [#wallets]

```python
wallets = client.customers.wallets("cus_123")
```

Returns `list[Wallet]`.

## Object shape [#object-shape]

The `Customer` model surfaces the most common fields with type hints;
unknown fields are still accessible because `EasyModel` allows extras.

| Field            | Type                     | Notes                                 |
| ---------------- | ------------------------ | ------------------------------------- |
| `id`             | `str`                    | Always present.                       |
| `created_at`     | `str \| None`            | ISO-8601.                             |
| `updated_at`     | `str \| None`            | ISO-8601.                             |
| `type`           | `str \| None`            | Identity type (e.g. `"PERSONAL"`).    |
| `application`    | `str \| None`            | Easy Labs application ID.             |
| `identity_roles` | `list[str] \| None`      |                                       |
| `entity`         | `dict[str, Any] \| None` | Structured personal/business profile. |
| `tags`           | `dict[str, Any] \| None` | Free-form metadata you set.           |

The full canonical shape lives in the
[Easy Labs API reference](https://docs.itseasy.co/api).

## Examples [#examples]

### Idempotent create from a webhook handler [#idempotent-create-from-a-webhook-handler]

```python
def on_signup(user, raw_request):
    customer = client.customers.create(
        first_name=user.first_name,
        last_name=user.last_name,
        email=user.email,
        idempotency_key=f"signup-{user.id}",   # safe to retry
    )
    user.update(easy_customer_id=customer.id)
```

### List + walk every customer [#list--walk-every-customer]

```python
PAGE = 100
offset = 0
while True:
    page = client.customers.list(limit=PAGE, offset=offset)
    if not page:
        break
    for c in page:
        print(c.id, c.email)
    if len(page) < PAGE:
        break
    offset += PAGE
```

### Aggregate a customer's payments [#aggregate-a-customers-payments]

```python
instruments = client.customers.payment_instruments("cus_123")
orders = client.customers.orders("cus_123")
total_paid = sum(o.total or 0 for o in orders)
print(f"{len(instruments)} cards, ${total_paid / 100:.2f} lifetime")
```


# Disputes (/docs/sdks/python/resources/disputes)



A `Dispute` is a chargeback raised by a cardholder. The Python SDK
exposes the read endpoints, the tag-only update, the lifecycle actions
(`accept`, `submit`), plus evidence upload + listing.

Namespace: `client.disputes`.

## Methods [#methods]

### `retrieve` [#retrieve]

```python
dispute = client.disputes.retrieve("dp_123")
```

### `list` [#list]

```python
disputes = client.disputes.list(limit=50, offset=0)
```

Returns `list[Dispute]`.

### `update` [#update]

```python
dispute = client.disputes.update(
    "dp_123",
    tags={"reviewed_by": "ops@example.com"},
)
```

Only `tags` is mutable from the API.

### `accept` [#accept]

```python
result = client.disputes.accept(
    "dp_123",
    idempotency_key="dispute-accept-dp_123",
)
```

Concedes the dispute. Returns the raw `data` payload — shape varies
by processor.

### `submit` [#submit]

```python
client.disputes.submit("dp_123", idempotency_key="dispute-submit-dp_123")
```

Submits previously-uploaded evidence for review. Call once you've
finished `upload_evidence(...)` for every supporting document.

### `upload_evidence` [#upload_evidence]

```python
with open("receipt.pdf", "rb") as f:
    client.disputes.upload_evidence(
        "dp_123",
        file=f,
        filename="receipt.pdf",
        content_type="application/pdf",
        idempotency_key="dispute-evidence-receipt",
    )
```

Multipart upload. The API accepts JPEG / PNG / PDF up to 1 MB per file.
Call once per file, then call `submit(...)` to finalize.

### `list_evidence` [#list_evidence]

```python
files = client.disputes.list_evidence("dp_123")
```

Returns the raw `data` payload (list of evidence file objects).

## Object shape [#object-shape]

`Dispute` follows the canonical API shape. The common fields:

| Field                      | Notes                                               |
| -------------------------- | --------------------------------------------------- |
| `id`                       | Always present.                                     |
| `state`                    | `"NEEDS_RESPONSE"`, `"PENDING"`, `"WON"`, `"LOST"`. |
| `amount`                   | Integer in the smallest currency unit.              |
| `currency`                 | Three-letter ISO.                                   |
| `transfer_id`              | The disputed transfer.                              |
| `due_at`                   | Deadline for evidence submission.                   |
| `tags`                     | Free-form metadata; mutable via `update`.           |
| `created_at`, `updated_at` | Standard.                                           |

## Examples [#examples]

### React to a `dispute.created` webhook [#react-to-a-disputecreated-webhook]

```python
if event.type == "dispute.created":
    dispute = event.data
    notify_ops(dispute["id"], dispute.get("amount"), dispute.get("due_at"))
```

### Build, upload, and submit evidence [#build-upload-and-submit-evidence]

```python
for path, mime in [
    ("receipt.pdf",   "application/pdf"),
    ("delivery.jpg",  "image/jpeg"),
    ("emails.pdf",    "application/pdf"),
]:
    with open(path, "rb") as f:
        client.disputes.upload_evidence(
            "dp_123",
            file=f,
            filename=path,
            content_type=mime,
            idempotency_key=f"evidence-{path}",
        )

client.disputes.submit("dp_123", idempotency_key="submit-dp_123-1")
```

### Concede when the cost of contesting outweighs the chargeback [#concede-when-the-cost-of-contesting-outweighs-the-chargeback]

```python
client.disputes.accept("dp_123", idempotency_key="accept-dp_123-1")
```


# Dunning (/docs/sdks/python/resources/dunning)



Dunning is the policy your account uses to retry failed subscription
payments and recover revenue. The Python SDK exposes two surfaces:

* `client.dunning_config` — the single, account-wide retry/recovery policy.
* `client.revenue_recovery_automations` — per-event automations layered on top.

## `client.dunning_config` [#clientdunning_config]

There is exactly one dunning config per account. The first call to
`create_or_replace` initializes it; subsequent calls overwrite.

### `create_or_replace` [#create_or_replace]

```python
config = client.dunning_config.create_or_replace(
    retry_schedule=[1, 3, 7, 14],          # days after failure to retry
    final_action="cancel",                 # or "mark_uncollectible"
    send_customer_emails=True,
    idempotency_key="dunning-2026-q2",
)
```

Returns: `DunningConfig`. All fields are accepted via `**kwargs`.

### `retrieve` [#retrieve]

```python
config = client.dunning_config.retrieve()
```

### `update` [#update]

```python
config = client.dunning_config.update(send_customer_emails=False)
```

PATCH semantics — only the fields you pass are changed.

## `client.revenue_recovery_automations` [#clientrevenue_recovery_automations]

Automations run alongside (or instead of) the built-in retry schedule —
e.g. "on second failure, send a custom email and create a follow-up
task."

### `list` [#list]

```python
automations = client.revenue_recovery_automations.list()
```

Returns `list[RevenueRecoveryAutomation]`.

### `create` [#create]

```python
automation = client.revenue_recovery_automations.create(
    name="Notify CSM on second failure",
    trigger="payment_failed",
    conditions={"attempt": 2},
    actions=[{"type": "webhook", "url": "https://example.com/csm-alert"}],
    idempotency_key="auto-csm-alert-v1",
)
```

### `update` [#update-1]

```python
client.revenue_recovery_automations.update("auto_123", enabled=False)
```

### `delete` [#delete]

```python
client.revenue_recovery_automations.delete("auto_123")
```

### `list_runs` [#list_runs]

```python
runs = client.revenue_recovery_automations.list_runs("auto_123")
for r in runs:
    print(r.id, r.status, r.created_at)
```

Returns `list[RevenueRecoveryAutomationRun]`.

## Object shape [#object-shape]

`DunningConfig` mirrors the configured policy. Common fields:

| Field                  | Notes                                      |
| ---------------------- | ------------------------------------------ |
| `retry_schedule`       | List of day offsets, e.g. `[1, 3, 7, 14]`. |
| `final_action`         | What to do once retries exhaust.           |
| `send_customer_emails` | Whether to email the customer.             |

`RevenueRecoveryAutomation` and `RevenueRecoveryAutomationRun` carry
`id`, `status`, `created_at`, plus the per-trigger configuration.

## Examples [#examples]

### Replace a stale dunning policy [#replace-a-stale-dunning-policy]

```python
client.dunning_config.create_or_replace(
    retry_schedule=[1, 3, 5],
    final_action="cancel",
    send_customer_emails=True,
    idempotency_key="dunning-2026-q3-rev1",
)
```

### Audit recent automation runs [#audit-recent-automation-runs]

```python
for auto in client.revenue_recovery_automations.list():
    runs = client.revenue_recovery_automations.list_runs(auto.id)
    failed = [r for r in runs if (r.status or "").lower() == "failed"]
    if failed:
        log.warning("automation %s has %d failed runs", auto.id, len(failed))
```

### React to recovery in your webhook handler [#react-to-recovery-in-your-webhook-handler]

```python
if event.type == "revenue_recovery.action_completed":
    log.info("recovery action ran: %s", event.data)
```


# Embedded Checkout (/docs/sdks/python/resources/embedded-checkout)



Embedded Checkout lets you render a fully-managed checkout flow in an
iframe inside your own UI. Your server creates a session via the
`x-easy-api-key`, hands the resulting `client_secret` to the browser,
and the iframe takes care of the rest.

Namespace: `client.embedded_checkout`.

Two of the methods below (`validate`, `confirm`) are **client-side
methods** that authenticate via the session's `client_secret` instead
of the SDK's API key. They're included on the Python SDK for parity
with the JS SDK's surface and for server-rendered flows that need to
proxy these calls.

## Methods [#methods]

### `create_session` [#create_session]

```python
session = client.embedded_checkout.create_session(
    items=[{"price_id": "price_abc", "quantity": 1}],
    return_url="https://example.com/checkout/return",
    idempotency_key="ecs-cart-2025-01-01-001",
)
print(session.id, session.client_secret)
```

Returns: `EmbeddedCheckoutSession`. Hand `client_secret` to the
browser; do not log it.

### `retrieve_session` [#retrieve_session]

```python
status = client.embedded_checkout.retrieve_session("ecs_123")
print(status.status, status.payment_status)
```

Returns: `EmbeddedCheckoutSessionStatus`.

### `crypto_status` [#crypto_status]

```python
crypto = client.embedded_checkout.crypto_status("ecs_123")
print(crypto.status, crypto.tx_signature)
```

Returns: `CryptoPaymentStatus` — for sessions paid via on-chain assets.

### `validate` (client-side) [#validate-client-side]

```python
ok = client.embedded_checkout.validate(
    client_secret="ecs_secret_xyz",
    parent_origin="https://example.com",
)
print(ok.valid)
```

Returns: `ValidateEmbeddedCheckoutSessionResponse`. **Sends no API key**
— authenticates via `client_secret`. Use server-side only when proxying
the iframe call.

### `confirm` (client-side) [#confirm-client-side]

```python
result = client.embedded_checkout.confirm(
    client_secret="ecs_secret_xyz",
    payment_method={"type": "PAYMENT_CARD", "token_id": "tok_abc"},
    idempotency_key="confirm-ecs_123-1",
)
```

Returns the raw confirmation payload (`dict`). Same authentication
note as `validate`.

### `get_config` [#get_config]

```python
config = client.embedded_checkout.get_config()
print(config.allowed_origins)
```

Returns: `EmbeddedCheckoutConfig`.

### `update_config` [#update_config]

```python
config = client.embedded_checkout.update_config(
    allowed_origins=["https://example.com", "https://staging.example.com"],
    idempotency_key="ecs-config-2025-01-01",
)
```

Returns the updated `EmbeddedCheckoutConfig`.

## Object shape [#object-shape]

`EmbeddedCheckoutSession`:

| Field                      | Type          |
| -------------------------- | ------------- |
| `id`                       | `str`         |
| `client_secret`            | `str \| None` |
| `status`                   | `str \| None` |
| `expires_at`               | `str \| None` |
| `return_url`               | `str \| None` |
| `created_at`, `updated_at` | `str \| None` |

`EmbeddedCheckoutSessionStatus`: `id`, `status`, `payment_status`.

`CryptoPaymentStatus`: `status`, `tx_signature`, `payment_address`,
`chain`, `asset`, `amount` — all `str | None`.

`EmbeddedCheckoutConfig`: `allowed_origins`, `updated_at`.

## Examples [#examples]

### Server endpoint that mints a session for the browser [#server-endpoint-that-mints-a-session-for-the-browser]

```python
@app.post("/api/checkout/session")
def create_checkout_session(request):
    cart = build_cart_from(request.user)

    session = client.embedded_checkout.create_session(
        items=cart.items,
        return_url=f"https://example.com/checkout/{cart.id}/return",
        idempotency_key=f"ecs-{cart.id}",
    )

    return {"client_secret": session.client_secret}
```

### Poll session status server-side after redirect [#poll-session-status-server-side-after-redirect]

```python
status = client.embedded_checkout.retrieve_session(session_id)
if status.payment_status == "succeeded":
    fulfill(session_id)
```


# Invoices (/docs/sdks/python/resources/invoices)



An `Invoice` is a billed line-item document — produced automatically by
subscription cycles or created ad-hoc for one-off billing. The Python
SDK exposes the full lifecycle: draft, finalize-and-send, pay, remind,
void, plus PDF retrieval.

Namespace: `client.invoices`.

## Methods [#methods]

### `create` [#create]

```python
invoice = client.invoices.create(
    customer_id="cus_123",
    currency="USD",
    collection_method="send_invoice",       # or "charge_automatically"
    items=[
        {"description": "Onboarding", "amount": 50000, "quantity": 1},
    ],
    due_date="2026-06-01T00:00:00Z",
    metadata={"po": "PO-1234"},
    idempotency_key="inv-cus_123-2026-05-onboarding",
)
```

Returns: `Invoice`.

### `list` [#list]

```python
invoices = client.invoices.list(
    limit=50,
    offset=0,
    status="open",
    collection_method="send_invoice",
    due_date_from="2026-05-01T00:00:00Z",
    due_date_to="2026-06-01T00:00:00Z",
)
```

Returns `list[Invoice]`. All filter args are optional.

### `retrieve` [#retrieve]

```python
invoice = client.invoices.retrieve("inv_123")
```

### `update` [#update]

```python
invoice = client.invoices.update(
    "inv_123",
    description="Updated description",
    metadata={"po": "PO-5678"},
)
```

### `send_invoice` [#send_invoice]

```python
invoice = client.invoices.send_invoice("inv_123")
```

Sends the invoice email. Named `send_invoice` (not `send`) to avoid
the coroutine / `socket.send` association in Python.

### `pay` [#pay]

```python
invoice = client.invoices.pay(
    "inv_123",
    payment_instrument_id="pi_abc",        # optional override
    idempotency_key="pay-inv_123-1",
)
```

Charges the invoice immediately. With `collection_method="charge_automatically"`
the API runs this on its own at the due date.

### `remind` [#remind]

```python
client.invoices.remind("inv_123")
```

Sends a reminder email for an overdue invoice.

### `void` [#void]

```python
client.invoices.void("inv_123")
```

Cancels the invoice. Use this instead of deleting; deletion isn't
exposed for audit reasons.

### `pdf_data` [#pdf_data]

```python
pdf = client.invoices.pdf_data("inv_123")
# pdf is the raw `data` payload from the API — typically a hosted URL.
```

## Object shape [#object-shape]

`Invoice`:

| Field                                             | Notes                                                       |
| ------------------------------------------------- | ----------------------------------------------------------- |
| `id`                                              | Always present.                                             |
| `status`                                          | `"draft"`, `"open"`, `"paid"`, `"void"`, `"uncollectible"`. |
| `customer_id`, `subscription_id`                  | Parent linkage.                                             |
| `collection_method`                               | `"send_invoice"` or `"charge_automatically"`.               |
| `currency`                                        | Three-letter ISO.                                           |
| `amount_due` / `amount_paid` / `amount_remaining` | Integer cents.                                              |
| `subtotal` / `total`                              | Integer cents.                                              |
| `items`                                           | List of line-item dicts.                                    |
| `custom_fields`, `tax_ids`                        | Display + tax metadata.                                     |
| `due_date`                                        | ISO-8601.                                                   |
| `period_start` / `period_end`                     | Subscription billing window if applicable.                  |
| `description`, `metadata`                         | Free-form.                                                  |
| `hosted_invoice_url`, `invoice_pdf_url`           | Public URLs for the hosted view + PDF.                      |
| `created_at`, `updated_at`                        | Standard.                                                   |

## Examples [#examples]

### Manual invoicing — create, finalize, and email [#manual-invoicing--create-finalize-and-email]

```python
inv = client.invoices.create(
    customer_id="cus_123",
    currency="USD",
    collection_method="send_invoice",
    items=[{"description": "Consulting", "amount": 250000, "quantity": 1}],
    due_date="2026-06-01T00:00:00Z",
    idempotency_key="inv-consult-2026-06",
)
client.invoices.send_invoice(inv.id)
```

### Pay an invoice immediately with a saved card [#pay-an-invoice-immediately-with-a-saved-card]

```python
client.invoices.pay(
    "inv_123",
    payment_instrument_id="pi_abc",
    idempotency_key="pay-inv_123-attempt-1",
)
```

### Nightly chase job [#nightly-chase-job]

```python
overdue = client.invoices.list(
    status="open",
    due_date_to="2026-05-01T00:00:00Z",
)
for inv in overdue:
    client.invoices.remind(inv.id)
```


# Orders (/docs/sdks/python/resources/orders)



An `Order` is the line-item record produced by checkout. It groups one
or more priced items into a single transaction so you can render
receipts, attach metadata, and reconcile against transfers.

Namespace: `client.orders`. Orders are created automatically by checkout
flows; the SDK exposes read endpoints plus a tag-only update.

## Methods [#methods]

### `retrieve` [#retrieve]

```python
order = client.orders.retrieve("ord_123")
```

### `list` [#list]

```python
orders = client.orders.list(limit=50, offset=0)
batch  = client.orders.list(ids=["ord_1", "ord_2"])
```

Returns `list[Order]`. See [Pagination](../pagination).

### `update_tags` [#update_tags]

```python
order = client.orders.update_tags(
    "ord_123",
    tags={"reconciled": True, "warehouse": "us-east"},
)
```

PATCHes only the `tags` map — the rest of the order is immutable from
the API.

## Object shape [#object-shape]

`Order` mirrors the API's order document. The most-used fields:

| Field                      | Notes                                          |
| -------------------------- | ---------------------------------------------- |
| `id`                       | Always present.                                |
| `customer_id`              | The customer who placed the order.             |
| `items`                    | Line items (`price_id`, `quantity`, etc.).     |
| `total` / `subtotal`       | Integer amounts in the smallest currency unit. |
| `currency`                 | Three-letter ISO code.                         |
| `tags`                     | Free-form metadata; mutable via `update_tags`. |
| `created_at`, `updated_at` | ISO-8601 timestamps.                           |

`EasyModel` allows extras, so any new server fields appear on the
object even before the SDK ships explicit annotations for them.

## Examples [#examples]

### Look up the order behind a checkout session [#look-up-the-order-behind-a-checkout-session]

```python
session = client.embedded_checkout.retrieve_session("ecs_123")
# (`session.payment_status` and other status fields drive UI here)
```

### Tag and walk recent orders [#tag-and-walk-recent-orders]

```python
PAGE = 100
offset = 0
while True:
    page = client.orders.list(limit=PAGE, offset=offset)
    if not page:
        break
    for o in page:
        client.orders.update_tags(o.id, tags={"synced": True})
    if len(page) < PAGE:
        break
    offset += PAGE
```


# Payment Instruments (/docs/sdks/python/resources/payment-instruments)



A `PaymentInstrument` is a saved payment method (card or bank account)
attached to a customer. The SDK surfaces the two server-side mutation
endpoints; reads come through `client.customers.payment_instruments(...)`.

Namespace: `client.payment_instruments`.

> Cards must be tokenized client-side first (via Basis Theory) — the
> server only ever receives the resulting `token_id`. The tokenization
> step happens in the browser, not in the Python SDK.

## Methods [#methods]

### `create` [#create]

```python
instrument = client.payment_instruments.create(
    type="PAYMENT_CARD",                   # or "BANK_ACCOUNT"
    name="Ada Lovelace",
    identity_id="ident_123",
    token_id="tok_abc",                    # required
    address={
        "line1": "1 Babbage St",
        "city": "London",
        "country": "GB",
    },
    idempotency_key="inst-ada-2025-01-01",
)
```

Returns: `FinixPaymentInstrument`. Pass `type="BANK_ACCOUNT"` for ACH
instead, with `account_type="checking"` (or `"savings"`) and an
`attempt_bank_account_validation_check=True/False`. Any extra keyword
arguments are forwarded as-is to the API.

`token_id` is required — the SDK raises `ValueError` if you pass an
empty string.

### `update` [#update]

```python
instrument = client.payment_instruments.update(
    "pi_123",
    enabled=False,
    tags={"deprecated": True},
)
```

PATCHes any combination of writable fields. Returns the updated
`PaymentInstrument`.

## Object shape [#object-shape]

`PaymentInstrument` (returned by reads):

| Field                                                | Type                     |
| ---------------------------------------------------- | ------------------------ |
| `id`                                                 | `str`                    |
| `identity_id`                                        | `str \| None`            |
| `type`                                               | `str \| None`            |
| `enabled`                                            | `bool \| None`           |
| `currency`                                           | `str \| None`            |
| `last_four`                                          | `str \| None`            |
| `brand` / `card_type`                                | `str \| None`            |
| `expiration_month` / `expiration_year`               | `int \| None`            |
| `bank_code`, `masked_account_number`, `account_type` | `str \| None`            |
| `name`, `fingerprint`                                | `str \| None`            |
| `address`, `tags`                                    | `dict[str, Any] \| None` |
| `created_at`, `updated_at`                           | `str \| None`            |

`FinixPaymentInstrument` (returned by `create`) includes processor-
specific fields like `bin`, `issuer_country`, and `address_verification`.

## Examples [#examples]

### Save a card and immediately charge it [#save-a-card-and-immediately-charge-it]

```python
inst = client.payment_instruments.create(
    type="PAYMENT_CARD",
    name="Ada Lovelace",
    identity_id="ident_123",
    token_id="tok_abc",
)

transfer = client.transfers.create(
    amount=2500,
    currency="USD",
    source=inst.id,
    idempotency_key=f"order-{order_id}",
)
```

### Disable a card without deleting it [#disable-a-card-without-deleting-it]

```python
client.payment_instruments.update("pi_123", enabled=False)
```


# Payment Links (/docs/sdks/python/resources/payment-links)



Payment links are pre-configured, hosted checkout URLs you can share
over email, chat, or social — useful when you don't want to build a
checkout UI yourself. Each link can charge once or be reused, optionally
capped by `payment_limit`.

Namespace: `client.payment_links`.

## Methods [#methods]

### `create` [#create]

```python
link = client.payment_links.create(
    items=[{"price_id": "price_abc", "quantity": 1}],
    payment_limit=1,
    branding_overrides={"primary_color": "#0a84ff"},
    tags={"campaign": "newsletter-jan"},
    idempotency_key="link-newsletter-jan",
)
print(link.id)              # use this id to look up the full link
```

Returns: `CreatePaymentLinkResponse` (just `{ id }`). All other fields
are accepted via `**kwargs`.

### `list` [#list]

```python
links = client.payment_links.list(limit=50, offset=0)
```

Returns `list[PaymentLink]`.

### `retrieve` [#retrieve]

```python
link = client.payment_links.retrieve("plink_123")
```

### `update` [#update]

```python
link = client.payment_links.update(
    "plink_123",
    payment_limit=10,
    branding_overrides={"primary_color": "#ff3b30"},
)
```

### `delete` [#delete]

```python
client.payment_links.delete("plink_123")
```

Returns `None` (HTTP 204).

### `list_payments` [#list_payments]

```python
payments = client.payment_links.list_payments("plink_123", limit=50)
```

Returns the raw `data` payload (a list of payment / transfer objects)
as a `dict` — passed through verbatim from the API.

## Object shape [#object-shape]

`PaymentLink`:

| Field                | Type                     |
| -------------------- | ------------------------ |
| `id`                 | `str`                    |
| `state`              | `str \| None`            |
| `payment_count`      | `int \| None`            |
| `payment_limit`      | `int \| None`            |
| `branding_overrides` | `dict[str, Any] \| None` |
| `tags`               | `dict[str, Any] \| None` |
| `created_at`         | `str \| None`            |
| `updated_at`         | `str \| None`            |

## Examples [#examples]

### Single-use checkout link [#single-use-checkout-link]

```python
link = client.payment_links.create(
    items=[{"price_id": "price_abc", "quantity": 1}],
    payment_limit=1,
)
share_url = f"https://pay.itseasy.co/{link.id}"
send_invoice_email(customer_email, url=share_url)
```

### Reusable promo link, then audit later [#reusable-promo-link-then-audit-later]

```python
link = client.payment_links.create(
    items=[{"price_id": "price_promo", "quantity": 1}],
    tags={"promo": "spring-2026"},
)

# Later — pull every payment that used it
payments = client.payment_links.list_payments(link.id, limit=200)
```

### Disable a link without deleting it [#disable-a-link-without-deleting-it]

```python
client.payment_links.update("plink_123", payment_limit=0)
```


# Products & pricing (/docs/sdks/python/resources/products-pricing)



Products and prices are the catalog you charge against. A `Product` is
the thing you sell ("Pro plan", "Widget"); a `ProductPrice` is the
amount + cadence ("$10/month", "$0.10 per unit usage"). Subscriptions
and checkouts both reference prices by ID.

Two namespaces:

* `client.products` — the product catalog.
* `client.product_prices` — prices attached to products.

## `client.products` [#clientproducts]

### `create` [#create]

```python
product = client.products.create(
    name="Pro plan",
    description="Everything in Free, plus priority support.",
    metadata={"tier": "pro"},
    idempotency_key="product-pro-2025-01-01",
)
```

All fields are accepted via `**kwargs`. Returns: `Product`.

### `update` [#update]

```python
product = client.products.update("prod_123", description="…")
```

### `retrieve` [#retrieve]

```python
product = client.products.retrieve("prod_123")
```

### `list` [#list]

```python
products = client.products.list(limit=50, offset=0)
batch    = client.products.list(ids=["prod_1", "prod_2"])
```

Returns `list[Product]`.

### `archive` [#archive]

```python
client.products.archive("prod_123")
```

Soft-deletes the product. Existing subscriptions on its prices keep
running; you can no longer create new ones.

### `with_prices` [#with_prices]

```python
bundle = client.products.with_prices("prod_123")
# bundle is a dict with the product + its prices joined
```

### `with_price` [#with_price]

```python
bundle = client.products.with_price("prod_123", "price_abc")
```

## `client.product_prices` [#clientproduct_prices]

### `create` [#create-1]

```python
# One-time price
one_time = client.product_prices.create(
    product_id="prod_123",
    currency="USD",
    unit_amount=2500,
    recurring=False,
    idempotency_key="price-onetime-prod_123",
)

# Recurring price
monthly = client.product_prices.create(
    product_id="prod_123",
    currency="USD",
    unit_amount=1000,
    recurring=True,
    interval="month",
    interval_count=1,
    idempotency_key="price-monthly-prod_123",
)
```

The discriminated union (`recurring=True/False`) is enforced server-
side. Returns: `ProductPrice`.

### `update` [#update-1]

```python
price = client.product_prices.update("price_abc", metadata={"legacy": True})
```

### `retrieve` [#retrieve-1]

```python
price = client.product_prices.retrieve("price_abc")
```

### `list` [#list-1]

```python
prices = client.product_prices.list(limit=50)
```

### `archive` [#archive-1]

```python
client.product_prices.archive("price_abc")
```

## Object shape [#object-shape]

`Product` and `ProductPrice` follow the canonical shape from the
[API reference](https://docs.itseasy.co/api). `EasyModel` allows
extras, so new fields appear on the model automatically.

Common fields:

| Type           | Field                                             | Notes             |
| -------------- | ------------------------------------------------- | ----------------- |
| `Product`      | `id`, `name`, `description`, `active`, `metadata` |                   |
| `ProductPrice` | `id`, `product_id`, `currency`, `unit_amount`     | Integer cents.    |
| `ProductPrice` | `recurring`, `interval`, `interval_count`         | Recurring config. |

## Examples [#examples]

### Bootstrap a SaaS plan (product + monthly price) [#bootstrap-a-saas-plan-product--monthly-price]

```python
product = client.products.create(name="Pro", description="Pro tier")
price = client.product_prices.create(
    product_id=product.id,
    currency="USD",
    unit_amount=2900,
    recurring=True,
    interval="month",
    interval_count=1,
)
print(price.id)
```

### Rotate a price (archive old, create new) [#rotate-a-price-archive-old-create-new]

```python
client.product_prices.archive("price_old")
new_price = client.product_prices.create(
    product_id="prod_123",
    currency="USD",
    unit_amount=3500,
    recurring=True,
    interval="month",
    interval_count=1,
)
```

### Render a product page [#render-a-product-page]

```python
bundle = client.products.with_prices("prod_123")
print(bundle["name"])
for p in bundle.get("prices", []):
    print(p["id"], p["unit_amount"], p.get("interval"))
```


# Promotion Codes (/docs/sdks/python/resources/promotion-codes)



A `PromotionCode` is a customer-facing code (`SUMMER2026`) that wraps a
[Coupon](./coupons). Use coupons to model the discount; use promotion
codes to expose it to end users with code strings, expiry dates,
minimum order amounts, and redemption caps.

Namespace: `client.promotion_codes`.

## Methods [#methods]

### `create` [#create]

```python
promo = client.promotion_codes.create(
    code="SUMMER2026",
    coupon_id="cou_25_off",
    max_redemptions=500,
    expires_at="2026-09-01T00:00:00Z",
    minimum_amount=2000,
    minimum_amount_currency="USD",
    first_time_transaction=True,
    idempotency_key="promo-summer2026",
)
```

Returns: `PromotionCode`. `coupon_id` is required.

### `list` [#list]

```python
codes = client.promotion_codes.list(limit=50)
```

### `retrieve` [#retrieve]

```python
promo = client.promotion_codes.retrieve("promo_123")
```

### `update` [#update]

```python
promo = client.promotion_codes.update("promo_123", active=False)
```

### `delete` [#delete]

```python
client.promotion_codes.delete("promo_123")
```

### `validate` [#validate]

```python
result = client.promotion_codes.validate(
    code="SUMMER2026",
    customer_id="cus_123",
    items=[{"price_id": "price_monthly", "quantity": 1}],
)

if result.valid:
    show_discount(result.discount_preview)
else:
    show_error(result.reason)
```

Returns: `ValidatePromotionCodeResponse` (`valid`, `promotion_code`,
`coupon`, `discount_preview`, `reason`). Use this on your checkout's
"Apply code" button before confirming the order.

## Object shape [#object-shape]

`PromotionCode`:

| Field                                        | Type                                  |
| -------------------------------------------- | ------------------------------------- |
| `id`                                         | `str`                                 |
| `code`                                       | `str \| None`                         |
| `coupon_id`                                  | `str \| None`                         |
| `active`                                     | `bool \| None`                        |
| `max_redemptions`                            | `int \| None`                         |
| `times_redeemed`                             | `int \| None`                         |
| `expires_at`                                 | `str \| None`                         |
| `customer_id`                                | `str \| None` (single-customer codes) |
| `minimum_amount` / `minimum_amount_currency` | `int \| None` / `str \| None`         |
| `first_time_transaction`                     | `bool \| None`                        |
| `metadata`, `created_at`, `updated_at`       | Standard.                             |

`ValidatePromotionCodeResponse`:

| Field              | Type                     |
| ------------------ | ------------------------ |
| `valid`            | `bool`                   |
| `promotion_code`   | `PromotionCode \| None`  |
| `coupon`           | `dict[str, Any] \| None` |
| `discount_preview` | `dict[str, Any] \| None` |
| `reason`           | `str \| None`            |

## Examples [#examples]

### Self-service "apply code" handler [#self-service-apply-code-handler]

```python
@app.post("/api/cart/apply-code")
def apply_code(request):
    result = client.promotion_codes.validate(
        code=request.json["code"],
        customer_id=request.user.easy_customer_id,
        items=request.session["cart_items"],
    )
    return {
        "valid": result.valid,
        "preview": result.discount_preview,
        "reason": result.reason,
    }
```

### Apply the validated code to a subscription [#apply-the-validated-code-to-a-subscription]

```python
client.subscriptions.apply_discount(
    sub_id,
    promotion_code="SUMMER2026",
)
```

### Disable a code without deleting it [#disable-a-code-without-deleting-it]

```python
client.promotion_codes.update("promo_123", active=False)
```


# Refunds (/docs/sdks/python/resources/refunds)



Refunds are reversals on an existing transfer. The Python SDK does not
expose a top-level `client.refunds` namespace — refunds live on the
[Transfers](./transfers) resource as `client.transfers.create_refund(...)`.

> No standalone `client.refunds.*` namespace ships in `0.1.x`.
>
> {/* TODO: Add a top-level `client.refunds` namespace (list / retrieve)
>   when the API exposes a queryable refund resource. */}

## Methods [#methods]

### `create_refund` (on `transfers`) [#create_refund-on-transfers]

```python
reversal = client.transfers.create_refund(
    "tr_123",
    refund_amount=500,                     # cents; partial allowed
    tags={"reason": "broken_widget"},
    idempotency_key="refund-tr_123-1",
)
```

Returns the reversal as a `Transfer` object (the API models reversals
as transfers in the opposite direction). Pass `refund_amount` equal to
the original transfer's `amount` for a full refund.

## Object shape [#object-shape]

The reversal is a `Transfer` — see [Transfers](./transfers#object-shape)
for the field list.

The most relevant fields on a reversal:

| Field                              | Notes                                          |
| ---------------------------------- | ---------------------------------------------- |
| `id`                               | The reversal's own ID.                         |
| `type`                             | Distinguishes reversal vs. original transfer.  |
| `state`                            | `"PENDING"`, `"SUCCEEDED"`, `"FAILED"`.        |
| `amount`                           | The refunded amount (positive integer, cents). |
| `failure_code` / `failure_message` | Populated if the reversal fails.               |

## Examples [#examples]

### Full refund on a transfer [#full-refund-on-a-transfer]

```python
original = client.transfers.retrieve("tr_123")
reversal = client.transfers.create_refund(
    original.id,
    refund_amount=original.amount,
    idempotency_key=f"refund-{original.id}-full",
)
assert reversal.state in {"PENDING", "SUCCEEDED"}
```

### Partial refund with a reason tag [#partial-refund-with-a-reason-tag]

```python
client.transfers.create_refund(
    "tr_123",
    refund_amount=500,
    tags={"reason": "shipping_damage", "ticket": "SUP-4421"},
    idempotency_key="refund-tr_123-shipping",
)
```

### Idempotent refund from a webhook handler [#idempotent-refund-from-a-webhook-handler]

```python
def on_dispute_won(event):
    dispute = event.data
    client.transfers.create_refund(
        dispute["transfer_id"],
        refund_amount=dispute["amount"],
        idempotency_key=f"refund-dispute-{dispute['id']}",
    )
```


# Settlements (/docs/sdks/python/resources/settlements)



A `Settlement` is a batched payout — the rolled-up record of transfers
the processor has paid out (or will pay out) to your bank account. Use
this resource to reconcile your books against actual deposits.

Namespace: `client.settlements`.

## Methods [#methods]

### `retrieve` [#retrieve]

```python
settlement = client.settlements.retrieve("stl_123")
```

### `list` [#list]

```python
settlements = client.settlements.list(limit=50, offset=0)
batch = client.settlements.list(ids=["stl_1", "stl_2"])
```

Returns `list[Settlement]`. See [Pagination](../pagination).

### `close` [#close]

```python
settlement = client.settlements.close(
    "stl_123",
    idempotency_key="close-stl_123",
)
```

PATCHes the settlement to a closed state. Use when finalizing a manual
settlement run.

## Object shape [#object-shape]

`Settlement` follows the canonical API shape. Common fields:

| Field                      | Notes                                     |
| -------------------------- | ----------------------------------------- |
| `id`                       | Always present.                           |
| `state`                    | `"PENDING"`, `"APPROVED"`, `"PAID"`, etc. |
| `amount`                   | Integer in the smallest currency unit.    |
| `currency`                 | Three-letter ISO.                         |
| `created_at`, `updated_at` | ISO-8601 timestamps.                      |

`EasyModel` allows extras, so any additional fields the API returns
(processor identifiers, batch counts, etc.) come through on the model.

## Examples [#examples]

### Reconcile against your accounting ledger [#reconcile-against-your-accounting-ledger]

```python
batch = client.settlements.list(limit=100)
for s in batch:
    record_settlement_in_ledger(
        external_id=s.id,
        state=s.state,
        amount=s.amount,
        currency=s.currency,
    )
```

### Close a settlement after manual review [#close-a-settlement-after-manual-review]

```python
client.settlements.close("stl_123", idempotency_key="close-stl_123-final")
```


# Subscriptions (/docs/sdks/python/resources/subscriptions)



Subscriptions bill a customer on a cadence — monthly, annual, usage-
based, or any combination. The Python SDK exposes the full lifecycle:
create, pause, resume, change items, apply discounts, report usage, and
cancel.

Namespace: `client.subscriptions`. The list of methods is large because
the resource models a real-world billing system; the
[Subscription System](../examples/subscription-system) example shows
how the pieces fit together.

## Core CRUD [#core-crud]

### `create` [#create]

```python
sub = client.subscriptions.create(
    identity_id="ident_123",
    items=[{"price_id": "price_monthly", "quantity": 1}],
    payment_instrument_id="pi_abc",
    idempotency_key="sub-ident_123-2025-01-01",
)
```

Returns: `Subscription`. All fields go through `**kwargs`.

### `retrieve` [#retrieve]

```python
sub = client.subscriptions.retrieve("sub_123")
```

### `update` [#update]

```python
sub = client.subscriptions.update(
    "sub_123",
    proration_behavior="create_prorations",
    metadata={"upgraded": True},
)
```

### `list` [#list]

```python
subs = client.subscriptions.list(limit=50, offset=0)
```

For per-customer lists, use
`client.customers.subscriptions(customer_id, status="active", ...)` —
that endpoint returns a paginated envelope (see
[Pagination](../pagination)).

### `cancel` [#cancel]

```python
# Cancel immediately
client.subscriptions.cancel("sub_123")

# Cancel at the end of the current billing period
client.subscriptions.cancel("sub_123", at_period_end=True)
```

## Pause, resume, preview [#pause-resume-preview]

### `pause` [#pause]

```python
client.subscriptions.pause(
    "sub_123",
    behavior="mark_uncollectible",         # or "keep_as_draft" / "void"
    resumes_at="2026-06-01T00:00:00Z",
)
```

### `resume` [#resume]

```python
client.subscriptions.resume("sub_123")
```

### `proration_preview` [#proration_preview]

```python
preview = client.subscriptions.proration_preview(
    "sub_123",
    items=[{"price_id": "price_pro", "quantity": 1}],
    remove_items=["si_old"],
    proration_date="2026-05-01T00:00:00Z",
)
```

Returns a `dict` with the calculated proration line items. Useful for
showing a "you'll be charged $X today" confirmation before applying
the change.

## Items [#items]

### `add_item` [#add_item]

```python
item = client.subscriptions.add_item(
    "sub_123",
    price_id="price_addon_seats",
    quantity=5,
)
```

### `update_item` [#update_item]

```python
item = client.subscriptions.update_item("sub_123", "si_456", quantity=10)
```

### `remove_item` [#remove_item]

```python
client.subscriptions.remove_item("sub_123", "si_456")
```

## Discounts [#discounts]

### `apply_discount` [#apply_discount]

```python
discount = client.subscriptions.apply_discount(
    "sub_123",
    coupon_id="cou_25_off",                # XOR with promotion_code
    subscription_item_id="si_456",         # optional scope
)

# Or via promotion code
discount = client.subscriptions.apply_discount(
    "sub_123",
    promotion_code="SUMMER2026",
)
```

Pass exactly one of `coupon_id` or `promotion_code`. Returns:
`SubscriptionDiscount`.

### `list_discounts` [#list_discounts]

```python
discounts = client.subscriptions.list_discounts("sub_123")
```

### `remove_discount` [#remove_discount]

```python
client.subscriptions.remove_discount("sub_123", "sd_789")
```

## One-time charges & usage [#one-time-charges--usage]

### `create_one_time_charge` [#create_one_time_charge]

```python
charge = client.subscriptions.create_one_time_charge(
    "sub_123",
    amount=500,
    currency="USD",
    description="Setup fee",
    idempotency_key="otc-sub_123-setup",
)
```

Adds a one-off line item to the subscription's next invoice. Returns
the raw `data` dict.

### `report_usage` [#report_usage]

```python
client.subscriptions.report_usage(
    "sub_123",
    subscription_item_id="si_metered",
    quantity=42,
    timestamp="2026-05-01T12:00:00Z",
    action="increment",                    # or "set"
    idempotency_key="usage-sub_123-2026-05-01-12",
)
```

### `usage_summary` [#usage_summary]

```python
summary = client.subscriptions.usage_summary(
    "sub_123",
    subscription_item_id="si_metered",
    from_="2026-05-01T00:00:00Z",
    to="2026-06-01T00:00:00Z",
)
```

> The keyword is `from_` (with trailing underscore) because `from` is
> a Python reserved word; the SDK rewrites it to `from` on the wire.

### `usage_reconciliation` [#usage_reconciliation]

```python
recon = client.subscriptions.usage_reconciliation(
    "sub_123",
    period_start="2026-05-01T00:00:00Z",
    period_end="2026-06-01T00:00:00Z",
)
```

## Object shape [#object-shape]

`Subscription`:

| Field                                         | Notes                                          |
| --------------------------------------------- | ---------------------------------------------- |
| `id`                                          | Always present.                                |
| `identity_id`                                 | The customer.                                  |
| `status`                                      | `"trialing"`, `"active"`, `"past_due"`, etc.   |
| `items`                                       | `list[SubscriptionItem] \| None`               |
| `current_period_start` / `current_period_end` | ISO-8601.                                      |
| `cancel_at_period_end`                        | `bool \| None`                                 |
| `pause_collection`                            | `dict \| None`                                 |
| `latest_invoice_id`                           | The invoice driving the current billing cycle. |
| `pending_update`                              | Scheduled changes not yet applied.             |
| `trial_end`                                   | ISO-8601 if in trial.                          |
| `metadata`, `created_at`, `updated_at`        | Standard.                                      |

Related models: `SubscriptionItem` (`id`, `price_id`, `quantity`),
`SubscriptionDiscount` (`id`, `coupon_id` or `promotion_code_id`,
`start`, `end`), `SubscriptionPlan` (legacy Finix engine).

## Examples [#examples]

See the [Subscription System](../examples/subscription-system) recipe
for an end-to-end walkthrough — checkout → create → upgrade with
proration → cancel at period end.


# Transfers (/docs/sdks/python/resources/transfers)



A `Transfer` is the SDK's term for a money movement — a charge against a
saved payment instrument. Refunds are reversals on a transfer and live
on this same resource (see [Refunds](./refunds) for the recipe).

Namespace: `client.transfers`.

> Amounts are integers in the smallest currency unit (e.g. cents for
> USD). `amount=2500` + `currency="USD"` charges $25.00.

## Methods [#methods]

### `create` [#create]

```python
transfer = client.transfers.create(
    amount=2500,
    currency="USD",
    source="pi_abc",                       # payment instrument id
    tags={"order_id": "ord_123"},
    idempotency_key=f"charge-ord_123",
)
```

Returns: `Transfer`.

### `update` [#update]

```python
transfer = client.transfers.update(
    "tr_123",
    tags={"reconciled": True},
)
```

PATCHes any combination of writable fields (typically `tags`).

### `retrieve` [#retrieve]

```python
transfer = client.transfers.retrieve("tr_123")
```

### `list` [#list]

```python
recent = client.transfers.list(limit=50)
batch  = client.transfers.list(ids=["tr_1", "tr_2"])
```

Returns `list[Transfer]`. See [Pagination](../pagination).

### `create_refund` [#create_refund]

```python
reversal = client.transfers.create_refund(
    "tr_123",
    refund_amount=500,                     # partial — leave full transfer for $20
    tags={"reason": "broken_widget"},
    idempotency_key="refund-tr_123-1",
)
```

Returns the reversal as a `Transfer` object. Pass `refund_amount` equal
to `transfer.amount` for a full refund. See the dedicated
[Refunds](./refunds) page for the full pattern.

## Object shape [#object-shape]

`Transfer`:

| Field              | Type                     |
| ------------------ | ------------------------ |
| `id`               | `str`                    |
| `type`             | `str \| None`            |
| `state`            | `str \| None`            |
| `amount`           | `int \| None`            |
| `amount_requested` | `int \| None`            |
| `currency`         | `str \| None`            |
| `source`           | `str \| None`            |
| `destination`      | `str \| None`            |
| `fee`              | `int \| None`            |
| `failure_code`     | `str \| None`            |
| `failure_message`  | `str \| None`            |
| `tags`             | `dict[str, Any] \| None` |
| `created_at`       | `str \| None`            |
| `updated_at`       | `str \| None`            |

## Examples [#examples]

### Idempotent charge per order [#idempotent-charge-per-order]

```python
import uuid

def charge_order(order):
    return client.transfers.create(
        amount=order.total_cents,
        currency=order.currency,
        source=order.payment_instrument_id,
        tags={"order_id": order.id},
        idempotency_key=f"order-{order.id}-charge",
    )
```

### Pull the most recent transfers for reconciliation [#pull-the-most-recent-transfers-for-reconciliation]

```python
transfers = client.transfers.list(limit=100)
for t in transfers:
    if t.state == "FAILED":
        log.warning("failed: %s — %s", t.id, t.failure_message)
```


# Treasury (/docs/sdks/python/resources/treasury)



Treasury is the platform's money-movement layer for the *operator's*
funds — bank-linking, recipients, transfers, withdrawals, payout
links, recurring payouts, and approval/security rules. The Python SDK
exposes the full surface as flat methods on `client.treasury`.

Namespace: `client.treasury`. The method names are deliberately
verbose (`list_recipient_payment_methods`, `create_security_rule`) so
the resource works without nested classes — see the [client.treasury
source](https://github.com/itseasyco/easy-sdk-python/blob/main/src/easylabs/resources/treasury.py)
for the canonical list.

## Bank accounts [#bank-accounts]

```python
# List linked bank accounts
accounts = client.treasury.list_bank_accounts(limit=50, offset=0)

# Plaid Link token for the dashboard / app
link_token = client.treasury.get_bank_link_token()

# Link a bank account after Plaid Link succeeds
client.treasury.link_bank_account(
    plaid_public_token="public-sandbox-…",
    plaid_account_id="acc_…",
    idempotency_key="bank-link-2026-05-01",
)

# Deactivate
client.treasury.delete_bank_account("ba_123")
```

## Categories [#categories]

```python
categories = client.treasury.list_categories(limit=50)
custom = client.treasury.create_category(
    name="Marketing",
    color="#0a84ff",
    idempotency_key="cat-marketing",
)
client.treasury.delete_category(custom.id)
usage = client.treasury.get_category_usage(custom.id)
```

## Dashboard & deposits [#dashboard--deposits]

```python
summary = client.treasury.get_dashboard_summary()
wire    = client.treasury.get_wire_instructions()

# Pull funds from a linked bank (ACH)
client.treasury.bank_pull(
    bank_account_id="ba_123",
    amount=100000,
    idempotency_key="pull-2026-05-01",
)
```

## Recipients [#recipients]

```python
recipients = client.treasury.list_recipients(limit=50)
recipient = client.treasury.retrieve_recipient("rec_123")

new = client.treasury.create_recipient(
    name="Vendor LLC",
    email="vendor@example.com",
    payment_methods=[{
        "type": "BANK_ACCOUNT",
        "routing_number": "...",
        "account_number": "...",
        "account_type": "checking",
    }],
    idempotency_key="recipient-vendor-llc",
)

client.treasury.update_recipient(new.id, notes="Net-30")
client.treasury.delete_recipient(new.id)

# Payment methods (sub-resource)
client.treasury.add_recipient_payment_method(
    new.id, type="BANK_ACCOUNT", routing_number="...", account_number="...",
)

# Self-service flows
client.treasury.invite_recipient(new.id)
client.treasury.request_recipient_w9(new.id)

# Auto-pay schedule
client.treasury.create_recipient_auto_pay(
    new.id, amount=100000, schedule="monthly_first",
)

# Tax info
tax = client.treasury.get_recipient_tax_info(new.id)
client.treasury.set_recipient_tax_info(new.id, tin="...", classification="LLC")

# Invitations
invites = client.treasury.list_recipient_invitations(limit=50)

# Bulk import (CSV)
with open("recipients.csv", "rb") as f:
    client.treasury.import_recipients(file=f, filename="recipients.csv")

# Tax compliance report
report = client.treasury.get_recipient_tax_report()

# Plaid for recipient self-service
token = client.treasury.get_recipient_plaid_link_token(recipient_id=new.id)
client.treasury.exchange_recipient_plaid_token(
    recipient_id=new.id,
    public_token="public-sandbox-…",
)
```

> `list_recipient_payment_methods(recipient_id)` is exposed for forward
> compatibility but the API has no dedicated GET endpoint today —
> payment methods are returned inline on the recipient object.

## Transactions [#transactions]

```python
# Cursor-based pagination — pass next_cursor back as cursor=
page = client.treasury.list_transactions(limit=100)
while True:
    for tx in page.get("data", []):
        print(tx["id"], tx["amount"])
    if not page.get("next_cursor"):
        break
    page = client.treasury.list_transactions(limit=100, cursor=page["next_cursor"])

tx = client.treasury.retrieve_transaction("ttx_123")
client.treasury.update_transaction("ttx_123", category_id="cat_marketing")
breakdown = client.treasury.get_transaction_settlement("ttx_123")
csv = client.treasury.export_transactions(start="2026-05-01", end="2026-05-31")
```

## Send / transfer / withdraw [#send--transfer--withdraw]

All three are two-step (initiate, then optional 2FA confirm) and accept
arbitrary fields via `**kwargs`. Each returns a raw `dict`.

```python
# Send money to a recipient
op = client.treasury.send(
    recipient_id="rec_123",
    amount=100000,
    method="ach",
    idempotency_key="send-rec_123-2026-05-01",
)
client.treasury.confirm_send(send_id=op["id"], two_factor_code="123456")
client.treasury.cancel_send(send_id=op["id"])

# Transfer between accounts
client.treasury.transfer(
    from_account="ba_123", to_account="ba_456", amount=50000,
)
client.treasury.confirm_transfer(transfer_id="ttr_123", two_factor_code="123456")

# Withdraw to an external bank
client.treasury.withdraw(
    bank_account_id="ba_123", amount=200000,
    idempotency_key="withdraw-2026-05-01",
)
client.treasury.confirm_withdraw(withdraw_id="tw_123", two_factor_code="123456")
```

## Payout links [#payout-links]

```python
links = client.treasury.list_payout_links(limit=50)
link  = client.treasury.generate_payout_link(amount=50000, currency="USD")

# Public endpoint — no auth needed; suitable for the recipient page
detail = client.treasury.get_payout_link("plk_token")
client.treasury.submit_payout_link(
    "plk_token",
    routing_number="...", account_number="...", account_type="checking",
)
```

## Recurring payments [#recurring-payments]

```python
recurring = client.treasury.list_recurring_payments(limit=50)
rp = client.treasury.retrieve_recurring_payment("trp_123")

new_rp = client.treasury.create_recurring_payment(
    recipient_id="rec_123",
    amount=100000,
    schedule="monthly_first",
    idempotency_key="recurring-vendor-monthly",
)

client.treasury.update_recurring_payment(new_rp.id, status="paused")
client.treasury.delete_recurring_payment(new_rp.id)
```

## Auto-transfer rules [#auto-transfer-rules]

```python
rules = client.treasury.list_auto_transfer_rules(limit=50)

rule = client.treasury.create_auto_transfer_rule(
    threshold=500000,
    target_account_id="ba_savings",
    idempotency_key="atr-overflow-to-savings",
)
client.treasury.update_auto_transfer_rule(rule.id, enabled=False)
client.treasury.delete_auto_transfer_rule(rule.id)
```

## Security rules & approvals [#security-rules--approvals]

```python
rules = client.treasury.list_security_rules(limit=50)

rule = client.treasury.create_security_rule(
    type="approval_required",
    threshold=1000000,
    approvers=["user_admin"],
    idempotency_key="sec-large-tx-approval",
)
client.treasury.update_security_rule(rule.id, threshold=2000000)
client.treasury.delete_security_rule(rule.id)

# Approvals
req = client.treasury.create_approval_request(
    transaction_id="ttx_pending",
    reason="High-value transfer",
)
client.treasury.resolve_approval_request(
    req.id, decision="approve", notes="OK from CFO",
)
```

## Object shapes [#object-shapes]

Treasury models live in `easylabs.models.treasury`:

`TreasuryBankAccount`, `TreasuryCategory`, `TreasuryRecipient`,
`TreasuryTransaction`, `TreasuryPayoutLink`, `TreasuryRecurringPayment`,
`TreasuryAutoTransferRule`, `TreasurySecurityRule`,
`TreasuryApprovalRequest`.

Each is a `pydantic` model on `EasyModel` with `extra="allow"`, so the
typed fields shown in source surface common attributes (`id`, `status`,
`amount`, `created_at`, ...) and the rest comes through dynamically.
The full per-model schema lives in the
[Easy Labs API reference](https://docs.itseasy.co/api).

## Examples [#examples]

### Walk all transactions for a CSV export [#walk-all-transactions-for-a-csv-export]

```python
all_rows = []
cursor = None
while True:
    page = client.treasury.list_transactions(limit=200, cursor=cursor)
    all_rows.extend(page.get("data", []))
    cursor = page.get("next_cursor")
    if not cursor:
        break
```

### Categorize uncategorized transactions [#categorize-uncategorized-transactions]

```python
page = client.treasury.list_transactions(limit=100)
for tx in page.get("data", []):
    if not tx.get("category_id"):
        client.treasury.update_transaction(tx["id"], category_id="cat_uncategorized")
```


# Wallet Checkout (/docs/sdks/python/resources/wallet-checkout)



Coming soon.

The Python SDK does not currently expose a dedicated `client.wallet_checkout`
namespace. Wallet-funded checkouts go through the standard checkout
surfaces today:

* [Checkout](./checkout) — `client.checkout.create(...)` for one-shot,
  server-side flows.
* [Embedded Checkout](./embedded-checkout) — `client.embedded_checkout.*`
  for iframe-rendered flows that can include wallet-based payment
  methods.

The `Wallet` *response model* exists (it's what
`client.customers.wallets(...)` returns) but there is no wallet-
specific checkout entry point in `0.1.x`.

{/* TODO: Document `client.wallet_checkout` once a dedicated namespace
  ships. The current Apple Pay / Google Pay / crypto wallet flows are
  covered by `client.checkout` and `client.embedded_checkout`. */}


# Webhook Endpoints (/docs/sdks/python/resources/webhook-endpoints)



Manage your webhook subscriptions and audit deliveries. The signature
verifier for *receiving* webhooks is documented separately on the
[Webhooks](../webhooks) page.

Namespace: `client.webhooks_management`.

## Methods [#methods]

### `register` [#register]

```python
endpoint = client.webhooks_management.register(
    url="https://example.com/webhooks/easy",
    events=["payment.created", "subscription.updated", "invoice.paid"],
    idempotency_key="webhook-prod-2026-05",
)

# `endpoint.secret` is returned once — store it now; you cannot fetch
# it again.
SECRET = endpoint.secret
```

Returns: `RegisteredWebhookEndpoint`. Pass `events=None` (the default)
to subscribe to every supported event.

### `list` [#list]

```python
endpoints = client.webhooks_management.list()
```

Returns `list[WebhookEndpoint]`. The signing secret is **not** included
on subsequent reads — only on the original `register(...)` response.

### `update` [#update]

```python
endpoint = client.webhooks_management.update(
    "we_123",
    url="https://example.com/webhooks/easy/v2",
    events=["payment.*"],
)
```

### `delete` [#delete]

```python
client.webhooks_management.delete("we_123")
```

### `list_deliveries` [#list_deliveries]

```python
page = client.webhooks_management.list_deliveries(
    event_type="payment.created",
    success=False,
    created_after="2026-05-01T00:00:00Z",
    created_before="2026-05-02T00:00:00Z",
    limit=100,
    offset=0,
    include_counts=True,
)
print(page.get("total"))
for d in page.get("data", []):
    print(d["id"], d["status_code"])
```

Returns the raw paginated `data` payload (`dict`). Use `endpoint_id=`
to scope to a single endpoint, or call `list_endpoint_deliveries` for
the same effect with the endpoint in the URL.

### `list_endpoint_deliveries` [#list_endpoint_deliveries]

```python
page = client.webhooks_management.list_endpoint_deliveries(
    "we_123",
    success=False,
    limit=50,
)
```

## Object shape [#object-shape]

`WebhookEndpoint`:

| Field        | Type                |
| ------------ | ------------------- |
| `id`         | `str`               |
| `url`        | `str \| None`       |
| `status`     | `str \| None`       |
| `events`     | `list[str] \| None` |
| `created_at` | `str \| None`       |
| `updated_at` | `str \| None`       |

`RegisteredWebhookEndpoint` extends the above with `secret: str | None`
— **only populated on creation**.

`WebhookDelivery`:

| Field                         | Type           |
| ----------------------------- | -------------- |
| `id`                          | `str`          |
| `endpoint_id`                 | `str \| None`  |
| `event_type`                  | `str \| None`  |
| `success`                     | `bool \| None` |
| `attempt` / `attempt_number`  | `int \| None`  |
| `status_code`                 | `int \| None`  |
| `response_body`               | `str \| None`  |
| `created_at` / `delivered_at` | `str \| None`  |

## Examples [#examples]

### Bootstrap an endpoint and store the secret [#bootstrap-an-endpoint-and-store-the-secret]

```python
endpoint = client.webhooks_management.register(
    url=f"{PUBLIC_BASE_URL}/webhooks/easy",
    events=["payment.created", "invoice.paid", "subscription.updated"],
    idempotency_key=f"webhook-{ENV}-2026-05",
)

# Persist atomically — losing the secret means re-registering.
secrets_store.put("EASY_WEBHOOK_SECRET", endpoint.secret)
```

### Audit failed deliveries from the last 24 hours [#audit-failed-deliveries-from-the-last-24-hours]

```python
import datetime as dt

since = (dt.datetime.now(dt.timezone.utc) - dt.timedelta(days=1)).isoformat()
page = client.webhooks_management.list_deliveries(
    success=False,
    created_after=since,
    limit=200,
)
for d in page.get("data", []):
    print(d["event_type"], d["status_code"], d["response_body"])
```

### Rotate an endpoint URL [#rotate-an-endpoint-url]

```python
client.webhooks_management.update(
    "we_123",
    url="https://example.com/webhooks/easy/v2",
)
```


# Customer Management (/docs/sdks/react/examples/customer-management)



This recipe builds the data layer for a customer-facing account page: list the signed-in customer's saved payment methods, orders, and subscriptions, then patch their profile in place. Everything runs through `useEasy()` from inside React components — no extra REST plumbing.

## Goal [#goal]

We want a `<CustomerDashboard customerId={...}>` component that:

1. Loads the customer record on mount.
2. Loads payment instruments, orders, and subscriptions in parallel.
3. Renders three tabs (or sections) for each list.
4. Lets the user update name / email and persists with `updateCustomer`.

This mirrors [`examples/next-example/src/app/profile/page.tsx`](https://github.com/itseasyco/easy-sdk/tree/main/examples/next-example/src/app/profile/page.tsx), simplified.

## Implementation [#implementation]

### 1. Create the customer [#1-create-the-customer]

Customers are usually created at signup or at first checkout. For a standalone signup form:

```tsx
const { createCustomer } = useEasy();

const res = await createCustomer({
  first_name: "Ada",
  last_name: "Lovelace",
  email: "ada@example.com",
});
const customerId = res.data.id;
```

Persist `customerId` somewhere your app can read it back — most apps store it on their own user row.

### 2. Load the dashboard data in parallel [#2-load-the-dashboard-data-in-parallel]

```tsx title="src/components/CustomerDashboard.tsx"
"use client";

import {
  useEasy,
  type CustomerData,
  type OrderData,
  type PaymentInstrumentData,
  type SubscriptionData,
} from "@easylabs/react";
import { useEffect, useState } from "react";

type State = {
  customer: CustomerData | null;
  instruments: PaymentInstrumentData[];
  orders: OrderData[];
  subscriptions: SubscriptionData[];
  loading: boolean;
  error: string | null;
};

export function CustomerDashboard({ customerId }: { customerId: string }) {
  const {
    getCustomer,
    getCustomerPaymentInstruments,
    getCustomerOrders,
    getCustomerSubscriptions,
    updateCustomer,
  } = useEasy();

  const [state, setState] = useState<State>({
    customer: null,
    instruments: [],
    orders: [],
    subscriptions: [],
    loading: true,
    error: null,
  });

  useEffect(() => {
    let cancelled = false;
    (async () => {
      try {
        const [customer, instruments, orders, subscriptions] = await Promise.all([
          getCustomer(customerId),
          getCustomerPaymentInstruments(customerId),
          getCustomerOrders(customerId),
          getCustomerSubscriptions(customerId),
        ]);
        if (cancelled) return;
        setState({
          customer: customer.success ? customer.data : null,
          instruments: instruments.success ? instruments.data : [],
          orders: orders.success ? orders.data : [],
          subscriptions: subscriptions.success ? subscriptions.data.data : [],
          loading: false,
          error: customer.success ? null : customer.message,
        });
      } catch (err) {
        if (cancelled) return;
        setState((s) => ({
          ...s,
          loading: false,
          error: err instanceof Error ? err.message : "Failed to load.",
        }));
      }
    })();
    return () => {
      cancelled = true;
    };
  }, [customerId, getCustomer, getCustomerPaymentInstruments, getCustomerOrders, getCustomerSubscriptions]);

  async function saveProfile(patch: Partial<CustomerData>) {
    const res = await updateCustomer(customerId, patch);
    if (res.success) {
      setState((s) => ({ ...s, customer: res.data }));
    }
  }

  if (state.loading) return <p>Loading…</p>;
  if (state.error || !state.customer) return <p>Couldn't load account.</p>;

  return (
    <>
      <ProfileSection customer={state.customer} onSave={saveProfile} />
      <PaymentMethodsSection instruments={state.instruments} />
      <OrdersSection orders={state.orders} />
      <SubscriptionsSection subscriptions={state.subscriptions} />
    </>
  );
}
```

(`ProfileSection`, `PaymentMethodsSection`, etc. are plain presentational components that render the typed records. Use whatever UI kit you prefer.)

### 3. Cancel a subscription [#3-cancel-a-subscription]

Cancellation is a one-liner. Refetch the list afterward (or optimistically update local state).

```tsx
const { cancelSubscription, getCustomerSubscriptions } = useEasy();

async function onCancel(subscriptionId: string) {
  await cancelSubscription(subscriptionId);
  const fresh = await getCustomerSubscriptions(customerId);
  if (fresh.success) setSubscriptions(fresh.data.data);
}
```

## Tradeoffs [#tradeoffs]

* **Client-side fetching.** Everything runs in the browser with the user's session. That's fine for a logged-in dashboard. For SEO-sensitive pages, fetch the same data server-side via `@easylabs/node` and pass it to a client component as props.
* **No built-in pagination.** `getCustomerOrders` and `getCustomerSubscriptions` accept pagination params (`limit`, `cursor`). For long histories, page them — see the [Node SDK reference](/sdk/node) for the exact param shape (the React types mirror the server's directly).
* **Stale data after mutation.** `updateCustomer` returns the patched record; reuse that instead of refetching. For lists (`getCustomerPaymentInstruments`, etc.) you'll want to refetch or optimistically update.
* **Saved-instrument selection at checkout.** Once you have `instruments` loaded, pass an `instrument.id` directly to `checkout` as `source: instrument.id`. This skips tokenization entirely — no `<CardElement>` needed for repeat purchases. The Next.js example shows the full pattern in [`src/app/checkout/page.tsx`](https://github.com/itseasyco/easy-sdk/tree/main/examples/next-example/src/app/checkout/page.tsx).


# Next.js integration (/docs/sdks/react/examples/nextjs)



A complete, runnable Next.js example lives at `easy-sdk/examples/next-example`. This page is a guided tour — it points to the most-relevant files in that example so you can see the SDK wired into a real project, not just isolated snippets.

## Source code [#source-code]

* **Repository:** [`itseasyco/easy-sdk`](https://github.com/itseasyco/easy-sdk)
* **Path:** [`examples/next-example`](https://github.com/itseasyco/easy-sdk/tree/main/examples/next-example)

## What this example covers [#what-this-example-covers]

* Wiring `EasyProvider` into the App Router via a `"use client"` boundary, so server components above it stay server-side.
* A storefront landing page that fetches products through a server action and renders an interactive grid.
* A full checkout page (`/checkout`) that supports anonymous shoppers (creates a customer mid-flow), authenticated shoppers (uses a saved `identity_id`), and either a new card / bank account or a previously saved payment instrument.
* A user profile (`/profile`) that lists the signed-in customer's orders, payment methods, and subscriptions through `useEasy().getCustomerOrders / getCustomerPaymentInstruments / getCustomerSubscriptions`.
* An admin area (`/admin`) for products, prices, orders, subscriptions, and refunds — backed by Easy Labs server-side calls in Next.js Server Actions.
* Mixed usage of `@easylabs/react` (client-side, for tokenization) and `@easylabs/node` (server-side, in actions).

## Key files [#key-files]

| File                                                                                                                                           | What it shows                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`src/components/Providers.tsx`](https://github.com/itseasyco/easy-sdk/tree/main/examples/next-example/src/components/Providers.tsx)           | `"use client"` wrapper that renders `<EasyProvider>` from `process.env.NEXT_PUBLIC_EASY_API_KEY`.                                                 |
| [`src/app/layout.tsx`](https://github.com/itseasyco/easy-sdk/tree/main/examples/next-example/src/app/layout.tsx)                               | Root layout that mounts `<Providers>` once for the whole app.                                                                                     |
| [`src/app/checkout/page.tsx`](https://github.com/itseasyco/easy-sdk/tree/main/examples/next-example/src/app/checkout/page.tsx)                 | Full client-side checkout flow with `useEasy().checkout`, branching on `customer_creation` vs. `identity_id`, plus existing-instrument selection. |
| [`src/app/profile/page.tsx`](https://github.com/itseasyco/easy-sdk/tree/main/examples/next-example/src/app/profile/page.tsx)                   | Customer dashboard fetching orders, payment instruments, and subscriptions via `useEasy()`.                                                       |
| [`src/app/admin/products/actions.ts`](https://github.com/itseasyco/easy-sdk/tree/main/examples/next-example/src/app/admin/products/actions.ts) | Server-side product CRUD in a Next.js Server Action using the Node SDK with React types imported for shape sharing.                               |

## Run it locally [#run-it-locally]

```bash
git clone https://github.com/itseasyco/easy-sdk
cd easy-sdk
pnpm install
pnpm --filter @easylabs/common build
pnpm --filter @easylabs/react build
pnpm --filter @easylabs/node build

cd examples/next-example
cp .env.example .env.local
# Set NEXT_PUBLIC_EASY_API_KEY (sk_test_…), EASY_API_KEY (server-side), and DATABASE_URL.
pnpm db:gen
pnpm dev
```

Open [http://localhost:3000](http://localhost:3000).

The example uses Prisma for an embedded user / role / cart database — it is not part of the SDK and exists only to demonstrate the auth and admin flows in a realistic shape.

## Adapting it [#adapting-it]

* **App Router only.** `EasyProvider` must live inside a Client Component. The pattern in `src/components/Providers.tsx` is the recommended one — keep all client providers (theme, auth, cart, etc.) in a single file rendered from `app/layout.tsx`.
* **Pages Router.** Mount `<EasyProvider>` once in `pages/_app.tsx`. No `"use client"` needed.
* **Server vs. client split.** Use `@easylabs/react` only on the client (anywhere you need to tokenize a card or read live customer data with the user's session). Use `@easylabs/node` in server actions, route handlers, and webhooks where you need a server-side API key.
* **Strip auth.** The example bundles a Prisma-backed auth system to show authenticated checkout — if you already have your own auth, replace `useAuthContext()` with your equivalent and pass `user.customerId` into `checkout({ customer_creation: false, identity_id })`.
* **Webhooks.** Not in the example yet — see the [Node SDK webhooks guide](/sdk/node/webhooks) for the matching server side.


# Payment Form (/docs/sdks/react/examples/payment-form)



This recipe covers the most common Easy Labs React pattern: a checkout-style form that collects card or bank-account details with PCI-isolated elements and persists the result as a saved payment instrument against a customer you already have. It assumes you have an `EasyProvider` mounted somewhere above this form.

## Goal [#goal]

We want one form that:

1. Lets the user choose **card** or **bank account**.
2. Renders the corresponding PCI-isolated elements.
3. Submits to `useEasy().createPaymentInstrument`, which tokenizes the elements and saves a Finix-backed instrument against `customerId` in a single round trip.
4. Surfaces tokenization and API errors back to the user.

If you also want to charge the instrument in the same submission, swap `createPaymentInstrument` for `checkout` — see [Tradeoffs](#tradeoffs).

## Implementation [#implementation]

```tsx title="src/components/PaymentForm.tsx"
"use client";

import {
  CardElement,
  TextElement,
  useEasy,
  type AccountType,
  type CreatePaymentInstrument,
  type ICardElement,
  type ITextElement,
} from "@easylabs/react";
import { useId, useRef, useState } from "react";

type Props = {
  customerId: string;
  onSaved?: (instrumentId: string) => void;
};

export function PaymentForm({ customerId, onSaved }: Props) {
  const formId = useId();
  const { createPaymentInstrument } = useEasy();

  const [type, setType] = useState<CreatePaymentInstrument["type"]>("PAYMENT_CARD");
  const [name, setName] = useState("");
  const [accountType, setAccountType] = useState<AccountType>("PERSONAL_CHECKING");
  const [error, setError] = useState<string | null>(null);
  const [submitting, setSubmitting] = useState(false);

  const cardRef = useRef<ICardElement>(null);
  const routingRef = useRef<ITextElement>(null);
  const accountRef = useRef<ITextElement>(null);

  async function onSubmit(e: React.FormEvent) {
    e.preventDefault();
    setError(null);
    setSubmitting(true);
    try {
      const res = await createPaymentInstrument(
        type === "PAYMENT_CARD"
          ? {
              type: "PAYMENT_CARD",
              customerId,
              name,
              cardElement: cardRef,
            }
          : {
              type: "BANK_ACCOUNT",
              customerId,
              name,
              accountType,
              routingElement: routingRef,
              accountElement: accountRef,
            },
      );
      if (res.success) {
        onSaved?.(res.data.id);
      } else {
        setError(res.message ?? "Could not save payment method.");
      }
    } catch (err) {
      setError(err instanceof Error ? err.message : "Unexpected error.");
    } finally {
      setSubmitting(false);
    }
  }

  return (
    <form onSubmit={onSubmit}>
      <fieldset>
        <legend>Payment method</legend>
        <label>
          <input
            type="radio"
            checked={type === "PAYMENT_CARD"}
            onChange={() => setType("PAYMENT_CARD")}
          />
          Card
        </label>
        <label>
          <input
            type="radio"
            checked={type === "BANK_ACCOUNT"}
            onChange={() => setType("BANK_ACCOUNT")}
          />
          Bank account
        </label>
      </fieldset>

      <label htmlFor={`${formId}-name`}>Name on payment method</label>
      <input
        id={`${formId}-name`}
        value={name}
        onChange={(e) => setName(e.target.value)}
        required
      />

      {type === "PAYMENT_CARD" ? (
        <CardElement ref={cardRef} id={`${formId}-card`} />
      ) : (
        <>
          <label htmlFor={`${formId}-routing`}>Routing number</label>
          <TextElement ref={routingRef} id={`${formId}-routing`} />
          <label htmlFor={`${formId}-account`}>Account number</label>
          <TextElement ref={accountRef} id={`${formId}-account`} />
          <label htmlFor={`${formId}-acct-type`}>Account type</label>
          <select
            id={`${formId}-acct-type`}
            value={accountType}
            onChange={(e) => setAccountType(e.target.value as AccountType)}
          >
            <option value="PERSONAL_CHECKING">Personal checking</option>
            <option value="PERSONAL_SAVINGS">Personal savings</option>
            <option value="BUSINESS_CHECKING">Business checking</option>
            <option value="BUSINESS_SAVINGS">Business savings</option>
          </select>
        </>
      )}

      {error && <p role="alert">{error}</p>}
      <button type="submit" disabled={submitting}>
        {submitting ? "Saving…" : "Save payment method"}
      </button>
    </form>
  );
}
```

Three things make this work:

* The `cardElement` ref is a `RefObject<ICardElement>`, not a DOM ref. The element is an iframe that exposes a typed API surface (`.month()`, `.year()`, `.value`).
* Each branch passes the matching set of refs into `createPaymentInstrument`. The SDK throws if the wrong combination is provided, so a strict discriminated union on `type` keeps it ergonomic.
* The form key is generated with `useId()` so multiple instances of `<PaymentForm>` on the same page don't collide on input IDs — important when you re-render after a save.

For a full version with TanStack Form, address fields, and validation, see [`examples/react/src/components/CreateInstrumentForm.tsx`](https://github.com/itseasyco/easy-sdk/tree/main/examples/react/src/components/CreateInstrumentForm.tsx).

## Tradeoffs [#tradeoffs]

* **`createPaymentInstrument` vs. `checkout`.** `createPaymentInstrument` saves a card without charging it — useful for "add a payment method" pages. If you want to save *and* charge in one step, call `checkout` with the same element refs in `source` (and `customer_creation: true` for new customers). The example app's `CheckoutForm.tsx` does this.
* **Split-card layout.** Replace `<CardElement>` with `<CardNumberElement>` + `<CardExpirationDateElement>` + `<CardVerificationCodeElement>` and pass all three refs. The SDK throws if you pass only some of them.
* **No raw token access.** This recipe uses `createPaymentInstrument` so you never see the raw token. If you need to mint a bare token (e.g. to stash for later), call `tokenizePaymentInstrument` directly. You give up the typed instrument record in exchange.
* **Customer must exist first.** `createPaymentInstrument` requires `customerId`. Create the customer with `createCustomer` (or use `checkout({ customer_creation: true })` to do both at once).


# Vite SPA integration (/docs/sdks/react/examples/vite-spa)



A complete, runnable Vite SPA example lives at `easy-sdk/examples/react`. This page is a guided tour — it points to the most-relevant files in that example so you can see the SDK wired into a real project, not just isolated snippets.

## Source code [#source-code]

* **Repository:** [`itseasyco/easy-sdk`](https://github.com/itseasyco/easy-sdk)
* **Path:** [`examples/react`](https://github.com/itseasyco/easy-sdk/tree/main/examples/react)

## What this example covers [#what-this-example-covers]

* Mounting `EasyProvider` in `main.tsx` and reading API config from Vite env vars.
* Using `useEasy()` from inside form components.
* Standalone customer creation (`createCustomer`).
* Saving a card or bank account against an existing customer (`createPaymentInstrument`) using both the combined `CardElement` and the `TextElement` pair for ACH.
* One-off transfers against a saved instrument (`createTransfer`).
* An end-to-end product → cart → checkout flow that lists products with `getProducts`, builds a `line_items` payload, and runs `checkout` with `customer_creation: true`.
* TanStack Form + Zod for client-side validation, shadcn-style UI primitives for the visual layer.

## Key files [#key-files]

| File                                                                                                                                                | What it shows                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [`src/main.tsx`](https://github.com/itseasyco/easy-sdk/tree/main/examples/react/src/main.tsx)                                                       | `EasyProvider` mounted at the root with `apiKey` from `VITE_EASY_API_KEY`.                |
| [`src/App.tsx`](https://github.com/itseasyco/easy-sdk/tree/main/examples/react/src/App.tsx)                                                         | Form picker that swaps in each demo component. Good entry point for reading top-down.     |
| [`src/components/CreateCustomerForm.tsx`](https://github.com/itseasyco/easy-sdk/tree/main/examples/react/src/components/CreateCustomerForm.tsx)     | Minimal `useEasy().createCustomer` flow with validation.                                  |
| [`src/components/CreateInstrumentForm.tsx`](https://github.com/itseasyco/easy-sdk/tree/main/examples/react/src/components/CreateInstrumentForm.tsx) | `CardElement` and `TextElement` refs passed into `createPaymentInstrument`.               |
| [`src/components/CreateTransferForm.tsx`](https://github.com/itseasyco/easy-sdk/tree/main/examples/react/src/components/CreateTransferForm.tsx)     | Charging a saved instrument with `createTransfer`.                                        |
| [`src/components/CheckoutForm.tsx`](https://github.com/itseasyco/easy-sdk/tree/main/examples/react/src/components/CheckoutForm.tsx)                 | Full product browse → cart → `checkout({ customer_creation: true, line_items, source })`. |

## Run it locally [#run-it-locally]

```bash
git clone https://github.com/itseasyco/easy-sdk
cd easy-sdk
pnpm install
pnpm --filter @easylabs/common build
pnpm --filter @easylabs/react build

cd examples/react
cp .env.example .env  # then fill in VITE_EASY_API_KEY
pnpm dev
```

Open [http://localhost:5173](http://localhost:5173). You can use any `sk_test_…` key from the [Easy Labs dashboard](https://dashboard.itseasy.co); it will route to the sandbox API automatically.

## Adapting it [#adapting-it]

* **Drop the form picker.** `App.tsx` is just a router for the demos. Lift any single component (e.g. `CheckoutForm`) into your own app.
* **Replace TanStack Form.** The SDK doesn't care which form library you use — react-hook-form, Formik, or hand-rolled state all work.
* **Swap the UI kit.** Components depend on shadcn-style primitives in `src/components/ui/*`. Replace those with your own design system; the SDK code is in the `useEasy()` calls and element refs, not the styling.
* **Move tokenization to a separate step.** The example calls `checkout` (which tokenizes + charges in one shot). If you want to save the card before charging, swap to `createPaymentInstrument` followed by `createTransfer`.


# Customer Management (/docs/sdks/react-native/examples/customer-management)



A native screen for listing, creating, and editing customers — the data plane that complements the [Payment Form](./payment-form) recipe. No card data is involved here, so this pattern is independent of Basis Theory and runs as soon as `EasyProvider` mounts.

## Goal [#goal]

Build a screen that:

* Loads existing customers with `getCustomers`.
* Creates new customers with `createCustomer`.
* Edits an existing customer with `updateCustomer`.
* Uses a single form for both create and edit, toggled by selection state.

This is the same shape as the `ProfileScreen` in the [Expo example](./expo) — adapted here as a standalone recipe.

## Implementation [#implementation]

```tsx title="src/screens/CustomersScreen.tsx"
import type { CustomerData } from '@easylabs/react-native';
import { useEasy } from '@easylabs/react-native';
import { useCallback, useEffect, useState } from 'react';
import {
  ActivityIndicator,
  Alert,
  ScrollView,
  StyleSheet,
  Text,
  TextInput,
  TouchableOpacity,
  View,
} from 'react-native';

export default function CustomersScreen() {
  const { getCustomers, createCustomer, updateCustomer } = useEasy();

  const [customers, setCustomers] = useState<CustomerData[]>([]);
  const [selected, setSelected] = useState<CustomerData | null>(null);
  const [editing, setEditing] = useState(false);
  const [loading, setLoading] = useState(false);

  const [form, setForm] = useState({ firstName: '', lastName: '', email: '', phone: '' });

  const fillFormFrom = useCallback((c: CustomerData) => {
    setForm({
      firstName: c.entity.first_name,
      lastName: c.entity.last_name,
      email: c.entity.email ?? '',
      phone: c.entity.phone ?? '',
    });
  }, []);

  const load = useCallback(async () => {
    setLoading(true);
    try {
      const result = await getCustomers({ limit: 20 });
      if (result.success) {
        setCustomers(result.data);
        if (result.data.length > 0) {
          setSelected(result.data[0]);
          fillFormFrom(result.data[0]);
        }
      }
    } catch (err) {
      Alert.alert('Error', err instanceof Error ? err.message : 'Failed to load');
    } finally {
      setLoading(false);
    }
  }, [getCustomers, fillFormFrom]);

  useEffect(() => {
    load();
  }, [load]);

  const handleCreate = async () => {
    if (!form.firstName || !form.lastName) {
      Alert.alert('Missing info', 'First and last name are required.');
      return;
    }
    setLoading(true);
    try {
      const result = await createCustomer({
        first_name: form.firstName,
        last_name: form.lastName,
        email: form.email,
        phone: form.phone,
      });
      if (result.success) {
        Alert.alert('Created', `Customer ${result.data.id}`);
        await load();
        setForm({ firstName: '', lastName: '', email: '', phone: '' });
      }
    } catch (err) {
      Alert.alert('Error', err instanceof Error ? err.message : 'Failed to create');
    } finally {
      setLoading(false);
    }
  };

  const handleUpdate = async () => {
    if (!selected) return;
    setLoading(true);
    try {
      const result = await updateCustomer(selected.id, {
        first_name: form.firstName,
        last_name: form.lastName,
        email: form.email,
        phone: form.phone,
      });
      if (result.success) {
        Alert.alert('Saved', 'Customer updated');
        await load();
        setEditing(false);
      }
    } catch (err) {
      Alert.alert('Error', err instanceof Error ? err.message : 'Failed to save');
    } finally {
      setLoading(false);
    }
  };

  return (
    <ScrollView contentContainerStyle={styles.container}>
      {customers.length > 0 && (
        <View>
          <Text style={styles.sectionTitle}>Customers</Text>
          <ScrollView horizontal showsHorizontalScrollIndicator={false}>
            {customers.map((c) => (
              <TouchableOpacity
                key={c.id}
                style={[styles.chip, selected?.id === c.id && styles.chipSelected]}
                onPress={() => {
                  setSelected(c);
                  fillFormFrom(c);
                  setEditing(false);
                }}
              >
                <Text style={[styles.chipText, selected?.id === c.id && styles.chipTextSelected]}>
                  {c.entity.first_name} {c.entity.last_name}
                </Text>
              </TouchableOpacity>
            ))}
          </ScrollView>
        </View>
      )}

      <Text style={styles.sectionTitle}>
        {selected && !editing ? 'Customer details' : selected ? 'Edit customer' : 'New customer'}
      </Text>

      <Text style={styles.label}>First name</Text>
      <TextInput
        style={styles.input}
        value={form.firstName}
        onChangeText={(v) => setForm({ ...form, firstName: v })}
        editable={!loading && (!selected || editing)}
      />

      <Text style={styles.label}>Last name</Text>
      <TextInput
        style={styles.input}
        value={form.lastName}
        onChangeText={(v) => setForm({ ...form, lastName: v })}
        editable={!loading && (!selected || editing)}
      />

      <Text style={styles.label}>Email</Text>
      <TextInput
        style={styles.input}
        value={form.email}
        onChangeText={(v) => setForm({ ...form, email: v })}
        keyboardType="email-address"
        autoCapitalize="none"
        editable={!loading && (!selected || editing)}
      />

      <Text style={styles.label}>Phone</Text>
      <TextInput
        style={styles.input}
        value={form.phone}
        onChangeText={(v) => setForm({ ...form, phone: v })}
        keyboardType="phone-pad"
        editable={!loading && (!selected || editing)}
      />

      {selected && !editing ? (
        <TouchableOpacity style={styles.button} onPress={() => setEditing(true)}>
          <Text style={styles.buttonText}>Edit</Text>
        </TouchableOpacity>
      ) : selected && editing ? (
        <TouchableOpacity style={styles.button} onPress={handleUpdate} disabled={loading}>
          {loading ? <ActivityIndicator color="#fff" /> : <Text style={styles.buttonText}>Save</Text>}
        </TouchableOpacity>
      ) : (
        <TouchableOpacity style={styles.button} onPress={handleCreate} disabled={loading}>
          {loading ? <ActivityIndicator color="#fff" /> : <Text style={styles.buttonText}>Create</Text>}
        </TouchableOpacity>
      )}
    </ScrollView>
  );
}

const styles = StyleSheet.create({
  container: { padding: 16, gap: 8 },
  sectionTitle: { fontSize: 18, fontWeight: '600', marginTop: 16, marginBottom: 8 },
  chip: { paddingHorizontal: 16, paddingVertical: 8, borderRadius: 20, backgroundColor: '#f0f0f0', marginRight: 8 },
  chipSelected: { backgroundColor: '#007AFF' },
  chipText: { color: '#333' },
  chipTextSelected: { color: '#fff' },
  label: { fontSize: 14, fontWeight: '500', marginTop: 12 },
  input: { borderWidth: 1, borderColor: '#ddd', borderRadius: 8, padding: 12, fontSize: 16 },
  button: { backgroundColor: '#007AFF', borderRadius: 8, padding: 16, alignItems: 'center', marginTop: 16 },
  buttonText: { color: '#fff', fontSize: 16, fontWeight: '600' },
});
```

### Related calls [#related-calls]

`useEasy()` exposes the rest of the customer surface for follow-on screens:

```ts
const {
  // Single record
  getCustomer,
  // Subresources
  getCustomerPaymentInstruments,
  getCustomerOrders,
  getCustomerSubscriptions,
  getCustomerWallets,
} = useEasy();

const { data: instruments } = await getCustomerPaymentInstruments('cust_…');
const { data: orders } = await getCustomerOrders('cust_…', { limit: 20 });
```

## Tradeoffs [#tradeoffs]

* **All customer reads happen client-side under the publishable key.** This is fine for a logged-in customer viewing their own profile or for admin tooling shipped behind your own auth, but it's not appropriate for surfacing other customers' data in a consumer app. For multi-tenant or operator-facing tooling, proxy customer reads through your server using the [backend SDK](/docs/backend/node).
* **`updateCustomer` is `PATCH`-style.** Only fields you pass are updated; omitted fields keep their current value. To clear a field, pass an explicit `null` rather than omitting it.
* **No client-side pagination state.** The example loads 20 records and stops. For large lists, hold an `offset` in component state and bump it on a "Load more" button — `getCustomers({ limit, offset })` is paginated.
* **Tag schemas are unenforced.** `tags` is `Record<string, unknown>` at the API level. Define your tag shape in your own type and cast at the call site (see [TypeScript → Module augmentation](../typescript#module-augmentation)).


# Expo integration (/docs/sdks/react-native/examples/expo)



A complete, runnable Expo example lives at `easy-sdk/examples/react-native-example`. This page is a guided tour — it points to the most-relevant files in that example so you can see the SDK wired into a real project, not just isolated snippets.

## Source code [#source-code]

* **Repository:** [`itseasyco/easy-sdk`](https://github.com/itseasyco/easy-sdk)
* **Path:** [`examples/react-native-example`](https://github.com/itseasyco/easy-sdk/tree/main/examples/react-native-example)
* **README:** [`examples/react-native-example/README.md`](https://github.com/itseasyco/easy-sdk/blob/main/examples/react-native-example/README.md)

## What this example covers [#what-this-example-covers]

* Mounting `EasyProvider` once at the app root, above React Navigation.
* A two-screen native stack (`@react-navigation/native-stack`) — Home, Checkout, Profile.
* A full card checkout using the three separate native elements (`CardNumberElement`, `CardExpirationDateElement`, `CardVerificationCodeElement`) and `useEasy().checkout()`.
* Customer CRUD — list with `getCustomers`, create with `createCustomer`, update with `updateCustomer`.
* Reading API keys from Expo public env vars (`EXPO_PUBLIC_EASY_API_KEY`).
* Expo `newArchEnabled: true` configuration with the `expo-build-properties` plugin pinning Android to `arm64-v8a`.

## Key files [#key-files]

| File                                                                                                                                             | What it shows                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| [`App.tsx`](https://github.com/itseasyco/easy-sdk/blob/main/examples/react-native-example/App.tsx)                                               | `EasyProvider` mounted at the root, wrapping `NavigationContainer` and the stack navigator.       |
| [`src/screens/CheckoutScreen.tsx`](https://github.com/itseasyco/easy-sdk/blob/main/examples/react-native-example/src/screens/CheckoutScreen.tsx) | Full card capture + `checkout()` flow with separate elements, billing address, and loading state. |
| [`src/screens/ProfileScreen.tsx`](https://github.com/itseasyco/easy-sdk/blob/main/examples/react-native-example/src/screens/ProfileScreen.tsx)   | Customer list / create / edit with `getCustomers`, `createCustomer`, `updateCustomer`.            |
| [`src/screens/HomeScreen.tsx`](https://github.com/itseasyco/easy-sdk/blob/main/examples/react-native-example/src/screens/HomeScreen.tsx)         | Plain navigation surface — useful as a template for screens that don't touch the SDK directly.    |
| [`app.json`](https://github.com/itseasyco/easy-sdk/blob/main/examples/react-native-example/app.json)                                             | Expo config: `newArchEnabled: true`, `expo-build-properties` for Android arch pinning.            |
| [`package.json`](https://github.com/itseasyco/easy-sdk/blob/main/examples/react-native-example/package.json)                                     | Pinned versions: Expo `~54.0.22`, React Native `0.81.5`, React `19.1.0`.                          |

## Run it locally [#run-it-locally]

From the monorepo root:

```sh
pnpm install
pnpm run build:packages
```

In `examples/react-native-example`, create `.env.local`:

```bash
EXPO_PUBLIC_EASY_API_KEY=sk_test_…
```

Then start Metro:

```sh
cd examples/react-native-example
pnpm start
```

Press `i` for iOS, `a` for Android. iOS requires Xcode and an iOS Simulator; Android requires Android Studio with an emulator or a connected device.

If you hit hook errors after editing the SDK itself, clear Metro's cache:

```sh
npx expo start --clear
```

## Adapting it [#adapting-it]

Common modifications teams make when starting from this example:

* **Replace the `price_id`** in `CheckoutScreen.tsx` with one of your own product price IDs from the dashboard.
* **Swap separate elements for a single combined input** by replacing the three card refs with a different layout — the SDK supports either pattern through `tokenizePaymentInstrument`.
* **Add bank account support** by mounting two `TextElement` components for routing and account numbers and switching `source.type` to `BANK_ACCOUNT`. See the [Payment Form](./payment-form) recipe.
* **Move the API key off `EXPO_PUBLIC_*`** for bare-RN builds — use `react-native-config` or your own native config and pass the resolved string into `EasyProvider`.
* **Swap React Navigation for Expo Router** — `EasyProvider` doesn't depend on either; mount it inside `app/_layout.tsx` for Expo Router instead of in `App.tsx`.


# Payment Form (/docs/sdks/react-native/examples/payment-form)



A reusable native checkout screen that collects customer details, captures card data inside Basis Theory's PCI-scoped elements, and runs `useEasy().checkout()` to create a customer, tokenize the card, and place an order in one call.

## Goal [#goal]

Ship a card payment screen that:

* Captures the PAN, expiration, and CVC inside native inputs (no card data ever in your component state).
* Creates a new customer and order in a single round-trip via `checkout()`.
* Surfaces validation, network, and tokenization errors back to the user.
* Works the same way on iOS and Android with no platform-specific branching.

The same pattern adapts to bank account (ACH) capture by swapping the element types and `source.type`.

## Implementation [#implementation]

```tsx title="src/screens/PaymentFormScreen.tsx"
import {
  type BTDateRef,
  type BTRef,
  CardExpirationDateElement,
  CardNumberElement,
  CardVerificationCodeElement,
  useEasy,
} from '@easylabs/react-native';
import { useRef, useState } from 'react';
import {
  ActivityIndicator,
  Alert,
  ScrollView,
  StyleSheet,
  Text,
  TextInput,
  TouchableOpacity,
  View,
} from 'react-native';

const PRICE_ID = 'price_…'; // from your Easy dashboard

export default function PaymentFormScreen() {
  const { checkout } = useEasy();

  const cardNumberRef = useRef<BTRef>(null);
  const cardExpirationRef = useRef<BTDateRef>(null);
  const cardCvcRef = useRef<BTRef>(null);

  const [form, setForm] = useState({ firstName: '', lastName: '', email: '' });
  const [loading, setLoading] = useState(false);

  const handleSubmit = async () => {
    if (!form.firstName || !form.lastName || !form.email) {
      Alert.alert('Missing info', 'First name, last name, and email are required.');
      return;
    }

    setLoading(true);
    try {
      const result = await checkout({
        customer_creation: true,
        customer_details: {
          first_name: form.firstName,
          last_name: form.lastName,
          email: form.email,
        },
        source: {
          type: 'PAYMENT_CARD',
          name: `${form.firstName} ${form.lastName}`,
          cardNumberElement: cardNumberRef,
          cardExpirationDateElement: cardExpirationRef,
          cardVerificationCodeElement: cardCvcRef,
        },
        line_items: [{ price_id: PRICE_ID, quantity: 1 }],
        metadata: { source: 'react-native-app' },
      });

      if (result.success) {
        Alert.alert('Paid', `Order ${result.data.orderId}`);
      }
    } catch (err) {
      Alert.alert('Error', err instanceof Error ? err.message : 'Payment failed');
    } finally {
      setLoading(false);
    }
  };

  return (
    <ScrollView contentContainerStyle={styles.container}>
      <Text style={styles.label}>First name</Text>
      <TextInput
        style={styles.input}
        value={form.firstName}
        onChangeText={(v) => setForm({ ...form, firstName: v })}
        editable={!loading}
      />

      <Text style={styles.label}>Last name</Text>
      <TextInput
        style={styles.input}
        value={form.lastName}
        onChangeText={(v) => setForm({ ...form, lastName: v })}
        editable={!loading}
      />

      <Text style={styles.label}>Email</Text>
      <TextInput
        style={styles.input}
        value={form.email}
        onChangeText={(v) => setForm({ ...form, email: v })}
        keyboardType="email-address"
        autoCapitalize="none"
        editable={!loading}
      />

      <Text style={styles.label}>Card number</Text>
      <View style={styles.element}>
        <CardNumberElement btRef={cardNumberRef} />
      </View>

      <View style={styles.row}>
        <View style={styles.flex}>
          <Text style={styles.label}>Expiration</Text>
          <View style={styles.element}>
            <CardExpirationDateElement btRef={cardExpirationRef} />
          </View>
        </View>
        <View style={styles.flex}>
          <Text style={styles.label}>CVC</Text>
          <View style={styles.element}>
            <CardVerificationCodeElement btRef={cardCvcRef} />
          </View>
        </View>
      </View>

      <TouchableOpacity
        style={[styles.button, loading && styles.buttonDisabled]}
        onPress={handleSubmit}
        disabled={loading}
      >
        {loading ? <ActivityIndicator color="#fff" /> : <Text style={styles.buttonText}>Pay</Text>}
      </TouchableOpacity>
    </ScrollView>
  );
}

const styles = StyleSheet.create({
  container: { padding: 16, gap: 8 },
  label: { fontSize: 14, fontWeight: '500', marginTop: 12 },
  input: { borderWidth: 1, borderColor: '#ddd', borderRadius: 8, padding: 12, fontSize: 16 },
  element: { borderWidth: 1, borderColor: '#ddd', borderRadius: 8, padding: 12, minHeight: 50 },
  row: { flexDirection: 'row', gap: 12 },
  flex: { flex: 1 },
  button: {
    backgroundColor: '#007AFF',
    borderRadius: 8,
    padding: 16,
    alignItems: 'center',
    marginTop: 24,
  },
  buttonDisabled: { backgroundColor: '#ccc' },
  buttonText: { color: '#fff', fontSize: 16, fontWeight: '600' },
});
```

### Variations [#variations]

**Existing customer.** Skip `customer_creation` and pass an `identity_id`:

```ts
await checkout({
  customer_creation: false,
  identity_id: 'cust_…',
  source: {
    type: 'PAYMENT_CARD',
    name: 'Jane Doe',
    cardNumberElement: cardNumberRef,
    cardExpirationDateElement: cardExpirationRef,
    cardVerificationCodeElement: cardCvcRef,
  },
  line_items: [{ price_id: PRICE_ID, quantity: 1 }],
});
```

**Stored payment instrument.** Pass the instrument id as `source` directly — no element refs needed:

```ts
await checkout({
  customer_creation: false,
  identity_id: 'cust_…',
  source: 'pi_…',
  line_items: [{ price_id: PRICE_ID, quantity: 1 }],
});
```

**Bank account (ACH).** Replace card refs with two `TextElement` refs and switch `source.type`:

```tsx
import { TextElement, type BTRef } from '@easylabs/react-native';

const routingRef = useRef<BTRef>(null);
const accountRef = useRef<BTRef>(null);

await checkout({
  customer_creation: true,
  customer_details: { first_name: 'Jane', last_name: 'Doe' },
  source: {
    type: 'BANK_ACCOUNT',
    accountType: 'CHECKING',
    name: 'Jane Doe',
    routingElement: routingRef,
    accountElement: accountRef,
  },
  line_items: [{ price_id: PRICE_ID, quantity: 1 }],
});

// Inputs:
<TextElement btRef={routingRef} keyboardType="numeric" placeholder="Routing number" />
<TextElement btRef={accountRef} keyboardType="numeric" placeholder="Account number" secureTextEntry />
```

## Tradeoffs [#tradeoffs]

* **Element refs must be mounted at submit time.** Don't conditionally hide a card element behind a tab and call `checkout()` from a different tab — the ref will be `null` and tokenization throws `"Card element reference is not set"`. If you need multi-step UI, mount the element off-screen or guard the submit on a known-good screen.
* **No on-device validation gating before submit.** The element exposes `onChange` events with `complete` / `valid` flags (see [Elements → Validation](../elements#validation)) — wire a disabled state into the submit button if you want to block submission until the form is complete locally.
* **`checkout()` is a single transaction.** Customer creation, tokenization, instrument creation, and the order all share one promise. If you need to retry only the order portion (e.g. after a 3DS retry), call `createPaymentInstrument` first to get a stable instrument ID, then call `checkout()` with that ID as the `source`.
* **Don't use this for Apple Pay or Google Pay.** Wallet flows have their own native sheet — see [Wallet Checkout](../wallet-checkout). Only fall back to manual card entry when the wallet is unavailable.


# E-commerce Flow (/docs/sdks/ruby/examples/ecommerce-flow)



End-to-end recipe for a typical e-commerce checkout: capture a tokenised
card from the browser, charge it, persist the order, and react to the
post-charge webhook.

## Goal [#goal]

Take a customer through a one-shot card payment with a server-side
charge:

1. Browser tokenises the card with BasisTheory and posts the token to
   our server.
2. Server creates (or retrieves) a customer.
3. Server attaches the tokenised card as a payment instrument.
4. Server creates a transfer for the order amount.
5. Server records the order locally.
6. Webhook handler confirms the payment when `payment.created` arrives.

## Implementation [#implementation]

```ruby
require "easy_sdk"

client = EasyLabs::Client.new(api_key: ENV.fetch("EASY_API_KEY"))

# 1. Browser POST: { token: "tok_…", email:, first_name:, last_name:, amount_cents: }
def checkout(client, params)
  customer = client.customers.create(
    first_name: params[:first_name],
    last_name:  params[:last_name],
    email:      params[:email]
  )

  card = client.payment_instruments.create(
    tokenId:    params[:token],
    identityId: customer[:id],
    type:       "PAYMENT_CARD",
    name:       "Card on file"
  )

  transfer = client.transfers.create(
    amount:   params[:amount_cents],
    currency: "USD",
    source:   card[:id],
    tags:     { order_id: SecureRandom.uuid }
  )

  Order.create!(
    customer_id: customer[:id],
    transfer_id: transfer[:id],
    amount:      params[:amount_cents],
    status:      "pending"
  )

  { transfer_id: transfer[:id], status: "pending" }
rescue EasyLabs::InvalidRequestError => e
  # Bad input from the browser (e.g. expired token).
  { error: e.message, code: e.code }
rescue EasyLabs::Error => e
  Rails.logger.error("[easy] #{e.status} #{e.code}: #{e.message}")
  raise
end

# Webhook receiver
post "/webhooks/easy" do
  event = EasyLabs::Webhooks.construct_event(
    payload:   request.body.read,
    signature: request.headers["X-Easy-Webhook-Signature"],
    secret:    ENV.fetch("EASY_WEBHOOK_SECRET")
  )

  case event[:type]
  when "payment.created"
    transfer_id = event.dig(:data, :id)
    Order.where(transfer_id: transfer_id).update_all(status: "paid")
  end

  status 204
end
```

## Tradeoffs [#tradeoffs]

* **Server-side `transfers.create` vs. checkout sessions.** This recipe
  charges the customer synchronously. For a hosted page, swap steps
  2-4 for [Payment Links](../resources/payment-links). For an embedded
  widget, use [Embedded Checkout](../resources/embedded-checkout) — both
  return a URL/secret you hand to the browser instead of charging
  inline.
* **Customer dedup.** This recipe always creates a new customer.
  Real-world apps should look up by email first and reuse the existing
  identity to avoid duplicate `cust_…` rows.
* **Idempotency.** The transfer is fire-and-forget. If the request
  times out, you may double-charge. Wrap the call in your own retry
  layer keyed on a stable `order_id` until the SDK exposes
  per-resource `idempotency_key:` arguments.
* **Webhook latency.** Don't render "thanks for your order" off the
  webhook — render it off the synchronous `transfers.create` response
  and use the webhook only for downstream effects (fulfillment,
  receipts, accounting).


# Refunds (/docs/sdks/ruby/examples/refunds)



Practical recipe for issuing refunds from your support tooling and
keeping local state consistent with refund webhooks.

## Goal [#goal]

A support agent can:

1. Look up a charge by ID.
2. Issue a full or partial refund with a reason tag.
3. Trust that the refund eventually settles, with `refund.updated`
   webhooks keeping your DB in sync.

## Implementation [#implementation]

### Issue the refund [#issue-the-refund]

The Easy API expresses refunds as **reversals** on the original
transfer — there is no top-level `Refunds.create`. The SDK exposes them
via `client.transfers.create_refund`.

```ruby
require "easy_sdk"

client = EasyLabs::Client.new(api_key: ENV.fetch("EASY_API_KEY"))

def refund_charge(client, transfer_id:, amount_cents: nil, reason:)
  charge = client.transfers.retrieve(transfer_id)
  amount = amount_cents || charge[:amount]    # default to full refund

  if amount > charge[:amount]
    raise ArgumentError, "Refund amount exceeds charge amount"
  end

  client.transfers.create_refund(
    charge[:id],
    refund_amount: amount,
    tags: {
      reason:     reason,
      issued_by:  Current.agent.email,
      issued_at:  Time.now.iso8601
    }
  )
rescue EasyLabs::InvalidRequestError => e
  # 400/422 — typically because the charge isn't refundable yet.
  { error: e.message, code: e.code }
end
```

### Read refund history [#read-refund-history]

The parent transfer carries the full reversals collection — no separate
list call needed.

```ruby
charge = client.transfers.retrieve("tr_…")
charge[:reversals]&.each do |refund|
  puts "#{refund[:id]} — #{refund[:amount]} #{refund[:state]}"
end
```

### Sync from webhooks [#sync-from-webhooks]

```ruby
post "/webhooks/easy" do
  event = EasyLabs::Webhooks.construct_event(
    payload:   request.body.read,
    signature: request.headers["X-Easy-Webhook-Signature"],
    secret:    ENV.fetch("EASY_WEBHOOK_SECRET")
  )

  case event[:type]
  when "refund.created", "refund.updated"
    Refund.upsert_by_easy_id(event[:data])
  end

  status 204
end
```

## Tradeoffs [#tradeoffs]

* **Full vs. partial refunds.** `refund_amount` is in minor units —
  always pass the full charge amount for a full refund rather than
  relying on a "missing → full" default. Explicit is safer in support
  workflows.
* **Multiple partial refunds.** You can issue multiple partial refunds
  against the same transfer until the cumulative amount matches the
  original charge. The API rejects further refunds beyond that.
* **Tags as audit trail.** Stash the agent identifier and reason in
  `tags` — they're immutable on the refund record and showing them in
  your support tool gives you a free audit trail.
* **Webhook latency.** `transfers.create_refund` returns a
  `PENDING`-shaped refund; final settlement (and chargeback resolution)
  comes through `refund.updated`. Don't tell the customer "refund
  complete" off the create call.
* **Subscription / invoice refunds.** For refunding a subscription
  invoice, refund the underlying transfer here — there is no separate
  "void invoice + refund" combo on the SDK.


# Subscription System (/docs/sdks/ruby/examples/subscription-system)



Recipe for standing up a recurring-billing system on top of
`client.products`, `client.product_prices`, and `client.subscriptions` —
catalog setup, customer signup, mid-cycle upgrades, and cancellation.

## Goal [#goal]

Run a SaaS-style subscription where:

1. Catalog is defined once (one `Product`, multiple `Prices`).
2. Customers sign up to a price; payment instrument is on file.
3. Mid-cycle upgrades use proration preview before applying.
4. Cancellations honor "end of period" by default.
5. Lifecycle webhooks keep your local state in sync.

## Implementation [#implementation]

### 1. Define the catalog (one-time) [#1-define-the-catalog-one-time]

```ruby
client = EasyLabs::Client.new(api_key: ENV.fetch("EASY_API_KEY"))

product = client.products.create(name: "Pro plan")

monthly = client.product_prices.create(
  product_id:     product[:id],
  active:         true,
  recurring:      true,
  currency:       "USD",
  unit_amount:    4_900,
  interval:       "month",
  interval_count: 1,
  tax_behavior:   "exclusive"
)

annual = client.product_prices.create(
  product_id:     product[:id],
  active:         true,
  recurring:      true,
  currency:       "USD",
  unit_amount:    49_900,
  interval:       "year",
  interval_count: 1,
  tax_behavior:   "exclusive"
)
```

### 2. Sign up a customer [#2-sign-up-a-customer]

```ruby
customer = client.customers.create(
  first_name: "Ada", last_name: "Lovelace", email: "ada@example.com"
)

card = client.payment_instruments.create(
  tokenId:    token_from_browser,
  identityId: customer[:id],
  type:       "PAYMENT_CARD",
  name:       "Personal card"
)

sub = client.subscriptions.create(
  identity_id:   customer[:id],
  items:         [{ price_id: monthly[:id] }],
  instrument_id: card[:id]
)
```

### 3. Preview, then upgrade [#3-preview-then-upgrade]

```ruby
preview = client.subscriptions.proration_preview(
  sub[:id],
  items: [{ price_id: annual[:id], quantity: 1 }]
)

if preview[:total] <= max_charge_cents
  client.subscriptions.update(sub[:id], items: [{ price_id: annual[:id] }])
end
```

### 4. Cancel at period end [#4-cancel-at-period-end]

```ruby
client.subscriptions.cancel(sub[:id], at_period_end: true)
```

### 5. Sync state from webhooks [#5-sync-state-from-webhooks]

```ruby
post "/webhooks/easy" do
  event = EasyLabs::Webhooks.construct_event(
    payload:   request.body.read,
    signature: request.headers["X-Easy-Webhook-Signature"],
    secret:    ENV.fetch("EASY_WEBHOOK_SECRET")
  )

  data = event[:data]

  case event[:type]
  when "subscription.created", "subscription.updated"
    Subscription.upsert_by_easy_id(data)
  when "subscription.deleted"
    Subscription.find_by(easy_id: data[:id])&.update!(state: "canceled")
  when "subscription.paused"
    Subscription.find_by(easy_id: data[:id])&.update!(state: "paused")
  when "subscription.resumed"
    Subscription.find_by(easy_id: data[:id])&.update!(state: "active")
  when "invoice.paid"
    Invoice.upsert_by_easy_id(data)
  when "invoice.payment_failed"
    DunningMailer.with(invoice: data).failed.deliver_later
  end

  status 204
end
```

## Tradeoffs [#tradeoffs]

* **Always preview prorations.** `proration_preview` is cheap and lets
  you show the customer (and verify against your business rules) what
  an upgrade actually costs before you charge them.
* **Cancel at period end vs. immediately.** Defaulting to
  `at_period_end: true` is friendlier and matches most customers'
  expectations — passing `false` cancels immediately and forfeits the
  remainder of the period.
* **Source of truth.** Treat the Easy API as the source of truth for
  subscription state and use webhooks to keep your local cache fresh.
  Avoid recording subscription state synchronously from the create call
  — the create response and a subsequent webhook can race.
* **Metered billing.** For usage-based pricing, layer
  `report_usage` calls into your existing event pipeline rather than
  doing it inline at request time. See [Subscriptions › Metered
  usage](../resources/subscriptions#metered-usage).


# Analytics (/docs/sdks/ruby/resources/analytics)



Aggregator endpoints for dashboards and reporting. Each method returns
a pre-aggregated payload over a time window — no need to walk every
underlying record yourself.

Every method accepts the same query shape: `period:`, `start_date:`,
`end_date:` (plus per-endpoint extras the API supports).

Accessed via `client.analytics`.

## Methods [#methods]

### `transactions(**query)` [#transactionsquery]

`GET /analytics/transactions`.

```ruby
client.analytics.transactions(period: "month")
client.analytics.transactions(start_date: "2026-04-01", end_date: "2026-04-30")
```

### `disputes(**query)` [#disputesquery]

`GET /analytics/disputes`.

```ruby
client.analytics.disputes(period: "quarter")
```

### `settlements(**query)` [#settlementsquery]

`GET /analytics/settlements`.

```ruby
client.analytics.settlements(period: "month")
```

### `revenue(**query)` [#revenuequery]

`GET /analytics/revenue`.

```ruby
client.analytics.revenue(period: "year")
```

### `revenue_recovery(**query)` [#revenue_recoveryquery]

`GET /analytics/revenue-recovery`. Aggregates the dunning + recovery
funnel — recovered amounts, retry success rate, automation hits.

```ruby
client.analytics.revenue_recovery(period: "month")
```

## Object shape [#object-shape]

Each endpoint returns a per-bucket aggregation: `:buckets` keyed by
period, each with `:gross`, `:net`, `:count`, `:currency`, … plus
top-line totals.

{/* TODO: enumerate the per-endpoint analytics schemas. */}

## Examples [#examples]

### Build a monthly revenue chart [#build-a-monthly-revenue-chart]

```ruby
data = client.analytics.revenue(period: "month")
data[:buckets].each do |bucket|
  puts "#{bucket[:period_start]}: #{bucket[:gross]} #{bucket[:currency]}"
end
```

### Surface dispute-rate spikes [#surface-dispute-rate-spikes]

```ruby
disputes  = client.analytics.disputes(period: "month")
txns      = client.analytics.transactions(period: "month")
rate      = disputes[:total_count].to_f / txns[:total_count]
alert! if rate > 0.01
```


# Authorizations (/docs/sdks/ruby/resources/authorizations)



An authorization holds funds on a card without capturing them. Use them
for delayed-capture flows: pre-orders, ride-hailing, hotels — anywhere
the final amount isn't known when the customer pays.

Authorizations are created implicitly through `checkout` /
`embedded_checkout` / `transfers` (when the appropriate flag is set).
The SDK exposes the read + capture/void surface on the resulting
authorization object.

Accessed via `client.authorizations`.

## Methods [#methods]

### `list(limit: nil, offset: nil, ids: nil)` [#listlimit-nil-offset-nil-ids-nil]

`GET /authorizations`.

```ruby
client.authorizations.list(limit: 50)
```

### `retrieve(id)` [#retrieveid]

`GET /authorizations/:id`.

### `capture(id, amount:)` [#captureid-amount]

`POST /authorizations/:id/capture`. `amount` is in minor units and may
be less than or equal to the authorized amount.

```ruby
client.authorizations.capture("auth_…", amount: 1_000)
```

### `void(id)` [#voidid]

`POST /authorizations/:id/void`. Release the held funds without
capturing.

```ruby
client.authorizations.void("auth_…")
```

## Object shape [#object-shape]

`:id`, `:state` (`SUCCEEDED`, `CAPTURED`, `VOIDED`, …), `:amount`,
`:captured_amount`, `:currency`, `:source`, `:expires_at`, `:created_at`, …

{/* TODO: enumerate the full authorization schema. */}

## Webhook events [#webhook-events]

Subscribe to `authorization.created`, `authorization.updated`, and
`authorization.voided`.

## Examples [#examples]

### Capture less than the authorized amount [#capture-less-than-the-authorized-amount]

```ruby
auth = client.authorizations.retrieve("auth_…")
client.authorizations.capture(auth[:id], amount: auth[:amount] - 500)
```

### Void on cancelled order [#void-on-cancelled-order]

```ruby
client.authorizations.void("auth_…")
```


# Checkout (/docs/sdks/ruby/resources/checkout)



One-shot, server-driven checkout. Use this when you've collected
payment-instrument data via tokenisation and want to create the customer

* instrument + charge in a single API call. For a hosted page, use
  [Payment Links](./payment-links). For an iframe-embeddable widget, use
  [Embedded Checkout](./embedded-checkout).

Accessed via `client.checkout`. Maps to a single endpoint.

## Methods [#methods]

### `create(**body)` [#createbody]

`POST /checkout`. Accepts both card/bank and wallet (crypto) variants —
the API discriminates on the body shape. Pass `source` for a tokenised
payment instrument or wallet details for a wallet-checkout flow.

```ruby
session = client.checkout.create(
  customer_creation: false,
  identity_id:       customer[:id],
  source:            token_id,
  line_items: [
    { name: "Pro plan", quantity: 1, unit_price: 4_900, currency: "USD" }
  ]
)
```

## Object shape [#object-shape]

The response includes the resulting `:order`, `:transfer` (if a charge
was made), and `:customer` records. Wallet-checkout responses additionally
include the on-chain transaction reference.

{/* TODO: enumerate the full checkout response payload, including the wallet-variant fields. */}

## Examples [#examples]

### Charge a tokenised card on a guest checkout [#charge-a-tokenised-card-on-a-guest-checkout]

```ruby
client.checkout.create(
  customer_creation: true,
  customer_details:  { first_name: "Ada", last_name: "Lovelace", email: "ada@example.com" },
  source:            token_from_browser,
  line_items: [
    { name: "Annual plan", quantity: 1, unit_price: 19_900, currency: "USD" }
  ]
)
```

### Wallet (crypto) checkout [#wallet-crypto-checkout]

{/* TODO: document the wallet-checkout request body once the canonical shape is finalised — it currently shares the `/checkout` endpoint via body discrimination. */}


# Compliance Forms (/docs/sdks/ruby/resources/compliance-forms)



Compliance forms are the merchant agreements (terms of service,
processing agreements, etc.) that need an authorized signer's name and
title before certain platform features unlock.

Accessed via `client.compliance_forms`.

## Methods [#methods]

### `list` [#list]

`GET /compliance-forms`. Every form your account currently needs.

```ruby
client.compliance_forms.list
```

### `retrieve(id)` [#retrieveid]

`GET /compliance-forms/:id`.

```ruby
client.compliance_forms.retrieve("cf_…")
```

### `sign(id, name:, title:)` [#signid-name-title]

`PUT /compliance-forms/:id/sign`. Records the signer's name and title
against the form.

```ruby
client.compliance_forms.sign("cf_…", name: "Ada Lovelace", title: "CEO")
```

## Object shape [#object-shape]

`:id`, `:type`, `:state` (`UNSIGNED`, `SIGNED`), `:document_url`,
`:signed_by`, `:signed_at`, `:created_at`, …

{/* TODO: enumerate the full compliance-form schema. */}

## Examples [#examples]

### Sign every outstanding form [#sign-every-outstanding-form]

```ruby
client.compliance_forms.list[:data].each do |form|
  next if form[:state] == "SIGNED"

  client.compliance_forms.sign(form[:id], name: "Ada Lovelace", title: "CEO")
end
```


# Coupons (/docs/sdks/ruby/resources/coupons)



A coupon is a reusable discount template — percent-off or amount-off,
applied once or recurring across N billing periods. Promotion codes are
the customer-facing names you hand out; coupons are the underlying
discount.

Accessed via `client.coupons`.

## Methods [#methods]

### `create(**body)` [#createbody]

`POST /coupons`.

```ruby
client.coupons.create(percent_off: 25, duration: "once")
client.coupons.create(amount_off: 1_000, currency: "USD", duration: "repeating", duration_in_months: 3)
```

### `list(limit: nil, offset: nil, ids: nil)` [#listlimit-nil-offset-nil-ids-nil]

`GET /coupons`.

### `retrieve(id)` [#retrieveid]

`GET /coupons/:id`.

### `update(id, **body)` [#updateid-body]

`PATCH /coupons/:id`. Coupons are mostly immutable — the metadata and
`active` flag are the practical update targets.

```ruby
client.coupons.update("cpn_…", active: false)
```

### `delete(id)` [#deleteid]

`DELETE /coupons/:id`.

## Object shape [#object-shape]

`:id`, `:percent_off`, `:amount_off`, `:currency`, `:duration` (`once`,
`forever`, `repeating`), `:duration_in_months`, `:max_redemptions`,
`:redeem_by`, `:active`, `:created_at`, …

{/* TODO: link to canonical coupon schema. */}

## Examples [#examples]

### Create a one-time 25% off coupon [#create-a-one-time-25-off-coupon]

```ruby
coupon = client.coupons.create(percent_off: 25, duration: "once")
```

### Wrap a coupon in a customer-facing promotion code [#wrap-a-coupon-in-a-customer-facing-promotion-code]

```ruby
coupon = client.coupons.create(percent_off: 50, duration: "once")
client.promotion_codes.create(coupon_id: coupon[:id], code: "LAUNCH50", max_redemptions: 100)
```

### Retire a coupon without deleting it [#retire-a-coupon-without-deleting-it]

```ruby
client.coupons.update("cpn_…", active: false)
```


# Customers (/docs/sdks/ruby/resources/customers)



A `Customer` is the identity Easy Labs uses to associate payment
instruments, orders, subscriptions, and wallets. Most resources accept
either a customer-shaped payload inline or an `identity_id` referencing a
previously created customer.

Accessed via `client.customers`.

## Methods [#methods]

### `create(**body)` [#createbody]

`POST /customer`. Body is a hash of customer fields — at minimum `email`,
`first_name`, `last_name`.

```ruby
customer = client.customers.create(
  first_name: "Ada",
  last_name:  "Lovelace",
  email:      "ada@example.com"
)
```

### `update(id, **body)` [#updateid-body]

`PATCH /customer/:id`. Pass only the fields you want to change.

```ruby
client.customers.update(customer[:id], phone: "+15555550100")
```

### `retrieve(id)` [#retrieveid]

`GET /customer/:id`.

```ruby
client.customers.retrieve("cust_…")
```

### `list(limit: nil, offset: nil, ids: nil)` [#listlimit-nil-offset-nil-ids-nil]

`GET /customer`. Standard pagination keywords (see [Pagination](../pagination)).

```ruby
page = client.customers.list(limit: 50)
page = client.customers.list(ids: ["cust_a", "cust_b"])
```

### `payment_instruments(id)` [#payment_instrumentsid]

`GET /customer/:id/instruments`. Every payment instrument tokenised
against this customer.

```ruby
client.customers.payment_instruments("cust_…")
```

### `orders(id, limit: nil, offset: nil, ids: nil)` [#ordersid-limit-nil-offset-nil-ids-nil]

`GET /customer/:id/orders`.

```ruby
client.customers.orders("cust_…", limit: 25)
```

### `subscriptions(id, status: nil, limit: nil, offset: nil, ids: nil)` [#subscriptionsid-status-nil-limit-nil-offset-nil-ids-nil]

`GET /customer/:id/subscriptions`. Optional `status:` filter
(`active`, `paused`, `canceled`, …).

```ruby
client.customers.subscriptions("cust_…", status: "active")
```

### `wallets(id, limit: nil, offset: nil, ids: nil)` [#walletsid-limit-nil-offset-nil-ids-nil]

`GET /customer/:id/wallets`. Crypto wallet records associated with the
customer.

```ruby
client.customers.wallets("cust_…")
```

## Object shape [#object-shape]

The response is a Ruby `Hash` with symbol keys mirroring the API
payload — `:id`, `:first_name`, `:last_name`, `:email`, `:phone`,
`:created_at`, `:updated_at`, `:tags`, …

See the [API reference](https://api-docs.itseasy.co) for the canonical
schema; the SDK passes payloads through as-is.

## Examples [#examples]

### Create or update by email [#create-or-update-by-email]

```ruby
def upsert_customer(client, email:, **fields)
  existing = client.customers.list(limit: 1).dig(:data, 0)  # filter on email server-side when supported
  if existing && existing[:email] == email
    client.customers.update(existing[:id], **fields)
  else
    client.customers.create(email: email, **fields)
  end
end
```

### List active subscriptions for a customer [#list-active-subscriptions-for-a-customer]

```ruby
client.customers
      .subscriptions("cust_…", status: "active")
      .fetch(:data, [])
      .each { |sub| puts "#{sub[:id]} — #{sub[:plan_name]}" }
```

### Walk every customer [#walk-every-customer]

```ruby
offset = 0
loop do
  page = client.customers.list(limit: 100, offset: offset)
  rows = page[:data] || []
  rows.each { |c| puts c[:email] }
  break if rows.size < 100

  offset += rows.size
end
```


# Disputes (/docs/sdks/ruby/resources/disputes)



A dispute (a.k.a. chargeback) is a customer's challenge to a transfer.
The SDK lets you list and retrieve disputes, mutate their tags, and
drive the lifecycle: accept the dispute, upload evidence, or submit
your response.

Accessed via `client.disputes`.

## Methods [#methods]

### `list(limit: nil, offset: nil, ids: nil)` [#listlimit-nil-offset-nil-ids-nil]

`GET /disputes`.

```ruby
client.disputes.list(limit: 25)
```

### `retrieve(id)` [#retrieveid]

`GET /disputes/:id`.

### `update(id, tags:)` [#updateid-tags]

`PATCH /disputes/:id`. Mutates `tags` only.

```ruby
client.disputes.update("dp_…", tags: { reason: "duplicate", agent: "support@example.com" })
```

## Lifecycle actions [#lifecycle-actions]

### `accept(id)` [#acceptid]

`POST /disputes/:id/accept`. Concede the dispute.

```ruby
client.disputes.accept("dp_…")
```

### `submit(id)` [#submitid]

`POST /disputes/:id/submit`. Submit your evidence package for review.

```ruby
client.disputes.submit("dp_…")
```

### `upload_evidence(id, **parts)` [#upload_evidenceid-parts]

`POST /disputes/:id/evidence`. Multipart/form-data upload — pass scalar
fields as keyword args and the file as a `Net::HTTP::UploadIO` (or any
IO-like object accepted by the [`multipart-post`](https://rubygems.org/gems/multipart-post) gem).

```ruby
require "net/http/post/multipart"

client.disputes.upload_evidence(
  "dp_…",
  evidence_type: "receipt",
  file:          UploadIO.new(File.open("receipt.pdf"), "application/pdf", "receipt.pdf")
)
```

### `list_evidence(id)` [#list_evidenceid]

`GET /disputes/:id/evidence`. Every evidence item attached to the
dispute.

```ruby
client.disputes.list_evidence("dp_…")
```

## Object shape [#object-shape]

`:id`, `:transfer_id`, `:reason`, `:state` (`NEEDS_RESPONSE`,
`UNDER_REVIEW`, `WON`, `LOST`, `ACCEPTED`, …), `:amount`, `:currency`,
`:respond_by`, `:evidence`, `:tags`, `:created_at`, …

{/* TODO: enumerate the full dispute schema. */}

## Webhook events [#webhook-events]

Subscribe to `dispute.created` and `dispute.updated`.

## Examples [#examples]

### Build an evidence package and submit it [#build-an-evidence-package-and-submit-it]

```ruby
require "net/http/post/multipart"

File.open("invoice.pdf") do |io|
  client.disputes.upload_evidence(
    "dp_…",
    evidence_type: "invoice",
    file:          UploadIO.new(io, "application/pdf", "invoice.pdf")
  )
end

File.open("shipping_label.pdf") do |io|
  client.disputes.upload_evidence(
    "dp_…",
    evidence_type: "shipping_documentation",
    file:          UploadIO.new(io, "application/pdf", "shipping_label.pdf")
  )
end

client.disputes.submit("dp_…")
```

### Concede a clearly-fraudulent dispute [#concede-a-clearly-fraudulent-dispute]

```ruby
client.disputes.accept("dp_…")
```


# Dunning (/docs/sdks/ruby/resources/dunning)



Dunning is the recovery flow that runs when an invoice or subscription
payment fails — retry schedules, reminder emails, and recovery
automations. The SDK exposes two related resources:

* `client.dunning_config` — the singleton config that controls retry
  behaviour and customer-facing emails.
* `client.revenue_recovery_automations` — programmable rules that fire
  in response to recovery events (e.g. "if invoice still unpaid after 7
  days, cancel the subscription").

## Dunning config [#dunning-config]

A single config per merchant. `create_or_replace` POSTs the full config;
`update` PATCHes the fields you pass; `retrieve` reads the current state.

### `client.dunning_config.create_or_replace(**body)` [#clientdunning_configcreate_or_replacebody]

`POST /dunning-config`.

```ruby
client.dunning_config.create_or_replace(
  retry_mode:           "smart",
  smart_retry_attempts: 4,
  payment_failed_email_enabled: true
)
```

### `client.dunning_config.retrieve` [#clientdunning_configretrieve]

`GET /dunning-config`.

### `client.dunning_config.update(**body)` [#clientdunning_configupdatebody]

`PATCH /dunning-config`.

```ruby
client.dunning_config.update(payment_failed_email_enabled: false)
```

## Revenue recovery automations [#revenue-recovery-automations]

Rule-based actions that fire on recovery events. Each rule has a
`trigger_type:` and an action body the API interprets.

### `client.revenue_recovery_automations.list` [#clientrevenue_recovery_automationslist]

`GET /revenue-recovery-automations`.

### `client.revenue_recovery_automations.create(**body)` [#clientrevenue_recovery_automationscreatebody]

`POST /revenue-recovery-automations`.

```ruby
client.revenue_recovery_automations.create(
  trigger_type: "invoice_overdue",
  conditions:   { days_overdue: 7 },
  actions:      [{ type: "cancel_subscription" }]
)
```

### `client.revenue_recovery_automations.update(id, **body)` [#clientrevenue_recovery_automationsupdateid-body]

`PATCH /revenue-recovery-automations/:id`.

```ruby
client.revenue_recovery_automations.update("auto_…", active: false)
```

### `client.revenue_recovery_automations.delete(id)` [#clientrevenue_recovery_automationsdeleteid]

`DELETE /revenue-recovery-automations/:id`.

### `client.revenue_recovery_automations.runs(id)` [#clientrevenue_recovery_automationsrunsid]

`GET /revenue-recovery-automations/:id/runs`. Audit trail of every time
this automation fired.

```ruby
client.revenue_recovery_automations.runs("auto_…")
```

## Object shapes [#object-shapes]

`DunningConfig` — `:retry_mode` (`smart` | `manual` | `off`),
`:smart_retry_attempts`, `:retry_schedule`,
`:payment_failed_email_enabled`, `:reminder_emails`, …

`RevenueRecoveryAutomation` — `:id`, `:trigger_type`, `:conditions`,
`:actions`, `:active`, `:created_at`, …

{/* TODO: enumerate the full config + automation schemas. */}

## Webhook events [#webhook-events]

Subscribe to `invoice.payment_failed` to react when dunning starts and
`revenue_recovery.action_completed` when an automation runs.

## Examples [#examples]

### Tighten dunning policy [#tighten-dunning-policy]

```ruby
client.dunning_config.update(retry_mode: "smart", smart_retry_attempts: 6)
```

### Auto-cancel after a week of failed retries [#auto-cancel-after-a-week-of-failed-retries]

```ruby
client.revenue_recovery_automations.create(
  trigger_type: "invoice_overdue",
  conditions:   { days_overdue: 7 },
  actions:      [{ type: "cancel_subscription", at_period_end: false }]
)
```


# Embedded Checkout (/docs/sdks/ruby/resources/embedded-checkout)



An embedded-checkout session is the server-side counterpart to the
`@easylabs/embedded-checkout` browser widget. Your server creates the
session and returns the `client_secret` to the browser; the browser
calls `validate` and `confirm` directly with that secret (no API key
needed in client code).

Accessed via `client.embedded_checkout`.

## Methods [#methods]

### `create(**body)` [#createbody]

`POST /embedded-checkout`. Server-side. Returns the session including
the `client_secret`.

```ruby
session = client.embedded_checkout.create(
  line_items: [{ price_id: "price_…", quantity: 1 }]
)

return_to_browser(session[:client_secret])
```

### `retrieve(id)` [#retrieveid]

`GET /embedded-checkout/:id`. Server-side session lookup.

```ruby
client.embedded_checkout.retrieve("sess_…")
```

### `crypto_status(id)` [#crypto_statusid]

`GET /embedded-checkout/:id/crypto-status`. Polls the on-chain status
for crypto sessions.

```ruby
client.embedded_checkout.crypto_status("sess_…")
```

### `validate(client_secret:, parent_origin: nil)` [#validateclient_secret-parent_origin-nil]

`POST /embedded-checkout/validate`. **Public endpoint** — authenticates
via the session's `client_secret` and skips the `X-Easy-Api-Key` header
entirely, so it's safe to call from a browser-like context. The SDK still
exposes it for completeness (e.g. server-side smoke tests).

```ruby
client.embedded_checkout.validate(
  client_secret: "cs_…",
  parent_origin: "https://shop.example.com"
)
```

### `confirm(client_secret:, source:, customer_details:)` [#confirmclient_secret-source-customer_details]

`POST /embedded-checkout/confirm`. **Public endpoint** — same auth
behaviour as `validate`.

```ruby
client.embedded_checkout.confirm(
  client_secret:    "cs_…",
  source:           { type: "PAYMENT_CARD", tokenId: "tok_…" },
  customer_details: { first_name: "Ada", last_name: "Lovelace", email: "ada@example.com" }
)
```

### `config` [#config]

`GET /embedded-checkout/config`. Returns the merchant-level embedded
config (e.g. `allowed_origins`).

```ruby
client.embedded_checkout.config
```

### `update_config(allowed_origins: nil)` [#update_configallowed_origins-nil]

`PATCH /embedded-checkout/config`.

```ruby
client.embedded_checkout.update_config(allowed_origins: ["https://shop.example.com"])
```

## Object shape [#object-shape]

A session response contains `:id`, `:client_secret`, `:status`,
`:line_items`, `:amount`, `:currency`, `:expires_at`, …

{/* TODO: enumerate the full embedded-checkout session schema. */}

## Examples [#examples]

### Create a session and pass the secret to the browser [#create-a-session-and-pass-the-secret-to-the-browser]

```ruby
def create_checkout_session(price_id)
  session = client.embedded_checkout.create(
    line_items: [{ price_id: price_id, quantity: 1 }]
  )

  { client_secret: session[:client_secret] }
end
```

### Lock down `allowed_origins` [#lock-down-allowed_origins]

```ruby
client.embedded_checkout.update_config(
  allowed_origins: ["https://shop.example.com", "https://staging.shop.example.com"]
)
```


# Invoices (/docs/sdks/ruby/resources/invoices)



Invoices represent both the recurring invoices automatically generated
by the subscription engine and ad-hoc invoices created via the API for
one-off billing.

Accessed via `client.invoices`.

## Methods [#methods]

### `create(**body)` [#createbody]

`POST /invoices`. Create a manual invoice.

```ruby
invoice = client.invoices.create(
  to_email: "client@example.com",
  due_date: "2026-05-15",
  items: [
    { description: "Consulting — April",   quantity: 10, unit_price: 25_000 },
    { description: "Travel reimbursement", quantity:  1, unit_price: 12_500 }
  ]
)
```

### `list(**query)` [#listquery]

`GET /invoices`. Accepts arbitrary query params — `status:`, `customer_id:`,
plus the usual `limit:` / `offset:`.

```ruby
client.invoices.list(status: "OPEN", limit: 50)
```

### `retrieve(id)` [#retrieveid]

`GET /invoices/:id`.

### `update(id, **body)` [#updateid-body]

`PATCH /invoices/:id`. Mutate notes, line items, or due date on an
unfinalised invoice.

```ruby
client.invoices.update("inv_…", notes: "Net 15 on this one — thanks Ada.")
```

### `send_invoice(id, **body)` [#send_invoiceid-body]

`POST /invoices/:id/send`. Renamed from `send` to avoid collision with
`Object#send`.

```ruby
client.invoices.send_invoice("inv_…")
```

### `pay(id, **body)` [#payid-body]

`POST /invoices/:id/pay`. Charge an invoice immediately using a saved
instrument.

```ruby
client.invoices.pay("inv_…", instrument_id: card[:id])
```

### `remind(id)` [#remindid]

`POST /invoices/:id/remind`. Trigger a reminder email to the customer.

```ruby
client.invoices.remind("inv_…")
```

### `void(id)` [#voidid]

`POST /invoices/:id/void`.

```ruby
client.invoices.void("inv_…")
```

### `pdf_data(id)` [#pdf_dataid]

`GET /invoices/:id/pdf`. Returns a JSON payload shaped for client-side
PDF rendering rather than a binary PDF blob.

```ruby
client.invoices.pdf_data("inv_…")
```

## Object shape [#object-shape]

`:id`, `:status` (`DRAFT`, `OPEN`, `PAID`, `VOID`, `UNCOLLECTIBLE`),
`:customer`, `:items`, `:subtotal`, `:total`, `:amount_due`, `:due_date`,
`:hosted_invoice_url`, `:created_at`, …

{/* TODO: enumerate the full invoice schema. */}

## Examples [#examples]

### Create + send in one go [#create--send-in-one-go]

```ruby
invoice = client.invoices.create(
  to_email: "client@example.com",
  due_date: 14.days.from_now.to_date.iso8601,
  items:    [{ description: "Plan", quantity: 1, unit_price: 4_900 }]
)

client.invoices.send_invoice(invoice[:id])
```

### Auto-charge on creation [#auto-charge-on-creation]

```ruby
invoice = client.invoices.create(...)
client.invoices.pay(invoice[:id], instrument_id: customer_default_card_id)
```

### Render a custom PDF client-side [#render-a-custom-pdf-client-side]

```ruby
data = client.invoices.pdf_data("inv_…")
MyPdfRenderer.render(data)
```


# Orders (/docs/sdks/ruby/resources/orders)



An order represents a discrete transaction in your system — typically
created server-side after a checkout completes. The SDK exposes a
read-only orders list plus a tag-update for reconciliation metadata.
Order creation happens implicitly through checkout, payment links, and
invoices.

Accessed via `client.orders`.

## Methods [#methods]

### `list(limit: nil, offset: nil, ids: nil)` [#listlimit-nil-offset-nil-ids-nil]

`GET /orders`.

```ruby
client.orders.list(limit: 50)
```

### `retrieve(id)` [#retrieveid]

`GET /orders/:id`.

```ruby
client.orders.retrieve("ord_…")
```

### `update_tags(id, tags:)` [#update_tagsid-tags]

`PATCH /orders/:id` with `{ tags }`. The legacy `/orders/:id/tags`
suffix returns 404 on the current API and is not used by the SDK.

```ruby
client.orders.update_tags("ord_…", tags: { region: "us-east", source: "shopify" })
```

## Object shape [#object-shape]

`:id`, `:state`, `:amount`, `:currency`, `:customer`, `:line_items`,
`:tags`, `:created_at`, … plus references to the originating checkout
session, payment link, or invoice.

{/* TODO: enumerate the full order schema once the public reference is finalised. */}

## Examples [#examples]

### Tag an order with internal reconciliation IDs [#tag-an-order-with-internal-reconciliation-ids]

```ruby
client.orders.update_tags(
  "ord_…",
  tags: { netsuite_id: "12345", reconciled_at: Time.now.iso8601 }
)
```

### Pull recent orders for a CSV export [#pull-recent-orders-for-a-csv-export]

```ruby
rows = client.orders.list(limit: 100)[:data] || []
rows.each do |order|
  puts [order[:id], order[:amount], order[:currency], order[:state]].join(",")
end
```


# Payment Instruments (/docs/sdks/ruby/resources/payment-instruments)



A payment instrument is a tokenised card or bank account attached to a
customer. The Easy API stores Finix-shaped payment-instrument objects;
the SDK exposes the two server-safe operations: `create` (with a token
from the front-end) and `update` (e.g. to disable an instrument).

Tokenisation itself happens client-side via BasisTheory — the
`basis_theory_public_api_key` returned at client construction is what you
hand to the browser SDK. Never send raw card data to the API.

Accessed via `client.payment_instruments`.

## Methods [#methods]

### `create(**body)` [#createbody]

`POST /payment`. Attach a tokenised instrument to a customer.

```ruby
client.payment_instruments.create(
  tokenId:    "tok_…",          # from BasisTheory tokenisation
  identityId: customer[:id],
  type:       "PAYMENT_CARD",
  name:       "Card on file"
)
```

### `update(id, **body)` [#updateid-body]

`PATCH /payment/:id`. Mutate metadata, disable, or set as default.

```ruby
client.payment_instruments.update("pi_…", enabled: false)
```

## Object shape [#object-shape]

Returned shape mirrors the Finix payment-instrument object — `:id`,
`:type`, `:name`, `:enabled`, `:identity`, `:tags`, `:bin`,
`:last_four`, `:brand`, …

{/* TODO: link to canonical API reference for the full Finix-shaped payload. */}

## Examples [#examples]

### Customer with a single card on file [#customer-with-a-single-card-on-file]

```ruby
customer = client.customers.create(
  first_name: "Ada", last_name: "Lovelace", email: "ada@example.com"
)

card = client.payment_instruments.create(
  tokenId:    token_from_browser,
  identityId: customer[:id],
  type:       "PAYMENT_CARD",
  name:       "Personal card"
)

client.transfers.create(amount: 1000, currency: "USD", source: card[:id])
```

### Disable an instrument without deleting it [#disable-an-instrument-without-deleting-it]

```ruby
client.payment_instruments.update(card[:id], enabled: false)
```


# Payment Links (/docs/sdks/ruby/resources/payment-links)



A payment link is a hosted, shareable URL that runs the Easy checkout
without any code on your site. Use them for invoicing, sales outreach,
and one-off requests for payment.

Accessed via `client.payment_links`. Maps to the `/v1/api/payment-link/*`
routes — branding endpoints under `/v1/auth/branding/payment-link/*` are
intentionally out of scope for this SDK.

## Methods [#methods]

### `create(**body)` [#createbody]

`POST /payment-link`.

```ruby
link = client.payment_links.create(
  amount_type: "FIXED",
  products: [
    { name: "Annual plan", quantity: 1, unit_price: 19_900, currency: "USD" }
  ]
)

puts link[:url]
```

### `list(limit: nil, offset: nil, ids: nil)` [#listlimit-nil-offset-nil-ids-nil]

`GET /payment-link/`.

```ruby
client.payment_links.list(limit: 25)
```

### `retrieve(id)` [#retrieveid]

`GET /payment-link/:id`.

```ruby
client.payment_links.retrieve("plink_…")
```

### `update(id, **body)` [#updateid-body]

`PATCH /payment-link/:id`. Adjust the active state, expiration, products,
or metadata.

```ruby
client.payment_links.update("plink_…", active: false)
```

### `delete(id)` [#deleteid]

`DELETE /payment-link/:id`.

```ruby
client.payment_links.delete("plink_…")
```

### `list_payments(id, limit: nil, offset: nil, ids: nil)` [#list_paymentsid-limit-nil-offset-nil-ids-nil]

`GET /payment-link/:id/payments`. Every payment captured against a link.

```ruby
client.payment_links.list_payments("plink_…", limit: 100)
```

## Object shape [#object-shape]

The response includes `:id`, `:url`, `:amount_type` (`FIXED` or
`CUSTOMER_DECIDES`), `:products`, `:active`, `:expires_at`, `:created_at`,
`:metadata`, …

{/* TODO: enumerate the full payment-link object once the public schema is finalised. */}

## Examples [#examples]

### Send a fixed-amount link via email [#send-a-fixed-amount-link-via-email]

```ruby
link = client.payment_links.create(
  amount_type: "FIXED",
  products: [{ name: "Consultation", quantity: 1, unit_price: 25_000, currency: "USD" }],
  expires_at: (Time.now + 7 * 86_400).iso8601
)

CustomerMailer.with(to: "client@example.com", url: link[:url]).pay_now.deliver_later
```

### Reconcile payments captured by a link [#reconcile-payments-captured-by-a-link]

```ruby
client.payment_links
      .list_payments("plink_…", limit: 100)
      .fetch(:data, [])
      .each { |p| puts "#{p[:id]} — #{p[:amount]} #{p[:currency]}" }
```


# Products Pricing (/docs/sdks/ruby/resources/products-pricing)



Products and prices are the primitives behind subscriptions and recurring
billing. A `Product` describes the thing being sold; a `Price` (a.k.a.
product-price) describes how it's billed — currency, amount, billing
interval, and tax behaviour.

The SDK splits these across two resources:

* `client.products` — product CRUD plus nested-price reads.
* `client.product_prices` — price CRUD.

## Products [#products]

### `client.products.list(limit: nil, offset: nil, ids: nil)` [#clientproductslistlimit-nil-offset-nil-ids-nil]

`GET /products`.

```ruby
client.products.list(limit: 25)
```

### `client.products.retrieve(id)` [#clientproductsretrieveid]

`GET /products/:id`.

### `client.products.create(**body)` [#clientproductscreatebody]

`POST /products`.

```ruby
product = client.products.create(name: "Pro plan", description: "Everything in Pro.")
```

### `client.products.update(id, **body)` [#clientproductsupdateid-body]

`PATCH /products/:id`.

```ruby
client.products.update("pr_…", name: "Pro plan v2")
```

### `client.products.archive(id)` [#clientproductsarchiveid]

`PATCH /products/:id/archive`.

```ruby
client.products.archive("pr_…")
```

### `client.products.with_prices(id)` [#clientproductswith_pricesid]

`GET /products/:id/prices`. Product object plus its full nested price
list — handy for catalog rendering.

### `client.products.with_price(id, price_id)` [#clientproductswith_priceid-price_id]

`GET /products/:id/prices/:price_id`. Product plus a single price.

## Product prices [#product-prices]

### `client.product_prices.list(limit: nil, offset: nil, ids: nil)` [#clientproduct_priceslistlimit-nil-offset-nil-ids-nil]

`GET /product-prices`.

### `client.product_prices.retrieve(id)` [#clientproduct_pricesretrieveid]

`GET /product-prices/:id`.

### `client.product_prices.create(**body)` [#clientproduct_pricescreatebody]

`POST /product-prices`. Body shape is a tagged union: pass either a
recurring price or a one-off. The API enforces the discriminator.

```ruby
client.product_prices.create(
  product_id:     "pr_…",
  active:         true,
  recurring:      true,
  currency:       "USD",
  unit_amount:    5_000,
  interval:       "month",
  interval_count: 1,
  tax_behavior:   "exclusive"
)
```

### `client.product_prices.update(id, **body)` [#clientproduct_pricesupdateid-body]

`PATCH /product-prices/:id`.

```ruby
client.product_prices.update("price_…", active: false)
```

### `client.product_prices.archive(id)` [#clientproduct_pricesarchiveid]

`PATCH /product-prices/:id/archive`.

## Object shapes [#object-shapes]

`Product` — `:id`, `:name`, `:description`, `:active`, `:metadata`,
`:created_at`, …

`Price` — `:id`, `:product_id`, `:currency`, `:unit_amount`,
`:recurring`, `:interval`, `:interval_count`, `:tax_behavior`, `:active`,
…

{/* TODO: enumerate the full price union (recurring vs. one-off, tiered, metered) once the canonical schema is published. */}

## Examples [#examples]

### Create a product with a monthly price [#create-a-product-with-a-monthly-price]

```ruby
product = client.products.create(name: "Pro plan")

price = client.product_prices.create(
  product_id:     product[:id],
  active:         true,
  recurring:      true,
  currency:       "USD",
  unit_amount:    4_900,
  interval:       "month",
  interval_count: 1,
  tax_behavior:   "exclusive"
)

client.subscriptions.create(
  identity_id:   customer[:id],
  items:         [{ price_id: price[:id] }],
  instrument_id: card[:id]
)
```

### Render a catalog page [#render-a-catalog-page]

```ruby
products = client.products.list(limit: 100)[:data] || []
catalog  = products.map { |p| client.products.with_prices(p[:id]) }
```


# Promotion Codes (/docs/sdks/ruby/resources/promotion-codes)



A promotion code is the customer-facing string (e.g. `LAUNCH50`) that
maps to a `Coupon`. Promotion codes can scope, limit, and gate the
underlying discount per identity.

Accessed via `client.promotion_codes`.

## Methods [#methods]

### `create(**body)` [#createbody]

`POST /promotion-codes`. Requires `coupon_id:`; `code:` is optional
(the API generates one if omitted).

```ruby
client.promotion_codes.create(
  coupon_id:       "cpn_…",
  code:            "SUMMER25",
  max_redemptions: 1_000,
  expires_at:      "2026-09-01T00:00:00Z"
)
```

### `list(limit: nil, offset: nil, ids: nil)` [#listlimit-nil-offset-nil-ids-nil]

`GET /promotion-codes`.

### `retrieve(id)` [#retrieveid]

`GET /promotion-codes/:id`.

### `update(id, **body)` [#updateid-body]

`PATCH /promotion-codes/:id`.

```ruby
client.promotion_codes.update("pc_…", active: false)
```

### `delete(id)` [#deleteid]

`DELETE /promotion-codes/:id`.

### `validate(code:, identity_id: nil, amount: nil)` [#validatecode-identity_id-nil-amount-nil]

`POST /promotion-codes/validate`. Server-side validity check before
applying the code at checkout. Optionally scope the check to a specific
identity and/or order amount.

```ruby
result = client.promotion_codes.validate(
  code:        "SUMMER25",
  identity_id: customer[:id],
  amount:      4_900
)
```

## Object shape [#object-shape]

`:id`, `:code`, `:coupon_id`, `:active`, `:expires_at`, `:max_redemptions`,
`:times_redeemed`, `:restrictions`, …

{/* TODO: link to canonical promotion-code schema. */}

## Examples [#examples]

### Validate before applying [#validate-before-applying]

```ruby
result = client.promotion_codes.validate(code: params[:code], identity_id: customer[:id])
if result[:valid]
  client.subscriptions.apply_discount(sub[:id], promotion_code: params[:code])
else
  flash[:error] = "That code can't be used on this subscription."
end
```

### Generate a one-shot personalised code [#generate-a-one-shot-personalised-code]

```ruby
client.promotion_codes.create(
  coupon_id:       "cpn_winback",
  max_redemptions: 1,
  metadata:        { customer_id: customer[:id] }
)
```


# Refunds (/docs/sdks/ruby/resources/refunds)



There is no top-level `Refunds` resource — refunds are issued against an
existing transfer via the `reversals` sub-resource. Use
`client.transfers.create_refund` to issue them.

For a top-level refunds index / retrieve API, **coming soon**.

{/* TODO: add a dedicated `client.refunds` resource (`list`, `retrieve`) once the API exposes a top-level `/refunds` index. */}

## Issuing a refund [#issuing-a-refund]

```ruby
# Full refund
charge = client.transfers.retrieve("tr_…")
client.transfers.create_refund(charge[:id], refund_amount: charge[:amount])

# Partial refund
client.transfers.create_refund("tr_…", refund_amount: 500)

# With reconciliation tags
client.transfers.create_refund(
  "tr_…",
  refund_amount: 1_000,
  tags:          { reason: "customer_request", agent: "support@example.com" }
)
```

See [Transfers › `create_refund`](./transfers#create_refundtransfer_id-refund_amount-tags-nil)
for the full method signature.

## Reading refund history [#reading-refund-history]

The `:reversals` field on the parent transfer contains every refund
issued against it:

```ruby
charge = client.transfers.retrieve("tr_…")
charge[:reversals]&.each do |refund|
  puts "#{refund[:id]} — #{refund[:amount]}"
end
```

## Webhook events [#webhook-events]

Subscribe to `refund.created` and `refund.updated` to react to refund
state changes asynchronously. See [Webhooks](../webhooks) for the
verifier and the full event-type catalog.


# Settlements (/docs/sdks/ruby/resources/settlements)



A settlement is a batch of transfers (charges and refunds) grouped for
payout — the unit of reconciliation between Easy Labs and your bank.
Read-only on the SDK side, plus a `close` action.

Accessed via `client.settlements`.

## Methods [#methods]

### `list(limit: nil, offset: nil, ids: nil)` [#listlimit-nil-offset-nil-ids-nil]

`GET /settlements`.

```ruby
client.settlements.list(limit: 50)
```

### `retrieve(id)` [#retrieveid]

`GET /settlements/:id`.

```ruby
client.settlements.retrieve("st_…")
```

### `close(id)` [#closeid]

`PATCH /settlements/:id`. Closes an open settlement so the payout can
be initiated.

```ruby
client.settlements.close("st_…")
```

## Object shape [#object-shape]

`:id`, `:state` (`OPEN`, `CLOSED`, `PAID`, …), `:total_amount`,
`:net_amount`, `:fees`, `:transfers`, `:created_at`, `:closed_at`, …

{/* TODO: enumerate the full settlement schema. */}

## Webhook events [#webhook-events]

Subscribe to `settlement.created` to react when a new settlement opens.

## Examples [#examples]

### Daily reconciliation export [#daily-reconciliation-export]

```ruby
client.settlements
      .list(limit: 100)[:data]
      .select { |s| s[:state] == "CLOSED" }
      .each   { |s| ReconciliationJob.perform_later(s[:id]) }
```

### Manually close an open settlement [#manually-close-an-open-settlement]

```ruby
client.settlements.close("st_…")
```


# Subscriptions (/docs/sdks/ruby/resources/subscriptions)



The Easy-native subscription engine. Covers the full lifecycle:
create / list / retrieve, cancel / pause / resume, item CRUD, discount
application, one-time charges, metered usage reporting, and proration
preview.

Accessed via `client.subscriptions`. The largest resource in the SDK
(\~14 endpoints).

## Top-level methods [#top-level-methods]

### `list(limit: nil, offset: nil, ids: nil)` [#listlimit-nil-offset-nil-ids-nil]

`GET /subscriptions`.

```ruby
client.subscriptions.list(limit: 50)
```

### `retrieve(id)` [#retrieveid]

`GET /subscriptions/:id`.

### `create(**body)` [#createbody]

`POST /subscriptions`. Minimum required fields: `identity_id:`,
`items:`, `instrument_id:`.

```ruby
sub = client.subscriptions.create(
  identity_id:   customer[:id],
  items:         [{ price_id: "price_…" }],
  instrument_id: card[:id]
)
```

### `update(id, **body)` [#updateid-body]

`PATCH /subscriptions/:id`. Update top-level fields like
`cancel_at_period_end:` or default payment method.

```ruby
client.subscriptions.update("sub_…", cancel_at_period_end: true)
```

### `cancel(id, at_period_end: nil)` [#cancelid-at_period_end-nil]

`DELETE /subscriptions/:id?at_period_end=…`. With no argument the
server's default applies; pass `true` / `false` explicitly to override.

```ruby
client.subscriptions.cancel("sub_…")                       # server default
client.subscriptions.cancel("sub_…", at_period_end: true)  # cancel at end of period
client.subscriptions.cancel("sub_…", at_period_end: false) # cancel immediately
```

## Pause / resume [#pause--resume]

### `pause(id, behavior:, resumes_at: nil)` [#pauseid-behavior-resumes_at-nil]

`POST /subscriptions/:id/pause`. `behavior` controls how the API treats
unpaid invoices during the pause (`"void"`, `"keep_as_draft"`, …).

```ruby
client.subscriptions.pause("sub_…", behavior: "void", resumes_at: "2026-06-01T00:00:00Z")
```

### `resume(id)` [#resumeid]

`POST /subscriptions/:id/resume`.

## Items [#items]

### `add_item(id, price_id:, quantity: nil)` [#add_itemid-price_id-quantity-nil]

`POST /subscriptions/:id/items`.

```ruby
client.subscriptions.add_item("sub_…", price_id: "price_addon", quantity: 2)
```

### `update_item(id, item_id, quantity:)` [#update_itemid-item_id-quantity]

`PATCH /subscriptions/:id/items/:item_id`.

```ruby
client.subscriptions.update_item("sub_…", "si_…", quantity: 5)
```

### `remove_item(id, item_id)` [#remove_itemid-item_id]

`DELETE /subscriptions/:id/items/:item_id`.

## Discounts [#discounts]

### `apply_discount(id, **body)` [#apply_discountid-body]

`POST /subscriptions/:id/discounts`. Pass exactly one of `coupon_id:`
or `promotion_code:`; optionally scope to a single item with
`subscription_item_id:`. The XOR is enforced server-side.

```ruby
client.subscriptions.apply_discount("sub_…", promotion_code: "SUMMER25")
```

### `list_discounts(id)` [#list_discountsid]

`GET /subscriptions/:id/discounts`.

### `remove_discount(id, discount_id)` [#remove_discountid-discount_id]

`DELETE /subscriptions/:id/discounts/:discount_id`.

## One-time charges [#one-time-charges]

### `create_one_time_charge(id, **body)` [#create_one_time_chargeid-body]

`POST /subscriptions/:id/one-time-charges`. Adds a non-recurring line to
the next invoice — useful for usage overages, setup fees, etc.

```ruby
client.subscriptions.create_one_time_charge(
  "sub_…", price_id: "price_setup_fee", quantity: 1
)
```

## Metered usage [#metered-usage]

### `report_usage(id, **body)` [#report_usageid-body]

`POST /subscriptions/:id/usage`. Report a usage delta against a metered
subscription item.

```ruby
client.subscriptions.report_usage("sub_…", subscription_item_id: "si_…", quantity: 100)
```

### `usage_summary(id, **query)` [#usage_summaryid-query]

`GET /subscriptions/:id/usage/summary`.

### `usage_reconciliation(id, **query)` [#usage_reconciliationid-query]

`GET /subscriptions/:id/usage/reconciliation`.

## Proration preview [#proration-preview]

### `proration_preview(id, items: nil, remove_items: nil, proration_date: nil)` [#proration_previewid-items-nil-remove_items-nil-proration_date-nil]

`GET /subscriptions/:id/proration-preview`. Preview the charge that
would result from a planned change before applying it.

`items:` accepts the same shape as `add_item` — array of
`{ price_id:, quantity: }` hashes. The SDK encodes them as the
comma-joined `price_id:quantity` shape the API expects.

```ruby
preview = client.subscriptions.proration_preview(
  "sub_…",
  items:        [{ price_id: "price_addon", quantity: 2 }],
  remove_items: ["si_old_addon"]
)
```

## Object shape [#object-shape]

`:id`, `:identity_id`, `:status` (`active`, `paused`, `canceled`,
`trialing`, …), `:items`, `:current_period_start`,
`:current_period_end`, `:cancel_at_period_end`, `:default_payment_method`,
`:metadata`, …

{/* TODO: enumerate the full subscription schema once the public reference is published. */}

## Examples [#examples]

### Create, add an item, then preview the proration [#create-add-an-item-then-preview-the-proration]

```ruby
sub = client.subscriptions.create(
  identity_id:   customer[:id],
  items:         [{ price_id: "price_base" }],
  instrument_id: card[:id]
)

preview = client.subscriptions.proration_preview(
  sub[:id],
  items: [{ price_id: "price_addon", quantity: 2 }]
)

if preview[:total] <= max_acceptable_charge
  client.subscriptions.add_item(sub[:id], price_id: "price_addon", quantity: 2)
end
```

### Cancel at the end of the current period [#cancel-at-the-end-of-the-current-period]

```ruby
client.subscriptions.cancel("sub_…", at_period_end: true)
```

### Apply a coupon, then remove it [#apply-a-coupon-then-remove-it]

```ruby
discount = client.subscriptions.apply_discount("sub_…", coupon_id: "cpn_holiday")
client.subscriptions.remove_discount("sub_…", discount[:id])
```


# Transfers (/docs/sdks/ruby/resources/transfers)



A transfer is a single charge against a payment instrument — the API
primitive behind one-off payments and the source of refunds via the
`reversals` sub-resource.

Accessed via `client.transfers`.

## Methods [#methods]

### `create(amount:, currency:, source:, tags: nil)` [#createamount-currency-source-tags-nil]

`POST /transfer`. `amount` is in minor units (cents). `source` is a
payment-instrument ID.

```ruby
transfer = client.transfers.create(
  amount:   1_500,
  currency: "USD",
  source:   "pi_…",
  tags:     { order_id: "ord_…" }
)
```

### `update(id, **body)` [#updateid-body]

`PATCH /transfer/:id`. Used primarily to mutate `tags`.

```ruby
client.transfers.update("tr_…", tags: { reconciled: true })
```

### `retrieve(id)` [#retrieveid]

`GET /transfer/:id`.

```ruby
client.transfers.retrieve("tr_…")
```

### `list(limit: nil, offset: nil, ids: nil)` [#listlimit-nil-offset-nil-ids-nil]

`GET /transfer`.

```ruby
client.transfers.list(limit: 100)
```

### `create_refund(transfer_id, refund_amount:, tags: nil)` [#create_refundtransfer_id-refund_amount-tags-nil]

`POST /transfer/:id/reversals`. Issues a refund against an existing
transfer. `refund_amount` is in minor units; pass the full transfer
amount for a complete refund or a smaller value for a partial refund.

```ruby
client.transfers.create_refund(
  "tr_…",
  refund_amount: 500,
  tags:          { reason: "duplicate_charge" }
)
```

## Object shape [#object-shape]

`:id`, `:amount`, `:currency`, `:source`, `:state`, `:created_at`,
`:tags`, … plus a `:reversals` collection that grows as refunds are
issued.

{/* TODO: link to canonical Finix transfer schema. */}

## Examples [#examples]

### Charge a customer's default card [#charge-a-customers-default-card]

```ruby
instruments = client.customers.payment_instruments(customer[:id])[:data] || []
default     = instruments.find { |pi| pi[:default] } || instruments.first
raise "no instrument on file" unless default

client.transfers.create(amount: 2_500, currency: "USD", source: default[:id])
```

### Full refund [#full-refund]

```ruby
charge = client.transfers.retrieve("tr_…")
client.transfers.create_refund(charge[:id], refund_amount: charge[:amount])
```

### Partial refund [#partial-refund]

```ruby
client.transfers.create_refund("tr_…", refund_amount: 500)
```


# Treasury (/docs/sdks/ruby/resources/treasury)



Treasury is the money-movement layer: linked bank accounts, ACH /
wire deposits and withdrawals, recipients (1099 and otherwise), payout
links, recurring payments, security rules, and approval workflows.

The resource keeps a flat method layout — sub-resources (recipients,
transactions, etc.) are exposed as prefixed methods rather than nested
objects, matching the rest of the SDK's convention.

Accessed via `client.treasury`. \~40 endpoints; only the most frequent
are documented here — see the source for the complete list.

## Dashboard [#dashboard]

### `dashboard_summary` [#dashboard_summary]

`GET /treasury/dashboard/summary`.

```ruby
client.treasury.dashboard_summary
```

## Bank accounts [#bank-accounts]

```ruby
client.treasury.list_bank_accounts
client.treasury.bank_account_link_token             # for Plaid Link
client.treasury.link_bank_account(public_token: "…")
client.treasury.delete_bank_account("ba_…")
```

## Deposit [#deposit]

```ruby
client.treasury.deposit_bank_pull(amount: 100_00, source_id: "ba_…")
client.treasury.deposit_wire_instructions
```

## Withdraw [#withdraw]

```ruby
client.treasury.withdraw(amount: 50_000, destination_id: "ba_…")
client.treasury.confirm_withdraw(withdrawal_id: "wd_…")
```

## Transfer (between own accounts) [#transfer-between-own-accounts]

```ruby
client.treasury.transfer(amount: 10_000, source_id: "ba_a", destination_id: "ba_b")
client.treasury.confirm_transfer(transfer_id: "tx_…")
```

## Send (to a recipient) [#send-to-a-recipient]

```ruby
client.treasury.send_payment(amount: 25_000, recipient_id: "rec_…")
client.treasury.confirm_send(send_id: "snd_…")
client.treasury.cancel_send(send_id: "snd_…")
```

## Transactions [#transactions]

```ruby
client.treasury.list_transactions(limit: 100)
client.treasury.retrieve_transaction("tx_…")
client.treasury.update_transaction("tx_…", category_id: "cat_…")
client.treasury.transaction_settlement("tx_…")
client.treasury.export_transactions(start_date: "2026-04-01", end_date: "2026-04-30")
```

## Recipients [#recipients]

Full CRUD plus invitations, auto-pay, payment-method attach, W-9
collection, and bulk import via CSV upload.

```ruby
client.treasury.list_recipients(limit: 50)
client.treasury.create_recipient(first_name: "Pat", last_name: "Lee", email: "pat@example.com")
client.treasury.retrieve_recipient("rec_…")
client.treasury.update_recipient("rec_…", email: "new@example.com")
client.treasury.delete_recipient("rec_…")

client.treasury.invite_recipient("rec_…")
client.treasury.set_recipient_auto_pay("rec_…", enabled: true)
client.treasury.create_recipient_payment_method("rec_…", type: "ACH", account_number: "…", routing_number: "…")
client.treasury.request_recipient_w9("rec_…")
client.treasury.recipient_tax_info("rec_…")
client.treasury.update_recipient_tax_info("rec_…", tin: "…", classification: "individual")

client.treasury.list_recipient_invitations
client.treasury.accept_recipient_invite(invite_token: "…")

client.treasury.recipients_tax_report(year: 2025)

# Plaid for recipient-side bank linking
client.treasury.recipient_plaid_link_token(recipient_id: "rec_…")
client.treasury.recipient_plaid_exchange(recipient_id: "rec_…", public_token: "…")
```

### Bulk import [#bulk-import]

`POST /treasury/recipients/import` is multipart/form-data. Pass `file:`
as a `Net::HTTP::UploadIO` (or any IO-like object the
[`multipart-post`](https://rubygems.org/gems/multipart-post) gem
accepts).

```ruby
require "net/http/post/multipart"

client.treasury.import_recipients(
  file: UploadIO.new(File.open("recipients.csv"), "text/csv", "recipients.csv")
)
```

## Payout links [#payout-links]

```ruby
client.treasury.list_payout_links(limit: 50)
client.treasury.generate_payout_link(amount: 50_000, recipient_email: "pat@example.com")
client.treasury.retrieve_payout_link("pl_token_…")
client.treasury.submit_payout_link("pl_token_…", payment_method_id: "pm_…")
```

## Recurring payments [#recurring-payments]

```ruby
client.treasury.list_recurring_payments(limit: 50)
client.treasury.create_recurring_payment(
  recipient_id: "rec_…", amount: 100_000, interval: "month", interval_count: 1
)
client.treasury.retrieve_recurring_payment("rp_…")
client.treasury.update_recurring_payment("rp_…", amount: 120_000)
client.treasury.delete_recurring_payment("rp_…")
```

## Categories [#categories]

```ruby
client.treasury.list_categories
client.treasury.create_category(name: "Software")
client.treasury.delete_category("cat_…")
client.treasury.category_usage("cat_…")
```

## Security rules [#security-rules]

```ruby
client.treasury.list_security_rules
client.treasury.create_security_rule(rule_type: "max_send_amount", value: 100_000)
client.treasury.update_security_rule("sec_…", value: 250_000)
client.treasury.delete_security_rule("sec_…")
```

## Auto-transfer rules [#auto-transfer-rules]

```ruby
client.treasury.list_auto_transfer_rules
client.treasury.create_auto_transfer_rule(source_id: "ba_a", destination_id: "ba_b", trigger_balance: 500_000)
client.treasury.update_auto_transfer_rule("atr_…", trigger_balance: 1_000_000)
client.treasury.delete_auto_transfer_rule("atr_…")
```

## Approval requests [#approval-requests]

```ruby
client.treasury.create_approval_request(operation: "send", payload: { recipient_id: "rec_…", amount: 100_000 })
client.treasury.resolve_approval_request("ar_…", decision: "approve")
```

## Object shapes [#object-shapes]

Treasury returns rich, varied shapes — bank accounts, transactions,
recipients, etc. all have distinct schemas.

{/* TODO: enumerate the per-resource schemas as the Treasury API reference
  stabilises. */}

## Examples [#examples]

### Pay a contractor and confirm [#pay-a-contractor-and-confirm]

```ruby
recipient = client.treasury.create_recipient(
  first_name: "Pat", last_name: "Lee", email: "pat@example.com"
)
send = client.treasury.send_payment(amount: 250_000, recipient_id: recipient[:id])
client.treasury.confirm_send(send_id: send[:id])
```

### Recurring monthly retainer [#recurring-monthly-retainer]

```ruby
client.treasury.create_recurring_payment(
  recipient_id:   "rec_…",
  amount:         500_000,
  interval:       "month",
  interval_count: 1,
  start_date:     "2026-06-01"
)
```

### Bulk-import recipients from a CSV [#bulk-import-recipients-from-a-csv]

```ruby
require "net/http/post/multipart"

File.open("vendors.csv") do |io|
  client.treasury.import_recipients(
    file: UploadIO.new(io, "text/csv", "vendors.csv")
  )
end
```


# Wallet Checkout (/docs/sdks/ruby/resources/wallet-checkout)



Wallet (crypto) checkout is **not** a separate SDK resource — it shares
the `/checkout` endpoint with card/bank checkout, and the API
discriminates on the body shape. See [Checkout](./checkout) for the
method signature.

```ruby
client.checkout.create(
  customer_creation: false,
  identity_id:       customer[:id],
  # …wallet-specific source fields…
)
```

## Methods [#methods]

`client.checkout.create(**body)` — see [Checkout](./checkout).

## Object shape [#object-shape]

The wallet variant returns the same checkout response envelope plus the
on-chain transaction reference.

{/* TODO: document the wallet-checkout request body and response fields once the canonical schema for the crypto variant is published. */}

## Examples [#examples]

{/* TODO: add a runnable wallet-checkout snippet once the request shape stabilises. */}


# Webhook Endpoints (/docs/sdks/ruby/resources/webhook-endpoints)



Manages the webhook **endpoints** registered on your account — the URLs
Easy Labs POSTs events to. For verifying inbound deliveries see
[Webhooks](../webhooks); this resource is for endpoint CRUD plus
delivery-history reads.

Accessed via `client.webhooks`.

## Methods [#methods]

### `register(url:, events: ["*"])` [#registerurl-events-]

`POST /webhooks&#x60;. Returns the registered endpoint including
&#x2A;*`secret`** — the HMAC signing key. The secret is returned **only on
creation**; capture and store it immediately.

```ruby
endpoint = client.webhooks.register(
  url:    "https://example.com/webhooks/easy",
  events: ["payment.created", "subscription.*"]
)

ENV["EASY_WEBHOOK_SECRET"] = endpoint[:secret]   # store this securely
```

### `list` [#list]

`GET /webhooks`.

```ruby
client.webhooks.list
```

### `update(id, **body)` [#updateid-body]

`PATCH /webhooks/:id`. Common updates: `active:`, `events:`, `url:`.

```ruby
client.webhooks.update("wh_…", active: false)
```

### `delete(id)` [#deleteid]

`DELETE /webhooks/:id`.

```ruby
client.webhooks.delete("wh_…")
```

### `list_deliveries(**query)` [#list_deliveriesquery]

`GET /webhooks/deliveries`. Every delivery across all endpoints. Query
params (e.g. `success: false`, `limit: 50`) are passed through.

```ruby
client.webhooks.list_deliveries(success: false, limit: 50)
```

### `list_endpoint_deliveries(endpoint_id, **query)` [#list_endpoint_deliveriesendpoint_id-query]

`GET /webhooks/:id/deliveries`. Deliveries scoped to one endpoint.

```ruby
client.webhooks.list_endpoint_deliveries("wh_…", limit: 50)
```

## Object shape [#object-shape]

Endpoint — `:id`, `:url`, `:events`, `:active`, `:secret` (only on
create), `:created_at`, …

Delivery — `:id`, `:endpoint_id`, `:event_type`, `:status_code`,
`:success`, `:response_body`, `:attempts`, `:delivered_at`, …

{/* TODO: enumerate the full endpoint + delivery schemas. */}

## Examples [#examples]

### Register and persist the secret [#register-and-persist-the-secret]

```ruby
endpoint = client.webhooks.register(url: "https://example.com/webhooks/easy")
SecretStore.write(:easy_webhook_secret, endpoint[:secret])
```

### Triage failed deliveries [#triage-failed-deliveries]

```ruby
failed = client.webhooks.list_deliveries(success: false, limit: 100)[:data] || []
failed.each { |d| WebhookFailureMailer.alert(d).deliver_later }
```

### Disable an endpoint temporarily [#disable-an-endpoint-temporarily]

```ruby
client.webhooks.update("wh_…", active: false)
# …investigate / fix the receiver…
client.webhooks.update("wh_…", active: true)
```


# Get dispute metrics (/docs/reference/api/account-and-operations/analytics/list-disputes)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/analytics/disputes&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get revenue recovery analytics (/docs/reference/api/account-and-operations/analytics/list-revenue-recovery)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/analytics/revenue-recovery&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get revenue breakdown (/docs/reference/api/account-and-operations/analytics/list-revenue)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/analytics/revenue&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get settlement summary (/docs/reference/api/account-and-operations/analytics/list-settlements)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/analytics/settlements&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get transaction volume analytics (/docs/reference/api/account-and-operations/analytics/list-transactions)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/analytics/transactions&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Preview checkout branding (/docs/reference/api/account-and-operations/branding/create-checkout-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/preview/checkout&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Preview email branding (/docs/reference/api/account-and-operations/branding/create-email)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/preview/email&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Preview invoice branding (/docs/reference/api/account-and-operations/branding/create-invoice)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/preview/invoice&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Preview customer portal branding (/docs/reference/api/account-and-operations/branding/create-portal)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/preview/portal&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Reset branding to Easy defaults (/docs/reference/api/account-and-operations/branding/create-reset-to-defaults)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/reset-to-defaults&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Reset branding to Easy defaults (deprecated alias) (/docs/reference/api/account-and-operations/branding/create-reset)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/reset&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Send a branding test email (/docs/reference/api/account-and-operations/branding/create-test)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/email/test&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Validate branding color or logo URL (/docs/reference/api/account-and-operations/branding/create-validate-3)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/validate&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Register custom email sending domain (/docs/reference/api/account-and-operations/branding/create-verify-domain)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/email/verify-domain&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Clear invoice branding override (/docs/reference/api/account-and-operations/branding/delete-invoice)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/invoice/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Clear payment link branding override (/docs/reference/api/account-and-operations/branding/delete-payment-link-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/payment-link/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Get invoice branding override (/docs/reference/api/account-and-operations/branding/get-invoice-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/invoice/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get payment link branding override (/docs/reference/api/account-and-operations/branding/get-payment-link-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/payment-link/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get branding audit log (/docs/reference/api/account-and-operations/branding/list-audit)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/audit&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get company branding (/docs/reference/api/account-and-operations/branding/list-branding)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List available fonts (/docs/reference/api/account-and-operations/branding/list-list)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/fonts/list&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get domain verification status (/docs/reference/api/account-and-operations/branding/list-verify-domain)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/email/verify-domain&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update company branding (/docs/reference/api/account-and-operations/branding/update-branding)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Update invoice branding override (/docs/reference/api/account-and-operations/branding/update-invoice)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/invoice/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Update payment link branding override (/docs/reference/api/account-and-operations/branding/update-payment-link-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/branding/payment-link/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Create a custom transaction category (/docs/reference/api/account-and-operations/categories/create-categories)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/categories&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Delete a custom transaction category (/docs/reference/api/account-and-operations/categories/delete-categories)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/categories/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Get usage count for a category (/docs/reference/api/account-and-operations/categories/get-usage)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/categories/{id}/usage&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List transaction categories (/docs/reference/api/account-and-operations/categories/list-categories)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/categories&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get communication preferences (/docs/reference/api/account-and-operations/comm-prefs/list-comm-prefs)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/comm-prefs/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update communication preferences (/docs/reference/api/account-and-operations/comm-prefs/update-comm-prefs)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/comm-prefs/&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Create a new company (/docs/reference/api/account-and-operations/companies/create-companies)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/companies/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Complete onboarding (/docs/reference/api/account-and-operations/companies/create-onboarding-complete-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/companies/onboarding-complete&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Ensure company accounts are fully provisioned (/docs/reference/api/account-and-operations/companies/list-ensure-provisioned)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/companies/ensure-provisioned&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Add a custom domain (dashboard) (/docs/reference/api/account-and-operations/custom-domains-dashboard/create-custom-domains)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/custom-domains/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Verify custom domain (dashboard) (/docs/reference/api/account-and-operations/custom-domains-dashboard/create-verify)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/custom-domains/{id}/verify&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Delete custom domain (dashboard) (/docs/reference/api/account-and-operations/custom-domains-dashboard/delete-custom-domains)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/custom-domains/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# List custom domains (dashboard) (/docs/reference/api/account-and-operations/custom-domains-dashboard/list-custom-domains)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/custom-domains/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get dashboard home stats (JWT-only) (/docs/reference/api/account-and-operations/dashboard/list-dashboard-stats)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/dashboard-stats/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Upload file content (/docs/reference/api/account-and-operations/files/create-upload)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/files/{id}/upload&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get a file by ID (/docs/reference/api/account-and-operations/files/get-file)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/files/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List merchant files (/docs/reference/api/account-and-operations/files/list-files)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/files/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Revoke a specific login session (/docs/reference/api/account-and-operations/login-sessions/delete-login-sessions-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/login-sessions/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Sign out all other sessions (/docs/reference/api/account-and-operations/login-sessions/delete-login-sessions)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/login-sessions/&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# List active login sessions (/docs/reference/api/account-and-operations/login-sessions/list-login-sessions)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/login-sessions/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get the authenticated merchant (/docs/reference/api/account-and-operations/merchant/list-merchant)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/merchant/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Create an approval request for a gated transaction (/docs/reference/api/account-and-operations/security-rules/create-approval-requests)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/approval-requests&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Approve or deny an approval request (/docs/reference/api/account-and-operations/security-rules/create-resolve)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/approval-requests/{id}/resolve&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create a security rule (budget, approval, time restriction) (/docs/reference/api/account-and-operations/security-rules/create-security-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/security-rules&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Delete a security rule (/docs/reference/api/account-and-operations/security-rules/delete-security-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/security-rules/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# List security rules (/docs/reference/api/account-and-operations/security-rules/list-security-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/security-rules&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update a security rule (/docs/reference/api/account-and-operations/security-rules/update-security-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/security-rules/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Register a webhook endpoint (/docs/reference/api/account-and-operations/webhooks/create-root)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/webhooks/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Delete a webhook endpoint (/docs/reference/api/account-and-operations/webhooks/delete-root)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/webhooks/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# List webhook deliveries (/docs/reference/api/account-and-operations/webhooks/get-deliverie)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/webhooks/{id}/deliveries&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List webhook deliveries (/docs/reference/api/account-and-operations/webhooks/list-deliveries)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/webhooks/deliveries&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List webhook endpoints (/docs/reference/api/account-and-operations/webhooks/list-root-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/webhooks/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update a webhook endpoint (/docs/reference/api/account-and-operations/webhooks/update-root)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/webhooks/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Create auto-pay schedule for a recipient (/docs/reference/api/billing/auto-pay/create-auto-pay)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/{id}/auto-pay&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create coupon (/docs/reference/api/billing/coupons/create-coupons)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/coupons/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Delete coupon (/docs/reference/api/billing/coupons/delete-coupons)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/coupons/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Get coupon (/docs/reference/api/billing/coupons/get-coupon)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/coupons/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List coupons (/docs/reference/api/billing/coupons/list-coupons)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/coupons/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update coupon (/docs/reference/api/billing/coupons/update-coupons)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/coupons/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Consume customer portal magic link (/docs/reference/api/billing/customer-portal/create-consume)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer-portal/access/consume&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create a one-time handoff code for cross-domain session transfer (/docs/reference/api/billing/customer-portal/create-create)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer-portal/access/handoff/create&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Exchange a handoff code for a session token (single use) (/docs/reference/api/billing/customer-portal/create-exchange)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer-portal/access/handoff/exchange&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create a payment method from an active customer portal session (/docs/reference/api/billing/customer-portal/create-payment-methods)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer-portal/payment-methods&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Consume a revenue recovery link into a customer portal session (/docs/reference/api/billing/customer-portal/create-recovery)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer-portal/access/recovery&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Request customer portal magic link (/docs/reference/api/billing/customer-portal/create-request-link)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer-portal/access/request-link&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Sign out customer portal session (/docs/reference/api/billing/customer-portal/create-sign-out)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer-portal/access/sign-out&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Remove a payment method from an active customer portal session (/docs/reference/api/billing/customer-portal/delete-payment-methods)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer-portal/payment-methods/{instrumentId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Get active customer portal session (/docs/reference/api/billing/customer-portal/list-me)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer-portal/access/me&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get public customer portal context (/docs/reference/api/billing/customer-portal/list-public)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer-portal/public&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update billing information from an active customer portal session (/docs/reference/api/billing/customer-portal/update-billing-information)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer-portal/billing-information&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Get customer portal config (/docs/reference/api/billing/customer-portal-config/list-customer-portal-config)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer-portal-config/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Patch customer portal config (/docs/reference/api/billing/customer-portal-config/update-customer-portal-config)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer-portal-config/&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Create a new invoice (/docs/reference/api/billing/invoices/create-invoices-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/invoices/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create a new invoice (/docs/reference/api/billing/invoices/create-invoices)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/invoices/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Pay an outstanding invoice (/docs/reference/api/billing/invoices/create-pay-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/invoices/{id}/pay&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Pay an outstanding invoice (/docs/reference/api/billing/invoices/create-pay)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/invoices/{id}/pay&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Send invoice reminder (/docs/reference/api/billing/invoices/create-remind-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/invoices/{id}/remind&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Send invoice reminder (/docs/reference/api/billing/invoices/create-remind)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/invoices/{id}/remind&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Send an invoice (/docs/reference/api/billing/invoices/create-send-3)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/invoices/{id}/send&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Send an invoice (/docs/reference/api/billing/invoices/create-send)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/invoices/{id}/send&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Void an invoice (/docs/reference/api/billing/invoices/create-void-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/invoices/{id}/void&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Void an invoice (/docs/reference/api/billing/invoices/create-void-3)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/invoices/{id}/void&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get invoice by ID (/docs/reference/api/billing/invoices/get-invoice-3)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/invoices/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get invoice by ID (/docs/reference/api/billing/invoices/get-invoice)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/invoices/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get invoice data for PDF (/docs/reference/api/billing/invoices/get-pdf-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/invoices/{id}/pdf&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get invoice data for PDF (/docs/reference/api/billing/invoices/get-pdf)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/invoices/{id}/pdf&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# View invoice (public) (/docs/reference/api/billing/invoices/get-view-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/invoices/{id}/view&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# View invoice (public) (/docs/reference/api/billing/invoices/get-view)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/invoices/{id}/view&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Download invoice PDF (public) (/docs/reference/api/billing/invoices/list-download-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/invoices/{id}/pdf/download&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Download invoice PDF (public) (/docs/reference/api/billing/invoices/list-download)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/invoices/{id}/pdf/download&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List invoices (/docs/reference/api/billing/invoices/list-invoices-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/invoices/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List invoices (/docs/reference/api/billing/invoices/list-invoices)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/invoices/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update a draft invoice (/docs/reference/api/billing/invoices/update-invoices-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/invoices/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Update a draft invoice (/docs/reference/api/billing/invoices/update-invoices)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/invoices/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Clone a product (/docs/reference/api/billing/product/create-clone)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/products/{id}/clone&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create a new product price (/docs/reference/api/billing/product/create-product-prices)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/product-prices/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create a new product (/docs/reference/api/billing/product/create-products)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/products/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Delete a product (soft-delete) (/docs/reference/api/billing/product/delete-products)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/products/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Get a product price by ID (/docs/reference/api/billing/product/get-product-price)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/product-prices/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get a product by ID (/docs/reference/api/billing/product/get-product)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/products/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get all product prices (/docs/reference/api/billing/product/list-product-prices)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/product-prices/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get all products (/docs/reference/api/billing/product/list-products)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/products/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Archive a product (/docs/reference/api/billing/product/update-archive-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/products/{id}/archive&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Archive a product price (/docs/reference/api/billing/product/update-archive)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/product-prices/{id}/archive&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Update a product price (/docs/reference/api/billing/product/update-product-prices)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/product-prices/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Update a product (/docs/reference/api/billing/product/update-products)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/products/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Restore an archived product (/docs/reference/api/billing/product/update-restore)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/products/{id}/restore&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Unarchive a product (atomic) (/docs/reference/api/billing/product/update-unarchive)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/products/{id}/unarchive&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Get product by product ID and price ID (/docs/reference/api/billing/products/get-price-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/products/{productId}/prices/{priceId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get all prices for a product (/docs/reference/api/billing/products/get-price)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/products/{productId}/prices&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Create promotion code (/docs/reference/api/billing/promotion-codes/create-promotion-codes)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/promotion-codes/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Validate promotion code (/docs/reference/api/billing/promotion-codes/create-validate-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/promotion-codes/validate&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Delete promotion code (/docs/reference/api/billing/promotion-codes/delete-promotion-codes)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/promotion-codes/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Get promotion code (/docs/reference/api/billing/promotion-codes/get-promotion-code)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/promotion-codes/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List promotion codes (/docs/reference/api/billing/promotion-codes/list-promotion-codes)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/promotion-codes/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update promotion code (/docs/reference/api/billing/promotion-codes/update-promotion-codes)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/promotion-codes/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Create a recurring payment (/docs/reference/api/billing/recurring-payments/create-recurring-payments)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recurring-payments&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Cancel a recurring payment (/docs/reference/api/billing/recurring-payments/delete-recurring-payments)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recurring-payments/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Get a recurring payment by ID (/docs/reference/api/billing/recurring-payments/get-recurring-payment)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recurring-payments/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List recurring payments (/docs/reference/api/billing/recurring-payments/list-recurring-payments)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recurring-payments&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update a recurring payment (pause, resume, cancel, edit) (/docs/reference/api/billing/recurring-payments/update-recurring-payments)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recurring-payments/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Create a subscription plan (legacy compatibility) (/docs/reference/api/billing/subscription-plan/create-subscription-plans)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscription-plans/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get a subscription plan by ID (legacy compatibility) (/docs/reference/api/billing/subscription-plan/get-subscription-plan)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscription-plans/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get subscription plans (legacy compatibility) (/docs/reference/api/billing/subscription-plan/list-subscription-plans)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscription-plans/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update a subscription plan (legacy compatibility) (/docs/reference/api/billing/subscription-plan/update-subscription-plans)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscription-plans/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Apply discount to subscription (/docs/reference/api/billing/subscriptions/create-discounts)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{id}/discounts&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create or replace revenue recovery config (/docs/reference/api/billing/subscriptions/create-dunning-config)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/dunning-config/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Add item to subscription (/docs/reference/api/billing/subscriptions/create-items)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{id}/items&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create one-time charge for subscription (/docs/reference/api/billing/subscriptions/create-one-time-charges)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{id}/one-time-charges&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Pause a subscription (/docs/reference/api/billing/subscriptions/create-pause)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{id}/pause&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Resume a subscription (/docs/reference/api/billing/subscriptions/create-resume)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{id}/resume&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create revenue recovery automation (/docs/reference/api/billing/subscriptions/create-revenue-recovery-automations)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/revenue-recovery-automations/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create or replace revenue recovery config (/docs/reference/api/billing/subscriptions/create-revenue-recovery-config)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/revenue-recovery-config/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create a subscription (/docs/reference/api/billing/subscriptions/create-subscriptions)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Report metered usage (/docs/reference/api/billing/subscriptions/create-usage)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{subscription_id}/usage&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Remove subscription discount (/docs/reference/api/billing/subscriptions/delete-discounts)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{id}/discounts/{discount_id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Remove subscription item (/docs/reference/api/billing/subscriptions/delete-items)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{id}/items/{item_id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Delete revenue recovery automation (/docs/reference/api/billing/subscriptions/delete-revenue-recovery-automations)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/revenue-recovery-automations/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Cancel a subscription (/docs/reference/api/billing/subscriptions/delete-subscriptions)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# List subscription discounts (/docs/reference/api/billing/subscriptions/get-discount)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{id}/discounts&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Preview proration for subscription updates (/docs/reference/api/billing/subscriptions/get-proration-preview)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{id}/proration-preview&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List revenue recovery automation runs (/docs/reference/api/billing/subscriptions/get-run)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/revenue-recovery-automations/{id}/runs&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get a subscription (/docs/reference/api/billing/subscriptions/get-subscription-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get revenue recovery config (/docs/reference/api/billing/subscriptions/list-dunning-config)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/dunning-config/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Reconcile usage billing for a period (/docs/reference/api/billing/subscriptions/list-reconciliation)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{subscription_id}/usage/reconciliation&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List revenue recovery automations (/docs/reference/api/billing/subscriptions/list-revenue-recovery-automations)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/revenue-recovery-automations/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get revenue recovery config (/docs/reference/api/billing/subscriptions/list-revenue-recovery-config)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/revenue-recovery-config/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List subscriptions (/docs/reference/api/billing/subscriptions/list-subscriptions)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get usage summary (/docs/reference/api/billing/subscriptions/list-summary)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{subscription_id}/usage/summary&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Patch revenue recovery config (/docs/reference/api/billing/subscriptions/update-dunning-config)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/dunning-config/&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Update subscription item quantity (/docs/reference/api/billing/subscriptions/update-items)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{id}/items/{item_id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Update revenue recovery automation (/docs/reference/api/billing/subscriptions/update-revenue-recovery-automations)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/revenue-recovery-automations/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Patch revenue recovery config (/docs/reference/api/billing/subscriptions/update-revenue-recovery-config)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/revenue-recovery-config/&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Update a subscription (/docs/reference/api/billing/subscriptions/update-subscriptions)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/subscriptions/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Create an authorization (/docs/reference/api/payments/authorization/create-authorizations)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/authorizations/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Capture an authorization (/docs/reference/api/payments/authorization/create-capture)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/authorizations/{id}/capture&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Void an authorization (/docs/reference/api/payments/authorization/create-void)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/authorizations/{id}/void&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get an authorization by ID (/docs/reference/api/payments/authorization/get-authorization)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/authorizations/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List authorizations (/docs/reference/api/payments/authorization/list-authorizations)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/authorizations/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Create a checkout session (/docs/reference/api/payments/checkout/create-checkout)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/checkout/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get checkout slug (/docs/reference/api/payments/checkout-slug/list-checkout-slug)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/checkout-slug/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update checkout slug (/docs/reference/api/payments/checkout-slug/update-checkout-slug)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/auth/checkout-slug/&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Create a new customer (/docs/reference/api/payments/customer/create-customer)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get a customer by ID (/docs/reference/api/payments/customer/get-customer)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get all payment instruments for a customer (/docs/reference/api/payments/customer/get-instrument)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer/{id}/instruments&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get all orders for a customer (/docs/reference/api/payments/customer/get-order)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer/{id}/orders&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get all subscriptions for a customer (/docs/reference/api/payments/customer/get-subscription)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer/{id}/subscriptions&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get all wallets for a customer (/docs/reference/api/payments/customer/get-wallet)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer/{id}/wallets&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get all customers (/docs/reference/api/payments/customer/list-customer)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update a customer (/docs/reference/api/payments/customer/update-customer)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/customer/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Accept a dispute (/docs/reference/api/payments/dispute/create-accept)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/disputes/{id}/accept&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Upload dispute evidence (/docs/reference/api/payments/dispute/create-evidence)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/disputes/{id}/evidence&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Submit dispute evidence (/docs/reference/api/payments/dispute/create-submit)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/disputes/{id}/submit&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get a dispute by ID (/docs/reference/api/payments/dispute/get-dispute)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/disputes/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List dispute evidence files (/docs/reference/api/payments/dispute/get-evidence)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/disputes/{id}/evidence&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get disputes (/docs/reference/api/payments/dispute/list-disputes-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/disputes/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update dispute tags (/docs/reference/api/payments/dispute/update-disputes)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/disputes/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Confirm payment for an embedded checkout session (/docs/reference/api/payments/embedded-checkout/create-confirm)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/embedded-checkout/confirm&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create an embedded checkout session (/docs/reference/api/payments/embedded-checkout/create-embedded-checkout)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/embedded-checkout/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Validate an embedded checkout session (/docs/reference/api/payments/embedded-checkout/create-validate)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/embedded-checkout/validate&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get crypto payment status for a checkout session (/docs/reference/api/payments/embedded-checkout/get-crypto-statu)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/embedded-checkout/{id}/crypto-status&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Retrieve an embedded checkout session (/docs/reference/api/payments/embedded-checkout/get-embedded-checkout)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/embedded-checkout/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get embedded checkout configuration (/docs/reference/api/payments/embedded-checkout/list-config)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/embedded-checkout/config&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update embedded checkout configuration (/docs/reference/api/payments/embedded-checkout/update-config)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/embedded-checkout/config&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Get an order by ID (/docs/reference/api/payments/order/get-order-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/orders/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get orders (/docs/reference/api/payments/order/list-orders)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/orders/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update order tags (/docs/reference/api/payments/order/update-orders)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/orders/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Create a payment instrument (Basis Theory proxy) (/docs/reference/api/payments/payment-instrument/create-payment-instruments)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/payment-instruments/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get a payment instrument by ID (/docs/reference/api/payments/payment-instrument/get-payment-instrument)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/payment-instruments/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List payment instruments (/docs/reference/api/payments/payment-instrument/list-payment-instruments)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/payment-instruments/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update a payment instrument (/docs/reference/api/payments/payment-instrument/update-payment-instruments)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/payment-instruments/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Create a payment link (/docs/reference/api/payments/payment-link/create-payment-link)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/payment-link/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Deactivate a payment link (/docs/reference/api/payments/payment-link/delete-payment-link)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/payment-link/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Retrieve a payment link (/docs/reference/api/payments/payment-link/get-payment-link)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/payment-link/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List payments for a payment link (/docs/reference/api/payments/payment-link/get-payment)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/payment-link/{id}/payments&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List payment links (/docs/reference/api/payments/payment-link/list-payment-link)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/payment-link/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update a payment link (/docs/reference/api/payments/payment-link/update-payment-link)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/payment-link/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Create a session (/docs/reference/api/payments/sessions/create-sessions)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/sessions/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create a refund (reversal) (/docs/reference/api/payments/transfer/create-reversals)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/transfer/{id}/reversals&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create a transfer (/docs/reference/api/payments/transfer/create-transfer)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/transfer/&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get a transfer by ID (/docs/reference/api/payments/transfer/get-transfer)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/transfer/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get transfers (/docs/reference/api/payments/transfer/list-transfer)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/transfer/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update transfer tags (/docs/reference/api/payments/transfer/update-transfer)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/transfer/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Create an auto-transfer rule (/docs/reference/api/treasury/auto-transfer-rules/create-auto-transfer-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/auto-transfer-rules&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Delete an auto-transfer rule (/docs/reference/api/treasury/auto-transfer-rules/delete-auto-transfer-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/auto-transfer-rules/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# List auto-transfer rules (/docs/reference/api/treasury/auto-transfer-rules/list-auto-transfer-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/auto-transfer-rules&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update an auto-transfer rule (/docs/reference/api/treasury/auto-transfer-rules/update-auto-transfer-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/auto-transfer-rules/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Link a bank account via Plaid (/docs/reference/api/treasury/bank-accounts/create-link)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/bank-accounts/link&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Deactivate a linked bank account (/docs/reference/api/treasury/bank-accounts/delete-bank-accounts)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/bank-accounts/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# List linked bank accounts (/docs/reference/api/treasury/bank-accounts/list-bank-accounts)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/bank-accounts&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get a Plaid Link token (/docs/reference/api/treasury/bank-accounts/list-link-token)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/bank-accounts/link-token&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Generate a shareable payout link (/docs/reference/api/treasury/payout-link/create-generate)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/payout-link/generate&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Submit banking details via payout link (public) (/docs/reference/api/treasury/payout-link/create-submit-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/payout-link/{token}/submit&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get payout link details (public) (/docs/reference/api/treasury/payout-link/get-payout-link)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/payout-link/{token}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List payout links (/docs/reference/api/treasury/payout-link/list-payout-links)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/payout-links&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Exchange Plaid public token for recipient bank linking (/docs/reference/api/treasury/recipient-plaid/create-exchange-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/plaid/exchange&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get a Plaid Link token for recipient self-service (/docs/reference/api/treasury/recipient-plaid/create-link-token)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/plaid/link-token&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get a settlement by ID (/docs/reference/api/treasury/settlement/get-settlement)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/settlements/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get settlements (/docs/reference/api/treasury/settlement/list-settlements-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/settlements/&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Close a settlement (/docs/reference/api/treasury/settlement/update-settlements)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/settlements/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Calculate sales tax (/docs/reference/api/treasury/tax/create-calculate)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/tax/calculate&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Send a W-9 request email to a recipient (/docs/reference/api/treasury/tax-documents/create-request-w9)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/{id}/request-w9&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Update tax information for a recipient (/docs/reference/api/treasury/tax-documents/create-tax-info)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/{id}/tax-info&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get tax information for a recipient (/docs/reference/api/treasury/tax-documents/get-tax-info)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/{id}/tax-info&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get tax compliance report for all recipients (/docs/reference/api/treasury/tax-documents/list-tax-report)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/tax-report&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Accept recipient invitation (public) (/docs/reference/api/treasury/treasury/create-accept-invite)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/accept-invite&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create an approval request for a gated transaction (/docs/reference/api/treasury/treasury/create-approval-requests)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/approval-requests&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create auto-pay schedule for a recipient (/docs/reference/api/treasury/treasury/create-auto-pay)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/{id}/auto-pay&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create an auto-transfer rule (/docs/reference/api/treasury/treasury/create-auto-transfer-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/auto-transfer-rules&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Pull funds from a linked bank account (ACH) (/docs/reference/api/treasury/treasury/create-bank-pull)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/deposit/bank-pull&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Cancel a pending send operation (/docs/reference/api/treasury/treasury/create-cancel)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/send/cancel&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create a custom transaction category (/docs/reference/api/treasury/treasury/create-categories)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/categories&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Confirm a send operation (with optional 2FA code) (/docs/reference/api/treasury/treasury/create-confirm-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/send/confirm&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Confirm an external transfer (with optional 2FA code) (/docs/reference/api/treasury/treasury/create-confirm-3)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/transfer/confirm&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Confirm a withdrawal (with optional 2FA code) (/docs/reference/api/treasury/treasury/create-confirm-4)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/withdraw/confirm&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Exchange Plaid public token for recipient bank linking (/docs/reference/api/treasury/treasury/create-exchange-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/plaid/exchange&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Generate a shareable payout link (/docs/reference/api/treasury/treasury/create-generate)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/payout-link/generate&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Bulk import recipients from CSV (/docs/reference/api/treasury/treasury/create-import)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/import&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Send invitation email to a recipient (/docs/reference/api/treasury/treasury/create-invite)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/{id}/invite&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get a Plaid Link token for recipient self-service (/docs/reference/api/treasury/treasury/create-link-token)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/plaid/link-token&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Link a bank account via Plaid (/docs/reference/api/treasury/treasury/create-link)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/bank-accounts/link&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Add a payment method to a recipient (/docs/reference/api/treasury/treasury/create-payment-methods-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/{id}/payment-methods&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create a recipient with payment methods (/docs/reference/api/treasury/treasury/create-recipients)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create a recurring payment (/docs/reference/api/treasury/treasury/create-recurring-payments)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recurring-payments&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Send a W-9 request email to a recipient (/docs/reference/api/treasury/treasury/create-request-w9)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/{id}/request-w9&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Approve or deny an approval request (/docs/reference/api/treasury/treasury/create-resolve)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/approval-requests/{id}/resolve&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create a security rule (budget, approval, time restriction) (/docs/reference/api/treasury/treasury/create-security-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/security-rules&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Initiate a send money operation (/docs/reference/api/treasury/treasury/create-send-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/send&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Submit banking details via payout link (public) (/docs/reference/api/treasury/treasury/create-submit-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/payout-link/{token}/submit&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Update tax information for a recipient (/docs/reference/api/treasury/treasury/create-tax-info)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/{id}/tax-info&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Initiate a fund transfer (internal or external) (/docs/reference/api/treasury/treasury/create-transfer-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/transfer&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Initiate a withdrawal to an external bank (/docs/reference/api/treasury/treasury/create-withdraw)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/withdraw&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Delete an auto-transfer rule (/docs/reference/api/treasury/treasury/delete-auto-transfer-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/auto-transfer-rules/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Deactivate a linked bank account (/docs/reference/api/treasury/treasury/delete-bank-accounts)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/bank-accounts/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Delete a custom transaction category (/docs/reference/api/treasury/treasury/delete-categories)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/categories/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Delete a recipient (/docs/reference/api/treasury/treasury/delete-recipients)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Cancel a recurring payment (/docs/reference/api/treasury/treasury/delete-recurring-payments)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recurring-payments/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Delete a security rule (/docs/reference/api/treasury/treasury/delete-security-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/security-rules/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


# Get payout link details (public) (/docs/reference/api/treasury/treasury/get-payout-link)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/payout-link/{token}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get a recipient by ID (/docs/reference/api/treasury/treasury/get-recipient)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get a recurring payment by ID (/docs/reference/api/treasury/treasury/get-recurring-payment)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recurring-payments/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get settlement/fees breakdown for a transaction (/docs/reference/api/treasury/treasury/get-settlement-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/transactions/{id}/settlement&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get tax information for a recipient (/docs/reference/api/treasury/treasury/get-tax-info)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/{id}/tax-info&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get full transaction detail with settlement breakdown (/docs/reference/api/treasury/treasury/get-transaction)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/transactions/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get usage count for a category (/docs/reference/api/treasury/treasury/get-usage)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/categories/{id}/usage&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List auto-transfer rules (/docs/reference/api/treasury/treasury/list-auto-transfer-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/auto-transfer-rules&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List linked bank accounts (/docs/reference/api/treasury/treasury/list-bank-accounts)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/bank-accounts&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List transaction categories (/docs/reference/api/treasury/treasury/list-categories)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/categories&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Export transactions as CSV (/docs/reference/api/treasury/treasury/list-export)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/transactions/export&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List recipient invitations (/docs/reference/api/treasury/treasury/list-invitations)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/invitations&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get a Plaid Link token (/docs/reference/api/treasury/treasury/list-link-token)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/bank-accounts/link-token&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List payout links (/docs/reference/api/treasury/treasury/list-payout-links)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/payout-links&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List recipients (/docs/reference/api/treasury/treasury/list-recipients)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List recurring payments (/docs/reference/api/treasury/treasury/list-recurring-payments)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recurring-payments&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List security rules (/docs/reference/api/treasury/treasury/list-security-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/security-rules&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get treasury dashboard summary (/docs/reference/api/treasury/treasury/list-summary-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/dashboard/summary&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get tax compliance report for all recipients (/docs/reference/api/treasury/treasury/list-tax-report)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/tax-report&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# List treasury transactions with cursor-based pagination (/docs/reference/api/treasury/treasury/list-transactions-2)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/transactions&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get wire transfer instructions for an Easy account (/docs/reference/api/treasury/treasury/list-wire-instructions)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/deposit/wire-instructions&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Update an auto-transfer rule (/docs/reference/api/treasury/treasury/update-auto-transfer-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/auto-transfer-rules/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Update a recipient (/docs/reference/api/treasury/treasury/update-recipients)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recipients/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Update a recurring payment (pause, resume, cancel, edit) (/docs/reference/api/treasury/treasury/update-recurring-payments)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/recurring-payments/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Update a security rule (/docs/reference/api/treasury/treasury/update-security-rules)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/security-rules/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />


# Update transaction metadata (category, receipt) (/docs/reference/api/treasury/treasury/update-transactions)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/vercel/path1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/v1/api/treasury/transactions/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;}]" />