Subscriptions

The Subscriptions API lists and retrieves subscription instances (a customer on a recurring plan). These are typically created when customers buy recurring products through Checkout Sessions or Payment Links.

SDKs may expose both /subscriptions helpers and dedicated /customer-subscriptions methods. For route-specific examples and status transitions, see Customer subscriptions. Immutable fields and cancel-only rules follow the generated OpenAPI descriptions for each operation.

List subscriptions

Retrieve all subscriptions for your organization.

Query Parameters

Parameter	Type	Description
`page`	`number`	Page number (default: `1`)
`pageSize`	`number`	Items per page (default: `50`)

import { LomiSDK } from '@lomi./sdk';

const lomi = new LomiSDK({
  apiKey: process.env.LOMI_API_KEY!,
  environment: 'live',
});

const subscriptions = await lomi.subscriptions.list({
  page: 1,
  pageSize: 20,
});

subscriptions.forEach(sub => {
  console.log(`${sub.id}: ${sub.status} - ${sub.amount} ${sub.currency_code}`);
});

from lomi import LomiClient
import os

client = LomiClient(
    api_key=os.environ["LOMI_API_KEY"],
    environment="test"
)

subscriptions = client.subscriptions.list(page=1, pageSize=20)

for sub in subscriptions:
    print(f"{sub['id']}: {sub['status']}")

curl -X GET "https://api.lomi.africa/subscriptions?page=1&pageSize=20" \
  -H "X-API-KEY: $LOMI_API_KEY"

Get subscriptions for a customer

Retrieve all subscriptions for a specific customer.

const customerSubs = await lomi.subscriptions.getByCustomer('cus_abc123...');

customer_subs = client.subscriptions.get_by_customer('cus_abc123...')

curl -X GET "https://api.lomi.africa/subscriptions/customer/cus_abc123..." \
  -H "X-API-KEY: $LOMI_API_KEY"

Get a subscription

Retrieve details of a specific subscription.

const subscription = await lomi.subscriptions.get('sub_abc123...');
console.log(`Status: ${subscription.status}`);
console.log(`Next billing: ${subscription.current_period_end}`);

subscription = client.subscriptions.get('sub_abc123...')
print(f"Status: {subscription['status']}")

curl -X GET "https://api.lomi.africa/subscriptions/sub_abc123..." \
  -H "X-API-KEY: $LOMI_API_KEY"

Cancel a subscription

Cancel an active subscription. This is the only modification allowed.

Request Body

Field	Type	Required	Description
`cancel_at_period_end`	`boolean`	No	If `true`, cancel at end of billing period. If `false`, cancel immediately (default).
`reason`	`string`	No	Cancellation reason

// Cancel immediately
const cancelled = await lomi.subscriptions.cancel('sub_abc123...');

// Cancel at period end
const scheduledCancel = await lomi.subscriptions.cancel('sub_abc123...', {
  cancel_at_period_end: true,
  reason: 'Customer requested cancellation',
});

console.log(`Subscription will cancel at: ${scheduledCancel.cancel_at}`);

# Cancel immediately
cancelled = client.subscriptions.cancel('sub_abc123...')

# Cancel at period end
scheduled_cancel = client.subscriptions.cancel('sub_abc123...', {
    "cancel_at_period_end": True,
    "reason": "Customer requested cancellation"
})

curl -X POST "https://api.lomi.africa/subscriptions/sub_abc123.../cancel" \
  -H "X-API-KEY: $LOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_at_period_end": true,
    "reason": "Customer requested cancellation"
  }'

Subscription Object

Field	Type	Description
`id`	`string`	Unique subscription identifier
`customer_id`	`string`	Associated customer
`product_id`	`string`	Associated product
`price_id`	`string`	Associated price
`status`	`string`	`active`, `past_due`, `cancelled`, `trialing`
`amount`	`number`	Recurring amount
`currency_code`	`string`	Currency
`billing_interval`	`string`	`day`, `week`, `month`, `year`
`current_period_start`	`string`	Current period start
`current_period_end`	`string`	Current period end (next billing date)
`cancel_at_period_end`	`boolean`	Scheduled for cancellation
`cancel_at`	`string`	Scheduled cancellation date
`cancelled_at`	`string`	Actual cancellation timestamp
`trial_start`	`string`	Trial start date
`trial_end`	`string`	Trial end date
`created_at`	`string`	Creation timestamp

Webhooks

Event	Description
`subscription.created`	New subscription created
`subscription.updated`	Subscription renewed or updated
`subscription.cancelled`	Subscription cancelled
`subscription.payment_failed`	Recurring payment failed

Error Responses

Status	Description
`401`	Invalid or missing API key
`404`	Subscription or customer not found

Subscriptions

On this page