Create subscription

Create a new subscription that automatically generates invoices on a recurring schedule.

Customer Identification:

Provide customer_id to link to an existing customer (customer data will be auto-filled)

Or provide customer_email and customer_name to create/find customer automatically

Subscription Items:

Link to products via product_id (description and price will be auto-filled)

Or provide custom description and unit_price for ad-hoc items

Billing Intervals:

interval: "day", "week", "month", or "year"

interval_count: Number of intervals between billings (e.g., 2 for every 2 months)

day_of_month: Required for monthly interval (1-28)

day_of_week: Required for weekly interval (0=Sunday, 6=Saturday)

Tax Calculation:

Specify tax_rate as a percentage (0-100)

Tax is calculated on each generated invoice

Subscription Lifecycle:

Status starts as "active" on creation

Invoices are automatically generated based on schedule

Set end_date to limit subscription duration

curl --location --request POST 'https://api.jokoor.com/v1/pay/subscriptions' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "customer_id": "cus_abc123", "currency": "GMD", "tax_rate": 15, "interval": "month", "interval_count": 1, "day_of_month": 1, "start_date": "2024-12-01", "items": [ { "product_id": "prod_xyz789", "quantity": 1 } ] }'

{ "data": { "id": "string", "organization_id": "string", "customer_id": "string", "customer_email": "string", "customer_name": "string", "amount": "string", "currency": "string", "tax_rate": 0, "interval": "day", "interval_count": 0, "day_of_month": 0, "day_of_week": 0, "start_date": "2019-08-24T14:15:22Z", "end_date": "2019-08-24T14:15:22Z", "next_invoice_date": "2019-08-24T14:15:22Z", "last_invoice_date": "2019-08-24T14:15:22Z", "status": "active", "invoice_count": 0, "items": [ { "product_id": "string", "description": "string", "quantity": 0, "unit_price": "string", "total": "string" } ], "notes": "string", "mode": "test", "version": 0, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "metadata": {} } }

Create subscription

Request

Responses