Marlin TypeScript SDK overview

Learn what @marlin/sdk exports, how to configure the Marlin client, and how to create your first invoice in a few lines of TypeScript.

@marlin/sdk is the official TypeScript and Node.js client for the Marlin API. It gives you typed access to every Marlin resource — invoices, plans, subscriptions, and customers — and includes a standalone webhook verification helper and React bindings so you can add stablecoin billing to any project without writing raw HTTP calls. The SDK runs in Node.js 18+ and in any environment that supports the fetch and crypto globals.

Resources

Each resource lives as a property on the Marlin instance and maps directly to a Marlin API surface.

Property	Methods
marlin.invoices	create, retrieve, list, void, send
marlin.plans	create, retrieve, list, update
marlin.subscriptions	list, retrieve, pause, resume, cancel
marlin.customers	create, retrieve, list, update

Standalone functions

Function	Description
verifyWebhook	Verifies the marlin-signature header and returns the parsed WebhookEvent. Throws MarlinWebhookVerificationError on failure.

Error classes

Class	Extends	When thrown
MarlinError	Error	Base class for all Marlin errors.
MarlinAPIError	MarlinError	An HTTP request to the API returned a non-2xx status. Includes .statusCode, .code, and .details.
MarlinWebhookVerificationError	MarlinError	Webhook signature verification fails (bad signature, expired timestamp, malformed header).

Constructor options

Pass a MarlinConfig object to new Marlin().

apiKey · string · required

Your Marlin secret API key. Retrieve it from the Marlin dashboard. Never expose this key in client-side code.

baseUrl · string · default: "https://api.marlin.dev"

Override the API base URL. Useful when pointing at a staging environment.

timeout · number · default: "30000"

Request timeout in milliseconds. Requests that exceed this value are aborted and retried according to maxRetries.

maxRetries · number · default: "2"

Maximum number of retry attempts on 500, 502, 503, and 504 responses. Retries use exponential backoff capped at 5 seconds.

Hello World

The snippet below creates an invoice and logs the hosted payment URL your customer uses to complete the transaction.

import { Marlin } from "@marlin/sdk";

const marlin = new Marlin({ apiKey: process.env.MARLIN_API_KEY! });

const invoice = await marlin.invoices.create({
  customerId: "cus_abc123",
  lineItems: [
    { description: "Pro Plan — May 2025", quantity: 1, unitAmount: 4900 },
  ],
});

console.log(invoice.id, invoice.paymentUrl);

Next steps

• Install and configure @marlin/sdk — package manager setup, all resource methods with examples, error handling, and pagination.
• Use Marlin in React — MarlinProvider, MarlinCheckoutButton, and the useMarlinCheckout hook.