Subscriptions

Subscriptions let you bill a customer on a recurring basis, like a SaaS seat or a membership fee, without building your own billing engine on top of raw payments.

Two objects work together:

A plan is the offer: price, currency, and billing terms. You create it once and reuse it for every customer on that tier.
A subscription binds one customer to one plan. It's what actually gets billed, cycle after cycle.

When to use it

Reach for Subscriptions any time you have a recurring price on a fixed schedule: monthly, yearly, or every N days. MoneyHash handles the plan catalog, the invoice generation, and the status tracking for you.

If instead you just need to charge a saved card whenever you feel like it, for example after a ride or a variable monthly usage bill, that's a different, lower-level tool: a Merchant Initiated Transaction (MIT). See Pay with Stored Card Details. Subscriptions actually uses MIT charges under the hood for automatic renewals, it just adds the plan catalog and lifecycle tracking on top.

Note

Not sure which one you need? If you can describe the billing in one sentence like "SAR 49/month, forever" or "SAR 20/week for 12 weeks," it's a subscription. If the amount or timing is unpredictable, look at raw MIT instead.

How the pieces fit

Three objects, in the order you meet them:

Object	Created	What it holds	Lifetime
Plan	Once, per offer	`amount`, `currency`, `recurrency` x `recurrency_unit`, `recurring_cycles`, `trial_period`, `one_time_fee`, discount terms	Reused by every subscriber on that tier
Subscription	Once per customer	`customer`, `plan`, `start_date`, and optional per-customer overrides in `customization`	Runs until it ends, is cancelled, or is terminated
Invoice	Automatically, one per billing cycle	`amount`, `currency`, `due_date`, its own status, and a `payment_intent_url` to pay it	One billing cycle

You never create invoices yourself. Each billing cycle issues one, and its status tells you whether that cycle has been paid.

Before you start

Every subscription needs a Customer to belong to. Create the customer first if you haven't already.

If you want cycles to be billed automatically, you also need a saved card token for that customer before the first invoice falls due. See Tokenize Cards.

A minimal end-to-end

Three calls, in order. All of them authenticate with your account key in the x-api-key header.

# 1. Create the plan, once
curl -X POST https://web.moneyhash.io/api/v1.4/subscriptions/plans/ \
  -H "x-api-key: <YOUR_ACCOUNT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Basic Monthly",
    "description": "Basic tier, billed monthly",
    "currency": "SAR",
    "amount": "49.00",
    "recurrency": 1,
    "recurrency_unit": "MONTH",
    "recurring_cycles": 12
  }'

# 2. Subscribe a customer to it
curl -X POST https://web.moneyhash.io/api/v1.4/subscriptions/ \
  -H "x-api-key: <YOUR_ACCOUNT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "<YOUR_PLAN_ID>",
    "customer": "<YOUR_CUSTOMER_ID>",
    "start_date": "2026-10-01",
    "charge_automatically": true,
    "primary_card_token": "<YOUR_CARD_TOKEN_ID>",
    "webhook_url": "https://your-server.com/webhooks/subscriptions"
  }'

# 3. Read it back at any time
curl https://web.moneyhash.io/api/v1.4/subscriptions/<YOUR_SUBSCRIPTION_ID>/ \
  -H "x-api-key: <YOUR_ACCOUNT_API_KEY>"

From there MoneyHash issues the invoices, charges the saved card at each due date, and posts a webhook every time the subscription status changes.

Next steps

Manage Plans - create and configure the plans customers subscribe to.
Manage Subscriptions - subscribe a customer, understand the lifecycle, and manage it day to day.
Update Subscriptions - change an existing subscription's plan, price, discount, or card.
Subscription Plans in the SDK - render plans and let the customer pick one from your app.