Skip to content
API Reference
/
/
CreateSubscriptionRespons...

CreateSubscriptionResponse

Subscription resource represents a recurring billing agreement for a customer

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"
reference_numberstring

optional identifier to be sent for reconciliations

Example:"R0001"
statusstringrequired

Current status of the subscription.

Enum:"created""active""paused""expired""failed""halted""cancelled""completed""authorized"
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.

Example:1000
currencystring, (iso-4217)(Currency)required

The currency code in ISO 4217 format.

Example:"USD"
interval_typestring(IntervalType)required

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

Enum:"month""year""as_presented"
interval_countinteger or null(IntervalCount)

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
  • As Presented: interval_type='as_presented', interval_count=null
Enum:136null
billing_cyclesinteger or null

Total number of billing cycles for the subscription. Null for 'as_presented' subscriptions.

Example:12
max_amountinteger or null

Maximum allowed amount per payment. Present only for 'as_presented' subscriptions, null for regular subscriptions.

Example:5000
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 or null, (date)

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"
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"
notesobject or null(Notes)

Optional key-value pairs for attaching custom metadata (e.g. invoice references, project codes). Keys must be strings and cannot collide with reserved field names. If your business has custom field rules configured (e.g. enum constraints), values are validated against those rules. Each key appears as a separate column in CSV report exports, with corresponding values populating the rows.

Example:
{
  "invoice_ref": "INV-2026-001",
  "project": "Alpha"
}
{
  "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",
  "reference_number": "R0001",
  "status": "active",
  "amount": 1000,
  "currency": "USD",
  "interval_type": "month",
  "interval_count": 1,
  "billing_cycles": 12,
  "max_amount": 5000,
  "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",
  "notes": {
    "invoice_ref": "INV-2026-001",
    "project": "Alpha"
  }
}