Subscriptions

Bill customers on a recurring schedule. Subscriptions are built from four resources: products, prices, customers, and subscriptions. Each billing cycle generates an invoice the customer pays from their wallet.

1. Create a product and a price

bash

# product
curl -X POST https://app.muamla.org/v1/products -u sk_test_your_key: \
  -H "content-type: application/json" -d '{ "name": "Premium Plan" }'
# → { "id": "prod_…" }

# price (weekly | monthly | yearly), amount in smallest MRU unit
curl -X POST https://app.muamla.org/v1/prices -u sk_test_your_key: \
  -H "content-type: application/json" \
  -d '{ "product_id": "prod_…", "amount": 500000, "interval": "monthly" }'
# → { "id": "price_…" }

2. Create a customer

Customers are indexed by your own external_user_id (unique per account).

bash

curl -X POST https://app.muamla.org/v1/customers -u sk_test_your_key: \
  -H "content-type: application/json" -d '{ "external_user_id": "user_123" }'
# → { "id": "cus_…" }

3. Create a subscription

bash

curl -X POST https://app.muamla.org/v1/subscriptions -u sk_test_your_key: \
  -H "content-type: application/json" \
  -d '{ "customer_id": "cus_…", "price_id": "price_…", "trial": "1_month" }'

Without a trial, the first invoice is generated immediately and the subscription is active. With a trial (1_week, 1_month, 1_year, or an ISO-8601 date) no invoice is created until the trial ends.

Statuses

Status	Meaning
`trialing`	In a free trial; no invoices yet.
`active`	Billing normally each cycle.
`past_due`	An invoice went unpaid.
`paused`	Temporarily not billing.
`cancelled`	Ended by the merchant or customer.
`expired`	Reached its end.
`pending_cancellation`	Will cancel at period end.

Lookups & cancel

bash

curl https://app.muamla.org/v1/subscriptions/sub_… -u sk_test_your_key:
curl https://app.muamla.org/v1/subscriptions/by-external-user/user_123 -u sk_test_your_key:
curl -X POST https://app.muamla.org/v1/subscriptions/sub_…/cancel -u sk_test_your_key:

Recurring billing

When a cycle ends, Muamla generates the next invoice and advances the billing date. Trigger the billing run on a schedule:

bash

curl -X POST https://app.muamla.org/v1/cron/billing-cycle -u sk_test_your_key:
# → { "billed": 3 }

Because payments are wallet transfers, each cycle's invoice is paid by the customer (there is no stored card to auto-charge). Use the generated invoice's payment link or a webhook to prompt them.