Subscriptions API

GetPaidHQ API reference for retrieving and managing customer subscriptions — pausing, resuming, cancelling, updating the billing anchor, and reading payment history.

Retrieve subscriptions and manage their lifecycle — pause, resume, cancel, change the billing anchor, and read payment history.

Creating a subscription

Subscriptions are created through orders, not through a direct subscription create endpoint. Create an order for your recurring items and complete it; completing the order activates the subscription and starts its billing. See Orders & Checkout — including how to start a subscription from a payment token you already hold.

Retrieve a subscription

GET https://api.getpaidhq.com/api/subscriptions/{id}

Example response

{
  "id": "sub_123",
  "order_id": "order_123",
  "status": "active",
  "currency": "NGN",
  "payment_method_id": "pm_123",
  "billing_interval": "month",
  "billing_interval_qty": 1,
  "cycles": 0,
  "billing_anchor": 17,
  "renews_at": "2026-07-17T10:30:00Z",
  "current_period_start": "2026-06-17T10:30:00Z",
  "current_period_end": "2026-07-17T10:30:00Z",
  "cycles_processed": 1,
  "total_revenue": 290000,
  "customer": { "id": "cus_123", "email": "customer@example.com" }
}

cycles is the total number of billing cycles; 0 means the subscription bills indefinitely. Monetary fields are in the currency's minor units.

List subscriptions

GET https://api.getpaidhq.com/api/subscriptions

Supports pagination. To list the subscriptions created by a specific order, use GET /api/orders/{id}/subscriptions instead.

List subscription payments

GET https://api.getpaidhq.com/api/subscriptions/{id}/payments

Returns the paginated payment history for a subscription.

Pause a subscription

PUT https://api.getpaidhq.com/api/subscriptions/{id}/pause

Parameters

reason string — Optional reason recorded against the pause.

{ "reason": "Customer requested a hold" }

A paused subscription does not bill until it is resumed.

Resume a subscription

PUT https://api.getpaidhq.com/api/subscriptions/{id}/resume

Parameters

resume_behavior string — How billing resumes:
- continue_existing_billing_period — keep the period that was in progress when the subscription was paused.
- start_new_billing_period — start a fresh billing period from the resume date.

{ "resume_behavior": "continue_existing_billing_period" }

Cancel a subscription

PUT https://api.getpaidhq.com/api/subscriptions/{id}/cancel

Parameters

reason string — Optional reason recorded against the cancellation.

{ "reason": "Downgraded to free plan" }

A cancelled subscription will not renew.

Update the billing anchor

PATCH https://api.getpaidhq.com/api/subscriptions/{id}/billing-anchor

Moves the day of the month on which the subscription bills, optionally prorating the current period.

Parameters

billing_anchor integer required — Day of month, 1–31.
proration_mode string required — none (no adjustment) or prorate (credit the unused portion of the current period).

{ "billing_anchor": 1, "proration_mode": "prorate" }

The response describes the resulting proration:

{
  "credit_amount": 9667,
  "days_credited": 10,
  "old_billing_anchor": 17,
  "new_billing_anchor": 1,
  "current_period_start": "2026-06-17T10:30:00Z",
  "current_period_end": "2026-07-17T10:30:00Z",
  "new_period_start": "2026-06-17T10:30:00Z",
  "new_period_end": "2026-07-01T00:00:00Z"
}

Update subscription metadata

PATCH https://api.getpaidhq.com/api/subscriptions/{id}

Parameters

metadata object — Custom key/value metadata.
default_payment_method string — The payment method to bill going forward.
status string — The subscription status.

{ "metadata": { "plan_tier": "pro" } }

Subscription statuses

pending — created but not yet activated.
trial — in a trial period.
active — active and billing.
past_due — a charge failed and retries are in progress.
paused — temporarily suspended; not billing.
cancelled — cancelled; will not renew.
expired — completed or expired.

Subscriptions API

On this page