Subscriptions API

• Merchant endpoints are called at https://api.zuuppa.com with your sk_ API key (or dashboard session). They're identical whether reached by key or session.
• Subscribers complete checkout and manage their subscription on Zuuppa-hosted pages at https://pay.zuuppa.com — you send them a link, they never call the API directly.

How it works#

• A charge is priced in USD cents on a tier, but settled in a stablecoin (USDC) that the platform configures. The tier response tells you the mint, decimals, and the computed base-unit amounts.
• At checkout the subscriber's wallet grants an allowance for the total authorization — one period's price times authorization_periods (default 12) — not just one period. Zuuppa draws down that allowance one charge at a time.
• The subscription becomes active only when the first charge confirms on-chain, so "subscribed" means "paid", not merely "signed".
• Subscription and charge state changes reach you as webhooks (subscription.*, charge.*) through the same signed pipeline as payment events.

Charge math#

unit_base_units                = price_usd_cents × 10^(decimals-2)   // e.g. USDC has 6 decimals
total_authorization_base_units = unit_base_units × authorization_periods

The tier response returns both unit_base_units and total_authorization_base_units so you don't compute them yourself.

Required setup order (merchant)#

1. POST /subscription-products                → create a product
2. POST /subscription-products/:id/tiers      → create a tier (price + interval)
3. POST /subscription-domains                 → register redirect domain(s)   [if using success_url/cancel_url]
4. POST /subscription-intents                 → returns checkout_url (a pay.zuuppa.com link)
5. send the subscriber to checkout_url        → they complete the hosted checkout
6. (later) POST /subscriptions/:id/portal-link → mint a portal link for management

Products#

A product groups one or more pricing tiers. Statuses: active, archived.

Product object (render_product): id, name, description, external_id, status, metadata, archived_at, created_at, updated_at.

Errors: invalid_name, invalid_description, invalid_external_id, invalid_status, invalid_metadata, product_exists, product_field_immutable (+field), product_not_found.

Tiers#

A tier is a price + billing interval under a product. Statuses: active, archived.

Interval ceilings: interval_count ≤ 365 (day), 52 (week), 12 (month), 1 (year). authorization_periods ≥ 1.

Errors: invalid_price, invalid_interval, invalid_interval_count, invalid_authorization_periods, authorization_total_too_large, tier_price_above_ceiling (+max_price_usd_cents), tier_field_immutable (+field), product_archived, payout_destination_missing, payout_destination_invalid, platform_wallet_unconfigured (503), tier_not_found, product_not_found, marketplace_fee_unsupported (+marketplace_fee_bps).

Redirect domains#

If you set a success_url or cancel_url on an intent, its host must first be registered here. URLs must be https and non-loopback.

Domain object (render_domain): id, host, active, created_at, updated_at.

Errors: invalid_host, invalid_redirect_url (+field), domain_not_found.

Subscription intents (hosted checkout link)#

Create an intent for a tier; the response carries the hosted checkout link you send the subscriber. Statuses: open, completed, canceled, expired.

Intent object (render_intent): id, tier_id, status, subscriber_wallet, wallet_pinned, success_url, cancel_url, subscription_id, metadata, expires_at, created_at, updated_at, completed_at, canceled_at.

checkout_url is a https://pay.zuuppa.com/s/<checkout_token> link — this is the only response that returns it. Redirect the subscriber there.

Errors: tier_not_found, tier_archived, tier_mint_mismatch (+tier_mint, +platform_mint), tier_price_above_ceiling (+max_price_usd_cents), invalid_expires_in (+min_expires_in, +max_expires_in), invalid_subscriber_wallet (+field), invalid_redirect_url (+field), invalid_tier_id (+field), intent_not_found, intent_not_open (+status, +subscription_id), marketplace_fee_unsupported (+marketplace_fee_bps).

Hosted checkout (pay.zuuppa.com/s/:token)#

The subscriber completes checkout on the hosted page. The page drives these endpoints for you — you don't call them — but here's the flow so you understand what the subscriber goes through.

The page first GETs the checkout to render product/tier/price, then calls prepare, which chooses one of two completion paths by arithmetic, not by configuration:

• requires_signature: true — the wallet's existing on-chain allowance can't cover this subscription, so a new allowance must be granted. The server builds an approveChecked transaction for the new total, partially signs it with the platform fee-payer (so the subscriber needs zero SOL), and hands it over. The wallet adds the owner signature and activate broadcasts it.
• requires_signature: false — the allowance already on chain covers it, so nothing needs to be broadcast. The wallet signs a SIWS message (Sign-In With Solana) and confirm completes it; that signature is the entire consent record.

Either way, the subscription ends up incomplete and armed for its first pull. Nothing here moves money — the charger does, and the subscription flips to active only when that first pull confirms. The page polls GET /s/:token for first_charge, and retry re-arms a first charge that definitely failed.

first_charge shape: { status ("pending"|"succeeded"|"failed"), failure_code, failure_message, recovery_action ("retry"|"reapprove"|"none"), signature, explorer_url }.

Common refusal codes (the page owns the wording): checkout_not_found, checkout_completed, checkout_expired, checkout_closed, wallet_not_permitted (a pinned wallet mismatch), rate_limited (+retry_after_seconds), no_token_account, account_frozen, authorization_required, blockhash_expired, invalid_signature, charge_in_progress.

Subscription management (merchant)#

Statuses: incomplete, active, renewal_required, past_due, paused, canceled, revoked, exhausted, failed.

Charge object (render_charge): id, subscription_id, period_index, delegation_epoch, mint, amount, fee_amount, net_amount, destination_ata, fee_destination, status, signature, explorer_url, failure_code, recovery_action, attempts, created_at, settled_at.

Delegation object (render_delegation): subscriber_wallet, mint, epoch, status, authorized_total, token_account, chain_delegate, chain_allowance, chain_checked_at, cleared_at, updated_at.

Errors: subscription_not_found, subscription_incomplete, subscription_ended (+status), subscription_paused, subscription_canceling, charge_in_progress (+charge_id), charge_already_scheduled (+next_charge_at), authorization_exhausted (+status), wallet_proof_required, delegation_not_found, permission_denied, chain_unavailable (502).

Hosted portal (pay.zuuppa.com/m/:token)#

Where a subscriber manages their subscription. As with checkout, the hosted page drives these endpoints; you mint the link via POST /subscriptions/:id/portal-link (or the subscriber recovers it by proving wallet ownership at /manage).

Reducing is always allowed; raising must be earned. Cancelling and downgrading reduce what can be pulled, so any portal credential may do them. Raising (a pricier tier, or renewing with a larger allowance) requires a wallet signature behind the portal session — a merchant-minted link cannot raise.

Every change of terms goes through one core that returns one of three outcomes, decided by the chain and the ledger, not by a parameter:

• changed — the new slice claims no more than the old one, or the room was already there and a signature was supplied. Applied inline; nothing broadcast.
• proof_required — the existing approval covers the increase, but someone is asking to be charged more, so a SIWS signature is required. A challenge is issued and nothing is written. Re-post the same request carrying the signature.
• approval_required — the room isn't there. A partially-signed approveChecked for the new total is handed over; POST /m/:token/activate broadcasts it.

Errors: portal_not_found (+recovery_url), portal_session_expired (+recovery_url), wallet_proof_required (raising via a link that can't raise), same_tier, tier_not_found, different_product, tier_archived, nothing_to_renew, authorization_pending, subscription_changed, incomplete_proof, blockhash_expired, invalid_signature.

What requires a wallet signature — summary#