REST API endpoints for subscription plans

Create, list, and update subscription plans. Plans define the amount, stablecoin, and billing interval that customers authorize when they subscribe.

A subscription plan is the template that governs how and when a customer is charged. When you create a plan, Marlin records it in the database and returns an unsignedTx you sign and submit to register the plan as an on-chain PDA. Customers subscribe to a plan via the hosted checkout URL returned as checkoutUrl. Plans support any billing interval expressed in seconds — for example, 86400 for daily, 2592000 for monthly.

---

POST /api/plans

Create a new subscription plan.

Request body

label · string · required

Human-readable plan name shown to customers at checkout (1–100 characters).

mint · string · required

Stablecoin denomination. One of USDC, PYUSD, or USDG.

amount · string · required

Billing amount as a decimal string, e.g. "49.00". Up to 6 decimal places. This is the amount charged each billing period.

intervalSeconds · number · required

Billing interval in seconds. Minimum 86400 (one day). For example: 2592000 for a 30-day month.

description · string

Optional description of what the plan includes (max 500 characters).

Response — 201 Created

plan · object · required

The created plan object.

Hide plan fields

id · string

Database UUID.

onchainId · string

Hex-encoded ULID that identifies the plan on-chain.

merchantId · string

Your merchant account ID.

label · string

Plan display name.

description · string | null

Plan description.

mint · string

Stablecoin: USDC, PYUSD, or USDG.

amount · string

Billing amount as a decimal string.

intervalSeconds · number

Billing interval in seconds.

active · boolean

Whether the plan accepts new subscribers. Defaults to true.

createdAt · string

ISO 8601 creation timestamp.

updatedAt · string

ISO 8601 last-updated timestamp.

unsignedTx · string

Base64-encoded unsigned Solana transaction. Sign this with your merchant wallet and submit it to register the plan on-chain.

curl

curl --request POST https://api.marlin.dev/api/plans \
  --header "Authorization: Bearer sk_live_abc123" \
  --header "Content-Type: application/json" \
  --data '{
    "label": "Pro Monthly",
    "mint": "USDC",
    "amount": "49.00",
    "intervalSeconds": 2592000,
    "description": "Full access to all Pro features, billed monthly."
  }'

---

GET /api/plans

List all subscription plans for your merchant account, ordered newest-first. Each plan object includes a _count.subscriptions field with the total number of subscribers.

Response — 200 OK

Returns an array of plan objects. Each object has the same shape as the plan field in the create response, plus _count: { subscriptions: number }.

curl

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

---

PATCH /api/plans/:id

Update a plan’s display label, description, or active status. You cannot change the amount, mint, or interval of a plan after creation — create a new plan instead.

Path parameters

id · string · required

The plan’s database UUID.

Request body

All fields are optional. Include only the fields you want to change.

label · string

New display name (1–100 characters).

description · string

New description (max 500 characters).

active · boolean

Set to false to stop accepting new subscribers without canceling existing ones. Set to true to re-open the plan.

Response — 200 OK

Returns the updated plan object.

Error cases

• NOT_FOUND (404) — The plan does not exist or does not belong to your account.
• VALIDATION_ERROR (400) — The request body failed schema validation.

curl

curl --request PATCH https://api.marlin.dev/api/plans/01HXYZ \
  --header "Authorization: Bearer sk_live_abc123" \
  --header "Content-Type: application/json" \
  --data '{ "active": false }'