Marlin REST API reference

Complete reference for the Marlin REST API. Authenticate with a Bearer token, paginate with cursors, and integrate stablecoin billing into your application.

The Marlin REST API gives you programmatic access to every resource in your merchant account — invoices, subscription plans, subscriptions, and customers. All requests go over HTTPS and return JSON. The API is versioned; the current version is v1, reflected in the base URL below.

Base URL

https://api.marlin.dev

All endpoints documented here are relative to this base URL.

Authentication

Every request to the Marlin API must include a secret API key in the Authorization header. You create and manage API keys from the Settings → API Keys endpoints or from the dashboard.

Authorization: Bearer sk_live_...

Never expose your secret key in client-side code or version control. Rotate a key immediately if it is compromised.

curl

curl https://api.marlin.dev/api/invoices \
  --header "Authorization: Bearer sk_live_abc123"

Versioning

The current API version is v1. Breaking changes will be introduced on a new version with a deprecation period for the previous one. Non-breaking additions — new optional fields, new endpoints — may be made to the current version at any time.

Pagination

All list endpoints use cursor-based pagination. Pass cursor as a query parameter to fetch the next page; the value comes from nextCursor in the previous response. When nextCursor is null, you have reached the last page.

cursor · string

Opaque cursor returned by the previous page. Omit to fetch the first page.

limit · number · default: "20"

Maximum number of objects to return. Accepted range varies by endpoint.

Example paginated response

{
  "data": [
    { "id": "01HXYZ...", "object": "invoice", "..." }
  ],
  "nextCursor": "01HXYZ_NEXT"
}

Iterate through all pages:

TypeScript SDK

let cursor: string | undefined;

do {
  const page = await marlin.invoices.list({ cursor, limit: 50 });
  process(page.data);
  cursor = page.nextCursor ?? undefined;
} while (cursor);

Rate limits

The API enforces per-key rate limits. When you exceed the limit, the API responds with 429 Too Many Requests. Three response headers communicate your current quota on every request:

Header	Description
X-RateLimit-Limit	Total requests allowed in the current window
X-RateLimit-Remaining	Requests remaining before you are throttled
X-RateLimit-Reset	Unix timestamp (seconds) when the window resets

Implement exponential back-off and check X-RateLimit-Reset before retrying.

Resources

Use the links below to jump to the reference page for each resource group.

Invoices

Create, list, retrieve, and void stablecoin invoices.

Plans

Manage subscription plans that customers can subscribe to.

Subscriptions

Pause, resume, and cancel customer subscriptions.

Customers

Create and manage the customer records attached to your account.

Settings

Manage API keys and configure your webhook endpoint.

Errors

Understand error codes, HTTP status codes, and SDK exceptions.