Skip to content
Docs/
API reference
/
/
Cancel a subscription

Cancel a subscription

Request

Cancels a subscription. Once cancelled, the subscription will stop processing future payments. This action cannot be undone, but you can create a new subscription if needed.

Security
JWT
Path
idstringrequired

Unique identifier of the subscription to cancel. Starts with sub_ followed by letters and digits. An ID of any other shape is rejected with 400 and a message saying it must start with sub_; a well-formed ID that doesn't match a subscription on your account returns 404.

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

Responses

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

optional identifier to be sent for reconciliations

Example:"R0001"
statusstringrequired

Current status of the subscription.

  • created — the subscription exists and is waiting for the customer to authorise it.
  • authorized — the customer has authorised the subscription and it has not become active yet.
  • active — the subscription is charging on its schedule.
  • paused — you paused the subscription. Resume it to continue charging.
  • halted — charging stopped automatically; halt_reason says why. It returns to active after its next successful payment, for example once the customer updates the card. The resume endpoint applies only to paused subscriptions.
  • action_required — Glomo needs more information before the subscription can proceed. Respond to the open RFI to continue.
  • under_review — the information you submitted is being reviewed. The subscription becomes active if the review passes and failed if it does not.
  • completed — every billing cycle has been charged. Terminal.
  • cancelled — the subscription was cancelled. Terminal.
  • expired — the customer did not authorise the subscription in time. Terminal.
  • failed — the subscription could not be set up, or did not pass review. Terminal.
Enum:"created""authorized""active""paused""halted""action_required""under_review""completed""cancelled""expired"
Example:"cancelled"
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. Each cycle lasts interval_count units of interval_type, so 12 cycles with interval_count 1 and interval_type month span 12 months. null for as_presented subscriptions.

Example:12
max_amountinteger or null

Maximum allowed amount per payment, in the smallest unit of currency (cents for USD). 5000 is $50.00 when currency is USD. 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:null
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"
halt_reasonobject or null

Present only when status is halted. Describes why the subscription was halted. Absent for all other statuses.

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. Your account may require some notes fields: Glomo configures custom field rules per account, and for beneficiaries they are checked when the beneficiary is created. Some fields are also validated by the beneficiary's country (for example, a PAN format for Indian beneficiaries). A missing required field returns 422 with Validation failed: Notes <field> is required, and type and validation errors (such as enum constraints) are returned the same way. The rule is set on your account, not by currency or rail. No API lists the fields, but the 422 names each missing one: add that key to notes with the value your account expects, and ask your Glomo account manager if you don't know what the field should hold. See Custom fields. 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"
}
payment_methodobject or null

The active payment method on the subscription, derived from the most recent successful payment. Returns null if no successful payment has been made yet (e.g. a newly created subscription or one where the first payment attempt failed).

Example:
{
  "type": "card",
  "details": {
    "card_network": "Visa",
    "card_type": "credit",
    "end_digits": "4242",
    "country_code": "IN",
    "card_holder_name": "John Doe",
    "card_bin": "424242",
    "issuer_name": "HDFC Bank"
  }
}
Response
{
  "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": "cancelled",
  "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": null,
  "subscription_link_url": "https://your-dashboard-host.example/subscription-links/sub_5JU9yv0lGSUP",
  "cancelled_at": "2025-01-15",
  "halt_reason": {
    "code": "MAX_RETRIES_REACHED",
    "description": "The maximum number of auto-debit retry attempts was reached without a successful payment."
  },
  "notes": {
    "invoice_ref": "INV-2026-001",
    "project": "Alpha"
  },
  "payment_method": {
    "type": "card",
    "details": { … }
  }
}