A plan is the price and the interval. Subscriptions reference a plan by its code, so plans come first.

Think of a plan as a product tier — "Pro, monthly, $20" — not as a per-customer arrangement. Many subscriptions share one plan.

The Flow

sequenceDiagram
    participant Y as Your backend
    participant K as Kyshi

    Y->>K: POST /v1/plans
    K-->>Y: plan code
    Note over Y: Store the code
    Y->>K: POST /v1/subscriptions (planCode)

Build It

-H "x-api-key: your_secret_key"

POST {{host}}/v1/plans

{
  "name": "Pro Monthly",
  "description": "Pro tier, billed monthly",
  "interval": "monthly",
  "amount": 20,
  "amountCurrency": "settlement",
  "localCurrency": "NGN"
}

Store the returned code. It is the only thing subscriptions need, and the only way to find the plan again.

Intervals

daily · weekly · monthly · quarterly · biannually · annually

The interval sets the billing cycle and therefore when invoices are generated.

Pricing: The Decision That Matters

amountCurrency determines who absorbs currency movement, and it cannot be changed after subscriptions exist without disrupting them.

With settlement, a $20 plan stays $20 to you, but your Nigerian customer might be billed ₦30,000 one month and ₦32,000 the next. Some customers find that alarming enough to cancel.

With local, the customer sees ₦30,000 every month, and your revenue per subscriber moves with the rate.

There is no universally right answer. Consumer subscriptions usually favour local for predictability; B2B contracts priced in dollars usually favour settlement. Decide before you launch. See FX And Rates.

When It Fails

Changing the price of a live plan

Plans are referenced by active subscriptions. Editing one changes what existing subscribers are billed at the next cycle, usually without them being told.

Create a new plan for new pricing and migrate deliberately. Treat plans as immutable once anything is subscribed to them.

Plan sprawl

Creating a plan per customer makes reporting meaningless and multiplies the objects you maintain. Use one plan per pricing tier; per-customer variation belongs on the subscription.

Losing the plan code

The code is how subscriptions reference the plan. Store it against your own product record at creation time rather than looking it up by name later — names are not unique.

An unsupported currency

A currency not enabled for your business returns 422. That is configuration, not a bad request; retrying will not help. See Countries And Currencies.

Reconcile

Plans are configuration, not money, so there is little ongoing reconciliation. Two checks are worth scheduling:

1. Every plan code you reference still exists in Kyshi.
2. Every plan in Kyshi maps to something you still sell — orphaned plans usually mean a migration that never finished.

GET {{host}}/v1/plans

Test It

Create a plan in test mode, subscribe to it, then use Simulate Subscription to drive a cycle. Test a daily plan rather than waiting a month — the billing logic is the same.

Next

• Create Plan — full schema
• Subscriptions — bill customers against a plan
• FX And Rates — the pricing decision in detail