Get Subscription

Retrieve details of a specific subscription by ID. Use when you need to load a single subscription for a billing portal or to check status.

GET /v1/subscriptions/{id}

Get Subscription

cURL

curl --request GET \
  --url https://api.example.com/v1/subscriptions/{id}

200

{
  "id": "<string>",
  "customer_id": "<string>",
  "plan_id": "<string>",
  "subscription_status": "<string>",
  "currency": "<string>",
  "billing_cadence": "<string>",
  "billing_period": "<string>",
  "billing_period_count": 123,
  "billing_anchor": "<string>",
  "billing_cycle": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "current_period_start": "<string>",
  "current_period_end": "<string>",
  "cancelled_at": "<string>",
  "cancel_at": "<string>",
  "cancel_at_period_end": true,
  "trial_start": "<string>",
  "trial_end": "<string>",
  "pause_status": "<string>",
  "commitment_amount": "<string>",
  "commitment_duration": "<string>",
  "overage_factor": "<string>",
  "enable_true_up": true,
  "payment_behavior": "<string>",
  "collection_method": "<string>",
  "customer_timezone": "<string>",
  "proration_behavior": "<string>",
  "parent_subscription_id": "<string>",
  "payment_terms": "<string>",
  "metadata": {},
  "version": 123,
  "created_at": "<string>",
  "updated_at": "<string>",
  "plan": {},
  "customer": {},
  "coupon_associations": [
    {}
  ],
  "phases": [
    {}
  ],
  "credit_grants": [
    {}
  ]
}

Path Parameters

id · string · required

Unique identifier of the subscription.

Example: "sub_x1y2z3a4b5c6d7e8f9g0"

Response

id · string

Unique identifier for the subscription.

customer_id · string

FlexPrice customer ID.

plan_id · string

Plan ID.

subscription_status · string

Current subscription status.

Values: "ACTIVE", "CANCELLED", "INCOMPLETE", "EXPIRED", "PAUSED", "DRAFT"

currency · string

Three-letter ISO currency code.

billing_cadence · string

Billing frequency.

Values: "IN_ADVANCE", "IN_ARREARS"

billing_period · string

Billing period unit.

Values: "DAY", "WEEK", "MONTH", "QUARTER", "YEAR"

billing_period_count · integer

Number of billing periods per cycle.

billing_anchor · string

ISO 8601 timestamp of the billing anchor date.

billing_cycle · string

Billing cycle type.

Values: "ANNIVERSARY", "CALENDAR"

start_date · string

ISO 8601 timestamp when subscription starts.

end_date · string

ISO 8601 timestamp when subscription ends (if set).

current_period_start · string

ISO 8601 timestamp of current billing period start.

current_period_end · string

ISO 8601 timestamp of current billing period end.

cancelled_at · string

ISO 8601 timestamp when subscription was cancelled (if applicable).

cancel_at · string

ISO 8601 timestamp when subscription will be cancelled (if scheduled).

cancel_at_period_end · boolean

Whether subscription will cancel at period end.

trial_start · string

ISO 8601 timestamp of trial start (if applicable).

trial_end · string

ISO 8601 timestamp of trial end (if applicable).

pause_status · string

Current pause status.

Values: "NONE", "PAUSED"

commitment_amount · string

Minimum committed amount (if set).

commitment_duration · string

Commitment duration (if set).

overage_factor · string

Overage multiplier (if set).

enable_true_up · boolean

Whether true-up fee is enabled.

payment_behavior · string

Payment handling behavior.

collection_method · string

Invoice collection method.

customer_timezone · string

Customer’s timezone.

proration_behavior · string

Proration handling.

parent_subscription_id · string

Parent subscription ID (if part of hierarchy).

payment_terms · string

Payment terms for invoices.

metadata · object

Custom metadata.

version · integer

Subscription version number.

created_at · string

ISO 8601 timestamp when the subscription was created.

updated_at · string

ISO 8601 timestamp when the subscription was last updated.

plan · object

Plan details.

customer · object

Customer details.

coupon_associations · array

Array of associated coupons.

phases · array

Array of subscription phases.

credit_grants · array

Array of credit grants.

Example Request

cURL

curl --request GET \
  --url https://api.flexprice.io/v1/subscriptions/sub_x1y2z3a4b5c6d7e8f9g0 \
  --header 'Authorization: Bearer <token>'

Example Response

{
  "id": "sub_x1y2z3a4b5c6d7e8f9g0",
  "customer_id": "cust_a1b2c3d4e5f6g7h8i9j0",
  "plan_id": "plan_a1b2c3d4e5f6g7h8i9j0",
  "subscription_status": "ACTIVE",
  "currency": "usd",
  "billing_cadence": "IN_ADVANCE",
  "billing_period": "MONTH",
  "billing_period_count": 1,
  "billing_anchor": "2024-03-20T00:00:00Z",
  "billing_cycle": "ANNIVERSARY",
  "start_date": "2024-03-20T00:00:00Z",
  "current_period_start": "2024-03-20T00:00:00Z",
  "current_period_end": "2024-04-20T00:00:00Z",
  "cancel_at_period_end": false,
  "pause_status": "NONE",
  "overage_factor": "1.0",
  "enable_true_up": false,
  "payment_behavior": "DEFAULT_ACTIVE",
  "collection_method": "CHARGE_AUTOMATICALLY",
  "customer_timezone": "UTC",
  "proration_behavior": "NONE",
  "metadata": {
    "source": "website"
  },
  "version": 1,
  "created_at": "2024-03-20T15:04:05Z",
  "updated_at": "2024-03-20T15:04:05Z",
  "plan": {
    "id": "plan_a1b2c3d4e5f6g7h8i9j0",
    "name": "Pro Plan"
  },
  "customer": {
    "id": "cust_a1b2c3d4e5f6g7h8i9j0",
    "name": "Acme Corporation"
  }
}