Subscriptions

Subscriptions are bound to a SubscriptionPlan (the template) and a Customer (the buyer). The customer's wallet authorises a multi-period allowance; Strimz's scheduler charges every period.

Plans

POST /v1/subscription-plans
{
  "name": "Pro",
  "amount": "20000000",
  "currency": "USDC",
  "interval": "monthly",      // 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly'
  "intervalCount": 1,
  "trialPeriodDays": 14,
  "successUrl": "https://your-app.com/welcome?sub={SUBSCRIPTION_ID}",  // optional
  "cancelUrl": "https://your-app.com/pricing"                          // optional
}

GET  /v1/subscription-plans/{id}
GET  /v1/subscription-plans
POST /v1/subscription-plans/{id}/archive

Only the return URLs can change after creation. null clears one; an omitted field stays the same. Any other field answers 400 invalid_request. See Plans: return URLs.

PATCH /v1/subscription-plans/{id}
{
  "successUrl": "https://your-app.com/welcome?sub={SUBSCRIPTION_ID}",
  "cancelUrl": null
}

Subscriptions

Customers create subscriptions on-chain via your hosted checkout. There's no POST /v1/subscriptions endpoint. The indexer projects them when the chain emits SubscriptionCreated.

Read paths:

GET  /v1/subscriptions/{id}
GET  /v1/subscriptions?status=active&planId=cmq4wjr3m0008je6l5t0w2yhb
POST /v1/subscriptions/{id}/cancel    { "reason": "merchant initiated" }

The list also takes customerId to show one customer's subscriptions, and from and to for subscriptions created in a range. See List filters.

Cancel marks the subscription cancelled in Strimz right away and queues the on-chain cancel.

Status enum

trialing  active  at_risk  cancelled  lapsed

Only cancelled and lapsed are terminal; at_risk is recoverable if the customer tops up their wallet. The schema also lists paused, but there are no pause or resume routes and nothing sets it today.

Charges

The indexer records every charge attempt from on-chain events: successful, failed and skipped. List them for one subscription, newest first:

GET /v1/subscriptions/{id}/charges?limit=25

It needs the subscriptions_read scope and pages like every other list (limit up to 100, cursor). Each item has a status and an outcome. For example, insufficient_funds is a payment failure, and token_not_allowed means the subscriber's token was delisted. Neither is a fault in your integration.

const page = await strimz.subscriptions.charges('sub_123', { limit: 25 })
for (const attempt of page.data) console.log(attempt.outcome, attempt.executedAt)

Successful charges also fire subscription.charged, and payment failures fire subscription.charge_failed.

Webhook events