Skip to main content

Documentation Index

Fetch the complete documentation index at: https://yanhgming.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

A subscription is created when a customer authorizes recurring charges by visiting a plan’s hosted checkout URL and signing an on-chain delegation transaction. Once created, Marlin charges the subscription automatically at each interval without requiring further customer interaction. You use these API endpoints to list subscriptions and control their lifecycle from the merchant side.

​
Subscription statuses

StatusDescription
ActiveCharging normally. Marlin will attempt to collect the next charge at currentPeriodEnd.
PastDuePaused via the API, or a charge attempt failed. No new charges are attempted until resumed.
CancelledThe subscription has been canceled and will never charge again.
CompletedThe subscription completed its authorized term.

​
GET /api/subscriptions

List all subscriptions associated with plans that belong to your merchant account, ordered newest-first.

​
Query parameters

​
status
string
Filter by subscription status. One of Active, PastDue, Cancelled, or Completed.

​
Response — 200 OK

Returns an array of subscription objects. Each object includes a nested plan snapshot with id, label, amount, mint, and intervalSeconds, and a nested customer snapshot with id, walletAddress, and label.
​
id
string
Database UUID for the subscription.
​
planId
string
ID of the plan this subscription belongs to.
​
customerId
string
ID of the subscribing customer.
​
status
string
Current subscription status.
​
cancelledAt
string | null
ISO 8601 timestamp of cancellation, or null.
​
plan
object
Nested plan snapshot.
​
customer
object
Nested customer snapshot.
​
createdAt
string
ISO 8601 creation timestamp.
​
updatedAt
string
ISO 8601 last-updated timestamp.
curl "https://api.marlin.dev/api/subscriptions?status=Active" \
  --header "Authorization: Bearer sk_live_abc123"

​
POST /api/subscriptions/:id/pause

Pause an active subscription. The subscription status transitions from Active to PastDue. No further charges are attempted while the subscription is paused. Call resume to restart charging.
Pausing a subscription does not affect the customer’s on-chain delegate authorization. The authorization remains valid and resumes charging immediately when you call resume.

​
Path parameters

​
id
string
required
The subscription’s database UUID.

​
Response — 200 OK

Returns the updated subscription object with status: "PastDue". Error cases
  • NOT_FOUND (404) — The subscription does not exist or does not belong to your account.
  • VALIDATION_ERROR (400) — The subscription is not currently Active and cannot be paused.
Status transition 
Active → PastDue

curl --request POST \
  https://api.marlin.dev/api/subscriptions/01HXYZ/pause \
  --header "Authorization: Bearer sk_live_abc123"

​
POST /api/subscriptions/:id/resume

Resume a paused subscription. The subscription status transitions from PastDue back to Active, and Marlin will process the next scheduled charge.

​
Path parameters

​
id
string
required
The subscription’s database UUID.

​
Response — 200 OK

Returns the updated subscription object with status: "Active". Error cases
  • NOT_FOUND (404) — The subscription does not exist or does not belong to your account.
  • VALIDATION_ERROR (400) — The subscription is not in PastDue status and cannot be resumed.
Status transition 
PastDue → Active

curl --request POST \
  https://api.marlin.dev/api/subscriptions/01HXYZ/resume \
  --header "Authorization: Bearer sk_live_abc123"

​
POST /api/subscriptions/:id/cancel

Cancel a subscription permanently. The status transitions to Cancelled and a cancelledAt timestamp is recorded. Canceled subscriptions cannot be resumed — the customer must subscribe again.
Canceling a subscription is irreversible via the API. The customer’s on-chain delegate authorization is also revoked, preventing any future automated charges.

​
Path parameters

​
id
string
required
The subscription’s database UUID.

​
Response — 200 OK

Returns the updated subscription object with status: "Cancelled" and cancelledAt populated. Error cases
  • NOT_FOUND (404) — The subscription does not exist or does not belong to your account.
  • VALIDATION_ERROR (400) — The subscription is already Cancelled or Completed.
Status transition 
Active | PastDue | Trialing → Cancelled

curl --request POST \
  https://api.marlin.dev/api/subscriptions/01HXYZ/cancel \
  --header "Authorization: Bearer sk_live_abc123"