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. For shareable hosted pages, see Payment Links.

Methods

`checkout(session)`

POST /checkout. Returns ApiResponse<{ transfer?: TransferData; orderId?: string; subscriptions: (SubscriptionData & { order_id: string; order_number: string })[] }>.

The request body is a discriminated union (CreateCheckoutSession):

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

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

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

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

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

Mixed cart (one-time + subscription)

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

// 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;
  }
}

Checkout

On this page