Plans

A plan turns a product into something a customer can subscribe to: a price, a currency, an optional trial, and a billing rule that tells the engine when to generate each invoice. The plan also owns the failure story — how many times a failed charge is retried (maxDunningAttempts), on which days (dunningScheduleDays), and how long the customer keeps access while payment is being chased (gracePeriodDays).

Endpoints

All Bearer-authenticated (at_live_…); lists use cursor pagination (pageSize, pageToken, filter by productId / includeArchived).

Create a plan

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/plans \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prd_4b2e88",
    "code": "pro-monthly",
    "name": "Pro Monthly",
    "price": 49900,
    "currency": "TRY",
    "trialPeriodDays": 7,
    "billing": {
      "frequency": "MONTHLY",
      "interval": 1,
      "byMonthDay": [15],
      "timezone": "Europe/Istanbul",
      "lastDayOfMonthFix": true
    },
    "maxDunningAttempts": 3,
    "dunningScheduleDays": [1, 3, 7],
    "gracePeriodDays": 7
  }'

Fields

The billing rule

The billing object is a recurrence rule — the same building blocks as an RRULE:

Recipes:

{ "frequency": "MONTHLY", "interval": 1,  "timezone": "Europe/Istanbul", "lastDayOfMonthFix": true }          // classic monthly
{ "frequency": "MONTHLY", "interval": 3,  "byMonthDay": [1], "timezone": "Europe/Istanbul", "lastDayOfMonthFix": true }  // quarterly, on the 1st
{ "frequency": "WEEKLY",  "interval": 1,  "byWeekDay": ["MO"], "timezone": "Europe/Istanbul", "lastDayOfMonthFix": false } // every Monday
{ "frequency": "YEARLY",  "interval": 1,  "timezone": "Europe/Istanbul", "lastDayOfMonthFix": true, "count": 3 }          // 3 annual charges, then done

Update & archive

PATCH /api/v1/subscriptions/plans/:id updates name, description, price, trialPeriodDays, billing, the dunning fields and metadata (plus an audit reason). Whether and when a price update reaches existing subscribers is governed by the product/subscription price policy (LOCKED / FOLLOW_PLAN, IMMEDIATE / NEXT_PERIOD) — see Products.

DELETE /api/v1/subscriptions/plans/:id archives the plan: it can no longer be subscribed to and leaves the public catalog, but existing subscriptions on it keep billing normally.

curl -X DELETE https://api-gateway.lunixi.com/api/v1/subscriptions/plans/pln_9f3a1c \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "superseded by pro-monthly-v2" }'

Translations & display text

Plan name / description localize exactly like products — PATCH …/plans/:id/translations/:locale with { "name": …, "description": … }, served automatically wherever a locale is passed (public catalog, portal).

The marketing bullet lines under a plan on your pricing page — "500 transactions / month", "Priority support" — are the plan's display features: ordered, per-locale display texts managed from the merchant panel and returned with the plan in the Public Catalog API. They are presentation only; enforceable quotas live in Features & entitlements.

Response

{
  "id": "pln_9f3a1c",
  "productId": "prd_4b2e88",
  "code": "pro-monthly",
  "name": "Pro Monthly",
  "price": 49900,
  "currency": "TRY",
  "trialPeriodDays": 7,
  "billing": {
    "frequency": "MONTHLY",
    "interval": 1,
    "byMonthDay": [15],
    "timezone": "Europe/Istanbul",
    "lastDayOfMonthFix": true
  },
  "maxDunningAttempts": 3,
  "dunningScheduleDays": [1, 3, 7],
  "gracePeriodDays": 7,
  "isActive": true,
  "createdAt": "2026-07-06T09:31:00Z"
}

Switching plans

Moving an existing subscriber to another plan is an operation on the subscription, not the plan: POST /api/v1/subscriptions/subscriptions/:id/change-plan with behavior: "IMMEDIATE" (switch and settle now) or "NEXT_PERIOD" (schedule for the period boundary). Upgrades, downgrades and the events they emit are covered in Subscriptions.

Errors

Webhooks

Next steps

• Subscriptions — subscribe customers, cancel, pause, change plan
• Products — price-change policy and catalog translations
• Pricing & Portal SDK — render these plans on your own pricing page
• Invoices — what the billing rule produces each period