Checkout Page JavaScript SDK

Official JavaScript/TypeScript SDK for the Checkout Page API.

Installation

npm install @checkoutpage/sdk

Or using pnpm:

pnpm add @checkoutpage/sdk

Or using yarn:

yarn add @checkoutpage/sdk

Quick Start

import { createCheckoutPageClient } from '@checkoutpage/sdk';

const checkoutpage = createCheckoutPageClient({ apiKey: 'YOUR_API_KEY' });

// Get a customer
const customer = await checkoutpage.customers.get('customer_id');
console.log(customer);

Authentication

The SDK requires an API key for authentication. You can obtain your API key from the Checkout Page Dashboard.

const checkoutpage = createCheckoutPageClient({
  apiKey: process.env.CHECKOUTPAGE_API_KEY,
});

Custom Base URL

For testing or custom environments, you can override the base URL:

const checkoutpage = createCheckoutPageClient({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://custom-api.example.com',
});

Usage

Customers

Get a customer

const customer = await checkoutpage.customers.get('6812fe6e9f39b6760576f01c');

List customers

const results = await checkoutpage.customers.list();

Coupons

List coupons

const results = await checkoutpage.coupons.list();

With pagination and filtering:

const results = await checkoutpage.coupons.list({
  search: '10off',
  limit: 50,
});

With cursor-based pagination:

const firstPage = await checkoutpage.coupons.list({ limit: 50 });

const nextPage = await checkoutpage.coupons.list({
  limit: 50,
  starting_after: firstPage.data[firstPage.data.length - 1].id,
});

const previousPage = await checkoutpage.coupons.list({
  limit: 50,
  ending_before: nextPage.data[0].id,
});

Create coupon

const results = await checkoutpage.coupons.create({
  type: 'amount',
  label: 'Spring Sale',
  code: 'SPRING25',
  amountOff: 2500,
  currency: 'usd',
  duration: 'once',
});

Subscriptions

List subscriptions

const results = await checkoutpage.subscriptions.list();

With pagination and filtering:

const results = await checkoutpage.subscriptions.list({
  search: '[email protected]',
  status: 'active',
  pageId: '67fcbdac6a91c25ef2d3534a',
  limit: 50,
});

With cursor-based pagination:

const firstPage = await checkoutpage.subscriptions.list({ limit: 50 });

const nextPage = await checkoutpage.subscriptions.list({
  limit: 50,
  starting_after: firstPage.data[firstPage.data.length - 1].id,
});

const previousPage = await checkoutpage.subscriptions.list({
  limit: 50,
  ending_before: nextPage.data[0].id,
});

Payments

List payments

const results = await checkoutpage.payments.list();

With cursor-based pagination:

const firstPage = await checkoutpage.payments.list({ limit: 50 });

const nextPage = await checkoutpage.payments.list({
  limit: 50,
  starting_after: firstPage.data[firstPage.data.length - 1].id,
});

const previousPage = await checkoutpage.payments.list({
  limit: 50,
  ending_before: firstPage.data[0].id,
});

Bookings

List bookings

const results = await checkoutpage.bookings.list();

Filter by status

const paidBookings = await checkoutpage.bookings.list({
  status: 'paid',
  limit: 25,
});

Filter by page

const pageBookings = await checkoutpage.bookings.list({
  pageId: '67fcbdac6a91c25ef2d3534a',
});

Products

Get a product

const product = await checkoutpage.products.get('product_id');

Update a product

const updated = await checkoutpage.products.update('product_id', {
  title: 'Updated Product Title',
  description: 'Updated description',
  price: 5900, // $59.00 in cents
  stock: 100,
  hasUnlimitedStock: false,
});

Files

Upload an image

const imageFile = new File([blob], 'product-image.jpg', { type: 'image/jpeg' });

const result = await checkoutpage.files.upload({
  file: imageFile,
  purpose: 'image',
});

console.log('Image uploaded:', result.data.id, result.data.location);

Upload a file

const pdfFile = new File([blob], 'ebook.pdf', { type: 'application/pdf' });

const result = await checkoutpage.files.upload({
  file: pdfFile,
  purpose: 'file',
});

console.log('File uploaded:', result.data.id);

Error Handling

The SDK provides typed error classes for different error scenarios:

import {
  CheckoutPageError,
  AuthenticationError,
  NotFoundError,
  ConflictError,
  RateLimitError,
  ValidationError,
  APIError,
} from '@checkoutpage/sdk';

try {
  const customer = await checkoutpage.customers.get('customer_id');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof NotFoundError) {
    console.error('Customer not found');
  } else if (error instanceof ConflictError) {
    console.error('Resource already exists');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded');
  } else if (error instanceof ValidationError) {
    console.error('Validation error');
  } else if (error instanceof APIError) {
    console.error('API error:', error.statusCode, error.message);
  }
}

Error Types

• CheckoutPageError - Base error class
• AuthenticationError - Invalid API key or authentication failure (401, 403)
• NotFoundError - Resource not found (404)
• ConflictError - Resource already exists (409)
• RateLimitError - Rate limit exceeded (429)
• ValidationError - Request validation failed (400, 422)
• APIError - Generic API error with status code and response

TypeScript Support

The SDK is written in TypeScript and provides full type definitions auto-generated from the OpenAPI specification:

import type { Customer, Address, Shipping } from '@checkoutpage/sdk';

const customer: Customer = await checkoutpage.customers.get('customer_id');

Advanced Type Usage

Access all generated types for advanced use cases:

import type { operations, components, paths } from '@checkoutpage/sdk';

// Get request type for an operation
type CreateCouponRequest =
  operations['coupons/create']['requestBody']['content']['application/json'];

// Get response type
type ListCustomersResponse =
  operations['customers/list']['responses'][200]['content']['application/json'];

// Access schema components
type CustomerId = components['schemas']['CustomerId'];

See TYPE_GENERATION.md for more details on working with generated types.

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0.0 (if using TypeScript)

Examples

See the examples directory for more usage examples.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT

Support

• Documentation: https://docs.checkoutpage.com
• GitHub Issues: https://github.com/checkout-page/checkoutpage-api-sdk/issues
• Email: [email protected]