POST /v1/subscriptions Bearer Idempotent

Enroll a subscription

Creates a subscriber and starts mandate enrollment for a subscription plan. Omni charges the plan amount once on approval (or immediately if the MSISDN already has an approved mandate). Later cycles are not automatic — call POST /v1/mandates/{mandate_id}/debits on your schedule. Hosted /subscribe pages are billed by Omni instead.

Headers

Idempotency-Key required string: Required for money-moving and session/mandate creates; replays must use the same body.
X-Mojo-Account-Ref optional string: Required when sub-accounts are enabled for the merchant (except metadata and balance routes). Targets the sub-account for this request.

Body parameters

plan_id required string
merchant_reference required string
customer_name required string
customer_email required string (email)
mobile required string
provider required string
notes optional string

Webhook events

subscription.created subscription.active subscription.charge_failed

POST https://omni.mojo-pay.com/v1/subscriptions

{
    "plan_id": "PLN_ABCDEF123456",
    "merchant_reference": "SUB-1042",
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "mobile": "233544338841",
    "provider": "MTN",
    "notes": "Signed up from marketing campaign"
}

curl -X POST "https://omni.mojo-pay.com/v1/subscriptions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "PLN_ABCDEF123456",
    "merchant_reference": "SUB-1042",
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "mobile": "233544338841",
    "provider": "MTN",
    "notes": "Signed up from marketing campaign"
}'

Response

{
    "object": "subscription",
    "subscription_id": "SUB_ABCDEF123456",
    "status": "pending_approval",
    "merchant_reference": "SUB-1042",
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "plan_id": "PLN_ABCDEF123456",
    "plan_name": "Gold Monthly",
    "mandate_id": "MD_ABCDEF123456",
    "mobile": "233544338841",
    "provider": "MTN",
    "starts_at": "2026-07-07",
    "ends_at": "2036-07-07"
}