Subscriptions

Manage recurring payment subscriptions that automatically generate invoices.

Create Subscription

Create a new subscription with automatic invoice generation.

Endpoint: POST /v1/pay/subscriptions

Authentication: Required

Request Body:

Field	Type	Required	Description
`customer_id`	string	No*	ID of existing customer
`customer_email`	string	No*	Customer email (required if `customer_id` not provided)
`customer_name`	string	No*	Customer name (required if `customer_id` not provided)
`customer_phone`	string	No	Customer phone number
`customer_address`	string	No	Customer address
`currency`	string	Yes	Currency code (default: `"GMD"`)
`tax_rate`	number	No	Tax rate as percentage (0-100, default: 0)
`interval`	string	Yes	Billing interval (`day`, `week`, `month`, `year`)
`interval_count`	integer	Yes	Number of intervals between billings
`day_of_month`	integer	No**	Day of month for monthly billing (1-28, required for monthly interval)
`day_of_week`	integer	No**	Day of week for weekly billing (0=Sunday, 6=Saturday, required for weekly interval)
`start_date`	string	Yes	Subscription start date (YYYY-MM-DD)
`end_date`	string	No	Optional end date to limit subscription duration (YYYY-MM-DD)
`items`	array	Yes	Subscription items (minimum 1)
`notes`	string	No	Additional notes
`metadata`	object	No	Custom metadata

*Either customer_id or customer_email+customer_name required
**Required based on interval type

Subscription Statuses:

active - Subscription is active, invoices will be generated

paused - Temporarily stopped, no invoices generated

cancelled - Permanently cancelled

completed - Subscription reached its end date

TIP

Billing Intervals:

Daily: interval: "day", interval_count: 1 for daily billing

Weekly: interval: "week", day_of_week: 1 (Monday) for weekly billing

Monthly: interval: "month", day_of_month: 15 for billing on the 15th each month

Yearly: interval: "year", interval_count: 1 for annual billing

Example:

HTTP

TypeScript

Python

Success Response (201):

{
  "data": {
    "id": "sub_abc123",
    "organization_id": "org_xyz789",
    "customer_id": "cus_def456",
    "customer_email": "customer@example.com",
    "customer_name": "John Doe",
    "amount": "1000.00",
    "currency": "GMD",
    "tax_rate": 15,
    "interval": "month",
    "interval_count": 1,
    "day_of_month": 1,
    "start_date": "2024-12-01T00:00:00Z",
    "end_date": null,
    "next_invoice_date": "2024-12-01T00:00:00Z",
    "last_invoice_date": null,
    "status": "active",
    "invoice_count": 0,
    "mode": "test",
    "version": 1,
    "items": [
      {
        "description": "Monthly subscription",
        "quantity": 1,
        "unit_price": "1000.00",
        "total": "1000.00"
      }
    ],
    "notes": null,
    "metadata": {},
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Get Subscription

Get details of a specific subscription.

Endpoint: GET /v1/pay/subscriptions/{id}

Authentication: Required

Example:

HTTP

TypeScript

Python

List Subscriptions

Get a paginated list of subscriptions.

Endpoint: GET /v1/pay/subscriptions

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
`offset`	integer	No	Number of items to skip (default: 0)
`limit`	integer	No	Maximum number of items to return (default: 20, max: 100)
`status`	string	No	Filter by status (`active`, `paused`, `cancelled`, `completed`)

Example:

HTTP

TypeScript

Python

Update Subscription

Update an existing subscription.

Endpoint: PUT /v1/pay/subscriptions/{id}

Authentication: Required

Request Body:

Field	Type	Required	Description
`status`	string	No	Status (`active`, `paused`, `cancelled`)
`end_date`	string	No	End date (YYYY-MM-DD)
`amount`	string	No	New amount (affects future invoices only)
`notes`	string	No	Updated notes

Example:

HTTP

TypeScript

Python

Cancel Subscription

Cancel a subscription immediately.

Endpoint: POST /v1/pay/subscriptions/{id}/cancel

Authentication: Required

Example:

HTTP

TypeScript

Python

WARNING

Permanent Action: Cancelling a subscription is permanent and cannot be undone. Existing invoices remain valid, but no new invoices will be generated.

List Subscription Invoices

Get all invoices generated by a subscription.

Endpoint: GET /v1/pay/subscriptions/{id}/invoices

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
`offset`	integer	No	Number of items to skip (default: 0)
`limit`	integer	No	Maximum number of items to return (default: 20, max: 100)

Example:

HTTP

TypeScript

Python

Trigger Subscription Processing

Manually trigger invoice generation for subscriptions that are due.

Endpoint: POST /v1/pay/subscriptions/trigger-processing

Authentication: Required

Example:

HTTP

TypeScript

Python

INFO

Testing: This endpoint is useful for testing subscription billing in test mode. In production, subscriptions are automatically processed by the background worker.

Subscriptions

Create Subscription#

Get Subscription#

List Subscriptions#

Update Subscription#

Cancel Subscription#

List Subscription Invoices#

Trigger Subscription Processing#

Create Subscription

Get Subscription

List Subscriptions

Update Subscription

Cancel Subscription

List Subscription Invoices

Trigger Subscription Processing