Skip to content
API Reference
/
Subscription
/
Create a new subscription

API specification for Glomo (1.0.0)

The Glomo API follows REST architecture, utilizing resource-oriented URLs for clarity. It handles form-encoded request bodies, delivers responses in JSON format, and operates with standard HTTP methods, authentication, and response codes.

You can download the complete API collection by using the download options on the right.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
E-mail

developer@glomopay.com

License

Apache 2.0

Terms of Service

Languages
Servers
Production server

https://api.glomopay.com/api/v1/

Balance

This resource represents your Glomo balance. You can retrieve it to see the current balance on your Glomo account in all currencies enabled for your account.

Operations

Balance Conversions

Balance Conversion resource represents the details of the balance conversion. The balance conversion is the conversion of the balance from one supported currency to another supported currency.

Operations

Orders

This resource represents the order details. The order is the request to receive payment from your customer.

Operations

Customer

This resource represents a customer of your business. The customer can be an individual or a business from whom you will receive payments.

Operations

Document

Document resource represents the documents details uploaded. This document is used in payin, payout, etc.

Operations

Payment

This resource represents a payment attempt made by your customer. The payment can either be successfully completed or failed, depending on various factors.

Operations

Refund

This resource represents a refund transaction from your Glomo account to your customer. You can retrieve it to see the details of the refund transaction.

Operations

Price

This resource represents the pricing details of the payin or payout. The pricing details include the fees and the pricing type

Operations

Subscription

This resource represents a recurring billing agreement for a customer. Subscriptions allow businesses to automatically charge customers on a regular schedule according to a defined billing plan.

Operations

List subscriptions

Request

Returns a list of subscriptions matching some criteria. The subscriptions are returned sorted by creation date, with the most recent subscriptions appearing first.

Security
JWT
Query
statusstring

Filter subscriptions by status.

Enum"created""active""paused""expired""failed""halted""cancelled""completed"
Example: status=active
customer_idstring

Filter subscriptions by customer ID.

Example: customer_id=cust_5JU9yv0lGSUP
start_datestring(date)

Filter subscriptions with a particular start date, in UTC timezone and ISO 8601 format (YYYY-MM-DD).

Example: start_date=2024-01-01
end_datestring(date)

Filter subscriptions with a particular end date, in UTC timezone and ISO 8601 format (YYYY-MM-DD).

Example: end_date=2024-12-31
beforestring(timestamp)

ISO-8601 timestamp in UTC to filter resources created before this time. Use this to avoid Page drift issue. See Pagination parameters for more details.

Example: before=2025-02-18T12:03:44Z
afterstring(timestamp)

ISO-8601 timestamp in UTC to filter resources created after this time. Use this to avoid Page drift issue. See Pagination parameters for more details.

Example: after=2025-01-18T12:03:44Z
per_pageinteger

Number of resources per page. Should be between 1 and 100.

Default 20
pageinteger

Page number for pagination. Starts from 1. Get the next page number from the next field in the response.

Default 1
curl -i -X GET \
  'https://api.glomopay.com/api/v1/subscriptions?status=active&customer_id=cust_5JU9yv0lGSUP&start_date=2024-01-01&end_date=2024-12-31&before=2025-02-18T12%3A03%3A44Z&after=2025-01-18T12%3A03%3A44Z&per_page=20&page=1' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

List of subscriptions matching the criteria.

Bodyapplication/json
dataArray of objects(Subscription)
page_metaobject(PageMeta)
Response
application/json
{
  "data": [
    { … }
  ],
  "page_meta": {
    "current": 2,
    "previous": 1,
    "next": 3,
    "per_page": 20,
    "pages": 10,
    "count": 200
  }
}

Create a new subscription

Request

Creates a new subscription for a customer with specified billing plan and schedule. The subscription will be created in 'created' status and will be activated when the customer completes the first payment.

Security
JWT
Bodyapplication/jsonrequired
customer_idstringrequired

Unique identifier of the customer associated with this subscription.

Example: "cust_5JU9yv0lGSUP"
product_namestring<= 128 charactersrequired

Name of the product being subscribed to.

Example: "ShieldGuard Insurance"
product_descriptionstring<= 512 charactersrequired

Description of the product.

Example: "Flexible, monthly insurance for belongings, travel, and digital assets; easy to manage"
plan_namestring<= 128 characters

Name of the subscription plan.

Example: "ShieldGuard Lite"
plan_descriptionstring<= 512 characters

Description of the subscription plan.

Example: "Simple, monthly insurance plan that covers your basic belongings and key digital assets"
amountnumber(Amount)required

The amount in the smallest currency unit. For example, if the amount is $299.00, then 29900 is passed in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ï¿¥295, pass the value as 295.

currencystring(iso-4217)(Currency)required

The currency code in ISO 4217 format.

interval_typestring(IntervalType)required

Used in combination with interval_count to define the billing cycle frequency.

Enum"month""year"
interval_countinteger(IntervalCount)required

Number of intervals between a billing cycle, used in combination with interval_type. Valid combinations:

  • Monthly: interval_type='month', interval_count=1
  • Quarterly: interval_type='month', interval_count=3
  • Half-yearly: interval_type='month', interval_count=6
  • Yearly: interval_type='year', interval_count=1
Enum136
billing_cyclesinteger>= 2required

Total number of billing cycles for the subscription. A subscription can have a lifetime of 10 years. Maximum billing cycles therefore depend on interval:

  • Monthly (interval_type='month', interval_count=1): max 120 cycles
  • Quarterly (interval_type='month', interval_count=3): max 40 cycles
  • Half-yearly (interval_type='month', interval_count=6): max 20 cycles
  • Yearly (interval_type='year', interval_count=1): max 10 cycles
Example: 12
start_datestring(date)required

Start date of the subscription in UTC timezone and ISO 8601 format (YYYY-MM-DD). Must be today or in the future.

Example: "2025-01-01"
expires_atstring(date)required

Expiration date for the subscription payment link in UTC timezone and ISO 8601 format (YYYY-MM-DD). Must be >= start_date and cannot be more than 6 months from start_date.

Example: "2025-01-07"
notify_customerbooleanrequired

Whether to send notification e-mails to customers for subscription lifecycle changes.

Example: true
starts_with_first_paymentbooleanrequired

Whether the subscription payment schedule should get synchronized with the first payment.

Example: true
curl -i -X POST \
  https://api.glomopay.com/api/v1/subscriptions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "cust_5JU9yv0lGSUP",
    "product_name": "ShieldGuard Insurance",
    "product_description": "Flexible, monthly insurance for belongings, travel, and digital assets; easy to manage",
    "plan_name": "ShieldGuard Lite",
    "plan_description": "Simple, monthly insurance plan that covers your basic belongings and key digital assets",
    "amount": 1000,
    "currency": "USD",
    "interval_type": "month",
    "interval_count": 1,
    "billing_cycles": 12,
    "start_date": "2025-01-01",
    "expires_at": "2025-01-07",
    "notify_customer": true,
    "starts_with_first_payment": true
  }'

Responses

Subscription created successfully

Bodyapplication/json
idstringrequired

Unique identifier for the subscription.

Example: "sub_5JU9yv0lGSUP"
customer_idstringrequired

Unique identifier of the customer associated with this subscription.

Example: "cust_5JU9yv0lGSUP"
product_namestringrequired

Name of the product being subscribed to.

Example: "ShieldGuard Insurance"
product_descriptionstringrequired

Description of the product.

Example: "Flexible, monthly insurance for belongings, travel, and digital assets; easy to manage"
plan_namestring

Name of the subscription plan.

Example: "ShieldGuard Lite"
plan_descriptionstring

Description of the subscription plan.

Example: "Simple, monthly insurance plan that covers your basic belongings and key digital assets"
statusstringrequired

Current status of the subscription.

Enum"created""active""paused""expired""failed""halted""cancelled""completed"
Example: "active"
amountnumber(Amount)required

The amount in the smallest currency unit. For example, if the amount is $299.00, then 29900 is passed in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ï¿¥295, pass the value as 295.

currencystring(iso-4217)(Currency)required

The currency code in ISO 4217 format.

interval_typestring(IntervalType)required

Used in combination with interval_count to define the billing cycle frequency.

Enum"month""year"
interval_countinteger(IntervalCount)required

Number of intervals between a billing cycle, used in combination with interval_type. Valid combinations:

  • Monthly: interval_type='month', interval_count=1
  • Quarterly: interval_type='month', interval_count=3
  • Half-yearly: interval_type='month', interval_count=6
  • Yearly: interval_type='year', interval_count=1
Enum136
billing_cyclesintegerrequired

Total number of billing cycles for the subscription.

Example: 12
start_datestring(date)required

Start date of the subscription in UTC timezone and ISO 8601 format (YYYY-MM-DD).

Example: "2025-01-01"
end_datestring(date)required

The date on which the subscription ends in UTC timezone and ISO 8601 format (YYYY-MM-DD).

Example: "2025-12-01"
expires_atstring(date)required

Expiration date for the subscription payment link in UTC timezone and ISO 8601 format (YYYY-MM-DD).

Example: "2025-01-07"
next_payment_datestring or null(date)

Date of the next scheduled payment in UTC timezone and ISO 8601 format (YYYY-MM-DD).

Example: "2025-02-01"
subscription_link_urlstring(uri)required

URL for the subscription payment page. Your customer can use this URL to make the first payment and activate the subscription.

Example: "https://checkout.glomopay.com/subscription/sub_5JU9yv0lGSUP"
cancelled_atstring or null(date)

Date when the subscription was cancelled in UTC timezone and ISO 8601 format (YYYY-MM-DD). This field is null unless the subscription status is 'cancelled'.

Example: "2025-01-15"
Response
application/json
{
  "id": "sub_5JU9yv0lGSUP",
  "customer_id": "cust_5JU9yv0lGSUP",
  "product_name": "ShieldGuard Insurance",
  "product_description": "Flexible, monthly insurance for belongings, travel, and digital assets; easy to manage",
  "plan_name": "ShieldGuard Lite",
  "plan_description": "Simple, monthly insurance plan that covers your basic belongings and key digital assets",
  "status": "active",
  "amount": 1000,
  "currency": "USD",
  "interval_type": "month",
  "interval_count": 1,
  "billing_cycles": 12,
  "start_date": "2025-01-01",
  "end_date": "2025-12-01",
  "expires_at": "2025-01-07",
  "next_payment_date": "2025-02-01",
  "subscription_link_url": "https://checkout.glomopay.com/subscription/sub_5JU9yv0lGSUP",
  "cancelled_at": "2025-01-15"
}

Retrieve a subscription by ID

Request

Retrieves the details of a specific subscription by its unique identifier.

Security
JWT
Path
idstringrequired

Unique identifier of the subscription

Example: sub_5JU9yv0lGSUP
curl -i -X GET \
  https://api.glomopay.com/api/v1/subscriptions/sub_5JU9yv0lGSUP \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Subscription details retrieved successfully

Bodyapplication/json
idstringrequired

Unique identifier for the subscription.

Example: "sub_5JU9yv0lGSUP"
customer_idstringrequired

Unique identifier of the customer associated with this subscription.

Example: "cust_5JU9yv0lGSUP"
product_namestringrequired

Name of the product being subscribed to.

Example: "ShieldGuard Insurance"
product_descriptionstringrequired

Description of the product.

Example: "Flexible, monthly insurance for belongings, travel, and digital assets; easy to manage"
plan_namestring

Name of the subscription plan.

Example: "ShieldGuard Lite"
plan_descriptionstring

Description of the subscription plan.

Example: "Simple, monthly insurance plan that covers your basic belongings and key digital assets"
statusstringrequired

Current status of the subscription.

Enum"created""active""paused""expired""failed""halted""cancelled""completed"
Example: "active"
amountnumber(Amount)required

The amount in the smallest currency unit. For example, if the amount is $299.00, then 29900 is passed in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ï¿¥295, pass the value as 295.

currencystring(iso-4217)(Currency)required

The currency code in ISO 4217 format.

interval_typestring(IntervalType)required

Used in combination with interval_count to define the billing cycle frequency.

Enum"month""year"
interval_countinteger(IntervalCount)required

Number of intervals between a billing cycle, used in combination with interval_type. Valid combinations:

  • Monthly: interval_type='month', interval_count=1
  • Quarterly: interval_type='month', interval_count=3
  • Half-yearly: interval_type='month', interval_count=6
  • Yearly: interval_type='year', interval_count=1
Enum136
billing_cyclesintegerrequired

Total number of billing cycles for the subscription.

Example: 12
start_datestring(date)required

Start date of the subscription in UTC timezone and ISO 8601 format (YYYY-MM-DD).

Example: "2025-01-01"
end_datestring(date)required

The date on which the subscription ends in UTC timezone and ISO 8601 format (YYYY-MM-DD).

Example: "2025-12-01"
expires_atstring(date)required

Expiration date for the subscription payment link in UTC timezone and ISO 8601 format (YYYY-MM-DD).

Example: "2025-01-07"
next_payment_datestring or null(date)

Date of the next scheduled payment in UTC timezone and ISO 8601 format (YYYY-MM-DD).

Example: "2025-02-01"
subscription_link_urlstring(uri)required

URL for the subscription payment page. Your customer can use this URL to make the first payment and activate the subscription.

Example: "https://checkout.glomopay.com/subscription/sub_5JU9yv0lGSUP"
cancelled_atstring or null(date)

Date when the subscription was cancelled in UTC timezone and ISO 8601 format (YYYY-MM-DD). This field is null unless the subscription status is 'cancelled'.

Example: "2025-01-15"
Response
application/json
{
  "id": "sub_5JU9yv0lGSUP",
  "customer_id": "cust_5JU9yv0lGSUP",
  "product_name": "ShieldGuard Insurance",
  "product_description": "Flexible, monthly insurance for belongings, travel, and digital assets; easy to manage",
  "plan_name": "ShieldGuard Lite",
  "plan_description": "Simple, monthly insurance plan that covers your basic belongings and key digital assets",
  "status": "active",
  "amount": 1000,
  "currency": "USD",
  "interval_type": "month",
  "interval_count": 1,
  "billing_cycles": 12,
  "start_date": "2025-01-01",
  "end_date": "2025-12-01",
  "expires_at": "2025-01-07",
  "next_payment_date": "2025-02-01",
  "subscription_link_url": "https://checkout.glomopay.com/subscription/sub_5JU9yv0lGSUP",
  "cancelled_at": "2025-01-15"
}

Payout

This resource represents the disbursement transactions from your Glomo account to your beneficiaries.

Operations

Beneficiary

This resource represents a payee of a payout initiated by your business. The beneficiary can be an individual or a business to whom you will send funds.

Operations

Bank Account Validation

Bank Account Validation resource represents the validation details of a bank account.

Operations

Withdrawal

This resource represents the withdrawal transaction from your Glomo account to your withdrawal account.

Operations

Withdrawal Account

This resource represents the withdrawal account details. The withdrawal account is the bank account where the withdrawal amount will be credited.

Operations

Settlement

This resource represents the settlement details. The settlement is the process of transferring funds from your Glomo account to your bank account.

Operations