lomi.
Payments

Subscriptions

Manage recurring customer subscriptions.

The Subscriptions API provides read access to customer subscriptions. Subscriptions are automatically created when customers purchase recurring products through Checkout Sessions or Payment Links.

Subscriptions are system-managed. You can only cancel subscriptions—price, billing dates, and other fields cannot be modified.

List subscriptions

Retrieve all subscriptions for your organization.

Query Parameters

ParameterTypeDescription
pagenumberPage number (default: 1)
pageSizenumberItems 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

FieldTypeRequiredDescription
cancel_at_period_endbooleanNoIf true, cancel at end of billing period. If false, cancel immediately (default).
reasonstringNoCancellation 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

FieldTypeDescription
idstringUnique subscription identifier
customer_idstringAssociated customer
product_idstringAssociated product
price_idstringAssociated price
statusstringactive, past_due, cancelled, trialing
amountnumberRecurring amount
currency_codestringCurrency
billing_intervalstringday, week, month, year
current_period_startstringCurrent period start
current_period_endstringCurrent period end (next billing date)
cancel_at_period_endbooleanScheduled for cancellation
cancel_atstringScheduled cancellation date
cancelled_atstringActual cancellation timestamp
trial_startstringTrial start date
trial_endstringTrial end date
created_atstringCreation timestamp

Webhooks

EventDescription
subscription.createdNew subscription created
subscription.updatedSubscription renewed or updated
subscription.cancelledSubscription cancelled
subscription.payment_failedRecurring payment failed

Error Responses

StatusDescription
401Invalid or missing API key
404Subscription or customer not found

Beneficiary Payouts

Send payments to contractors, suppliers, and other beneficiaries.

Discount Coupons

Create and manage promotional discount codes.

On this page

List subscriptions
Query Parameters
Get subscriptions for a customer
Get a subscription
Cancel a subscription
Request Body
Subscription Object
Webhooks
Error Responses