Skip to main content
GET
/
subscriptions
/
{id}
/
v2
Get subscription V2
curl --request GET \
  --url https://api.cloud.flexprice.io/v1/subscriptions/{id}/v2 \
  --header 'x-api-key: <api-key>'
{
  "active_pause_id": "<string>",
  "billing_anchor": "<string>",
  "billing_cadence": "RECURRING",
  "billing_cycle": "anniversary",
  "billing_period": "MONTHLY",
  "billing_period_count": 123,
  "cancel_at": "<string>",
  "cancel_at_period_end": true,
  "cancelled_at": "<string>",
  "collection_method": "<string>",
  "commitment_amount": "<string>",
  "coupon_associations": [
    {
      "coupon": {
        "amount_off": "<string>",
        "cadence": "once",
        "created_at": "<string>",
        "created_by": "<string>",
        "currency": "<string>",
        "duration_in_periods": 123,
        "environment_id": "<string>",
        "id": "<string>",
        "max_redemptions": 123,
        "metadata": {},
        "name": "<string>",
        "percentage_off": "<string>",
        "redeem_after": "<string>",
        "redeem_before": "<string>",
        "rules": {},
        "status": "published",
        "tenant_id": "<string>",
        "total_redemptions": 123,
        "type": "fixed",
        "updated_at": "<string>",
        "updated_by": "<string>"
      },
      "coupon_id": "<string>",
      "created_at": "<string>",
      "created_by": "<string>",
      "end_date": "<string>",
      "environment_id": "<string>",
      "id": "<string>",
      "metadata": {},
      "start_date": "<string>",
      "status": "published",
      "subscription_id": "<string>",
      "subscription_line_item_id": "<string>",
      "subscription_phase_id": "<string>",
      "tenant_id": "<string>",
      "updated_at": "<string>",
      "updated_by": "<string>"
    }
  ],
  "created_at": "<string>",
  "created_by": "<string>",
  "credit_grants": [
    {
      "cadence": "ONETIME",
      "conversion_rate": "<string>",
      "created_at": "<string>",
      "created_by": "<string>",
      "credit_grant_anchor": "<string>",
      "credits": "<string>",
      "end_date": "<string>",
      "environment_id": "<string>",
      "expiration_duration": 123,
      "expiration_duration_unit": "DAY",
      "expiration_type": "NEVER",
      "id": "<string>",
      "metadata": {},
      "name": "<string>",
      "period": "DAILY",
      "period_count": 123,
      "plan_id": "<string>",
      "priority": 123,
      "scope": "PLAN",
      "start_date": "<string>",
      "status": "published",
      "subscription_id": "<string>",
      "tenant_id": "<string>",
      "topup_conversion_rate": "<string>",
      "updated_at": "<string>",
      "updated_by": "<string>"
    }
  ],
  "currency": "<string>",
  "current_period_end": "<string>",
  "current_period_start": "<string>",
  "customer": {
    "address_city": "<string>",
    "address_country": "<string>",
    "address_line1": "<string>",
    "address_line2": "<string>",
    "address_postal_code": "<string>",
    "address_state": "<string>",
    "created_at": "<string>",
    "created_by": "<string>",
    "email": "<string>",
    "environment_id": "<string>",
    "external_id": "<string>",
    "id": "<string>",
    "metadata": {},
    "name": "<string>",
    "parent_customer": "<unknown>",
    "parent_customer_id": "<string>",
    "status": "published",
    "tenant_id": "<string>",
    "updated_at": "<string>",
    "updated_by": "<string>"
  },
  "customer_id": "<string>",
  "customer_timezone": "<string>",
  "enable_true_up": true,
  "end_date": "<string>",
  "environment_id": "<string>",
  "gateway_payment_method_id": "<string>",
  "id": "<string>",
  "invoicing_customer_id": "<string>",
  "line_items": [
    {
      "billing_period": "MONTHLY",
      "commitment_amount": 123,
      "commitment_overage_factor": 123,
      "commitment_quantity": 123,
      "commitment_true_up_enabled": true,
      "commitment_type": "amount",
      "commitment_windowed": true,
      "created_at": "<string>",
      "created_by": "<string>",
      "currency": "<string>",
      "customer_id": "<string>",
      "display_name": "<string>",
      "end_date": "<string>",
      "entity_id": "<string>",
      "entity_type": "plan",
      "environment_id": "<string>",
      "id": "<string>",
      "invoice_cadence": "ARREAR",
      "metadata": {},
      "meter_display_name": "<string>",
      "meter_id": "<string>",
      "plan_display_name": "<string>",
      "price": {
        "addon": {
          "created_at": "<string>",
          "created_by": "<string>",
          "description": "<string>",
          "entitlements": [
            {
              "addon": "<unknown>",
              "created_at": "<string>",
              "created_by": "<string>",
              "display_order": 123,
              "end_date": "<string>",
              "entity_id": "<string>",
              "entity_type": "PLAN",
              "environment_id": "<string>",
              "feature": {
                "alert_settings": {
                  "alert_enabled": true,
                  "critical": {
                    "condition": "above",
                    "threshold": 123
                  },
                  "info": {
                    "condition": "above",
                    "threshold": 123
                  },
                  "warning": {
                    "condition": "above",
                    "threshold": 123
                  }
                },
                "created_at": "<string>",
                "created_by": "<string>",
                "description": "<string>",
                "environment_id": "<string>",
                "id": "<string>",
                "lookup_key": "<string>",
                "metadata": {},
                "meter": {
                  "aggregation": {
                    "bucket_size": "MONTH",
                    "field": "<string>",
                    "multiplier": "<string>",
                    "type": "COUNT"
                  },
                  "created_at": "2024-03-20T15:04:05Z",
                  "event_name": "api_request",
                  "filters": [
                    {
                      "key": "<string>",
                      "values": [
                        "<string>"
                      ]
                    }
                  ],
                  "id": "550e8400-e29b-41d4-a716-446655440000",
                  "name": "API Usage Meter",
                  "reset_usage": "BILLING_PERIOD",
                  "status": "published",
                  "tenant_id": "tenant123",
                  "updated_at": "2024-03-20T15:04:05Z"
                },
                "meter_id": "<string>",
                "name": "<string>",
                "status": "published",
                "tenant_id": "<string>",
                "type": "metered",
                "unit_plural": "<string>",
                "unit_singular": "<string>",
                "updated_at": "<string>",
                "updated_by": "<string>"
              },
              "feature_id": "<string>",
              "feature_type": "metered",
              "id": "<string>",
              "is_enabled": true,
              "is_soft_limit": true,
              "parent_entitlement_id": "<string>",
              "plan": {
                "created_at": "<string>",
                "created_by": "<string>",
                "credit_grants": [
                  {
                    "cadence": "ONETIME",
                    "conversion_rate": "<string>",
                    "created_at": "<string>",
                    "created_by": "<string>",
                    "credit_grant_anchor": "<string>",
                    "credits": "<string>",
                    "end_date": "<string>",
                    "environment_id": "<string>",
                    "expiration_duration": 123,
                    "expiration_duration_unit": "DAY",
                    "expiration_type": "NEVER",
                    "id": "<string>",
                    "metadata": {},
                    "name": "<string>",
                    "period": "DAILY",
                    "period_count": 123,
                    "plan_id": "<string>",
                    "priority": 123,
                    "scope": "PLAN",
                    "start_date": "<string>",
                    "status": "published",
                    "subscription_id": "<string>",
                    "tenant_id": "<string>",
                    "topup_conversion_rate": "<string>",
                    "updated_at": "<string>",
                    "updated_by": "<string>"
                  }
                ],
                "description": "<string>",
                "display_order": 123,
                "entitlements": "<array>",
                "environment_id": "<string>",
                "id": "<string>",
                "lookup_key": "<string>",
                "metadata": {},
                "name": "<string>",
                "prices": "<array>",
                "status": "published",
                "tenant_id": "<string>",
                "updated_at": "<string>",
                "updated_by": "<string>"
              },
              "plan_id": "<string>",
              "start_date": "<string>",
              "static_value": "<string>",
              "status": "published",
              "tenant_id": "<string>",
              "updated_at": "<string>",
              "updated_by": "<string>",
              "usage_limit": 123,
              "usage_reset_period": "MONTHLY"
            }
          ],
          "environment_id": "<string>",
          "id": "<string>",
          "lookup_key": "<string>",
          "metadata": {},
          "name": "<string>",
          "prices": "<array>",
          "status": "published",
          "tenant_id": "<string>",
          "type": "onetime",
          "updated_at": "<string>",
          "updated_by": "<string>"
        },
        "amount": "<string>",
        "billing_cadence": "RECURRING",
        "billing_model": "FLAT_FEE",
        "billing_period": "MONTHLY",
        "billing_period_count": 123,
        "conversion_rate": "<string>",
        "created_at": "<string>",
        "created_by": "<string>",
        "currency": "<string>",
        "description": "<string>",
        "display_amount": "<string>",
        "display_name": "<string>",
        "display_price_unit_amount": "<string>",
        "end_date": "<string>",
        "entity_id": "<string>",
        "entity_type": "PLAN",
        "environment_id": "<string>",
        "group": {
          "created_at": "<string>",
          "entity_ids": [
            "<string>"
          ],
          "entity_type": "<string>",
          "id": "<string>",
          "lookup_key": "<string>",
          "metadata": {},
          "name": "<string>",
          "status": "<string>",
          "updated_at": "<string>"
        },
        "group_id": "<string>",
        "id": "<string>",
        "invoice_cadence": "ARREAR",
        "lookup_key": "<string>",
        "metadata": {},
        "meter": {
          "aggregation": {
            "bucket_size": "MONTH",
            "field": "<string>",
            "multiplier": "<string>",
            "type": "COUNT"
          },
          "created_at": "2024-03-20T15:04:05Z",
          "event_name": "api_request",
          "filters": [
            {
              "key": "<string>",
              "values": [
                "<string>"
              ]
            }
          ],
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "API Usage Meter",
          "reset_usage": "BILLING_PERIOD",
          "status": "published",
          "tenant_id": "tenant123",
          "updated_at": "2024-03-20T15:04:05Z"
        },
        "meter_id": "<string>",
        "min_quantity": "<string>",
        "parent_price_id": "<string>",
        "plan": {
          "created_at": "<string>",
          "created_by": "<string>",
          "credit_grants": [
            {
              "cadence": "ONETIME",
              "conversion_rate": "<string>",
              "created_at": "<string>",
              "created_by": "<string>",
              "credit_grant_anchor": "<string>",
              "credits": "<string>",
              "end_date": "<string>",
              "environment_id": "<string>",
              "expiration_duration": 123,
              "expiration_duration_unit": "DAY",
              "expiration_type": "NEVER",
              "id": "<string>",
              "metadata": {},
              "name": "<string>",
              "period": "DAILY",
              "period_count": 123,
              "plan_id": "<string>",
              "priority": 123,
              "scope": "PLAN",
              "start_date": "<string>",
              "status": "published",
              "subscription_id": "<string>",
              "tenant_id": "<string>",
              "topup_conversion_rate": "<string>",
              "updated_at": "<string>",
              "updated_by": "<string>"
            }
          ],
          "description": "<string>",
          "display_order": 123,
          "entitlements": "<array>",
          "environment_id": "<string>",
          "id": "<string>",
          "lookup_key": "<string>",
          "metadata": {},
          "name": "<string>",
          "prices": "<array>",
          "status": "published",
          "tenant_id": "<string>",
          "updated_at": "<string>",
          "updated_by": "<string>"
        },
        "price_unit": "<string>",
        "price_unit_amount": "<string>",
        "price_unit_id": "<string>",
        "price_unit_tiers": [
          {
            "flat_amount": "<string>",
            "unit_amount": "<string>",
            "up_to": 123
          }
        ],
        "price_unit_type": "FIAT",
        "pricing_unit": {
          "base_currency": "<string>",
          "code": "<string>",
          "conversion_rate": "<string>",
          "created_at": "<string>",
          "created_by": "<string>",
          "environment_id": "<string>",
          "id": "<string>",
          "metadata": {},
          "name": "<string>",
          "status": "published",
          "symbol": "<string>",
          "tenant_id": "<string>",
          "updated_at": "<string>",
          "updated_by": "<string>"
        },
        "start_date": "<string>",
        "status": "published",
        "tenant_id": "<string>",
        "tier_mode": "VOLUME",
        "tiers": [
          {
            "flat_amount": "<string>",
            "unit_amount": "<string>",
            "up_to": 123
          }
        ],
        "transform_quantity": {
          "divide_by": 123,
          "round": "up"
        },
        "trial_period": 123,
        "type": "USAGE",
        "updated_at": "<string>",
        "updated_by": "<string>"
      },
      "price_id": "<string>",
      "price_type": "USAGE",
      "price_unit": "<string>",
      "price_unit_id": "<string>",
      "quantity": "<string>",
      "start_date": "<string>",
      "status": "published",
      "subscription_id": "<string>",
      "subscription_phase_id": "<string>",
      "tenant_id": "<string>",
      "trial_period": 123,
      "updated_at": "<string>",
      "updated_by": "<string>"
    }
  ],
  "lookup_key": "<string>",
  "metadata": {},
  "overage_factor": "<string>",
  "pause_status": "none",
  "pauses": [
    {
      "created_at": "<string>",
      "created_by": "<string>",
      "environment_id": "<string>",
      "id": "<string>",
      "metadata": {},
      "original_period_end": "<string>",
      "original_period_start": "<string>",
      "pause_end": "<string>",
      "pause_mode": "immediate",
      "pause_start": "<string>",
      "pause_status": "none",
      "reason": "<string>",
      "resume_mode": "immediate",
      "resumed_at": "<string>",
      "status": "published",
      "subscription_id": "<string>",
      "tenant_id": "<string>",
      "updated_at": "<string>",
      "updated_by": "<string>"
    }
  ],
  "payment_behavior": "<string>",
  "phases": [
    {
      "created_at": "<string>",
      "created_by": "<string>",
      "end_date": "<string>",
      "environment_id": "<string>",
      "id": "<string>",
      "metadata": {},
      "start_date": "<string>",
      "status": "published",
      "subscription_id": "<string>",
      "tenant_id": "<string>",
      "updated_at": "<string>",
      "updated_by": "<string>"
    }
  ],
  "plan": {
    "created_at": "<string>",
    "created_by": "<string>",
    "credit_grants": [
      {
        "cadence": "ONETIME",
        "conversion_rate": "<string>",
        "created_at": "<string>",
        "created_by": "<string>",
        "credit_grant_anchor": "<string>",
        "credits": "<string>",
        "end_date": "<string>",
        "environment_id": "<string>",
        "expiration_duration": 123,
        "expiration_duration_unit": "DAY",
        "expiration_type": "NEVER",
        "id": "<string>",
        "metadata": {},
        "name": "<string>",
        "period": "DAILY",
        "period_count": 123,
        "plan_id": "<string>",
        "priority": 123,
        "scope": "PLAN",
        "start_date": "<string>",
        "status": "published",
        "subscription_id": "<string>",
        "tenant_id": "<string>",
        "topup_conversion_rate": "<string>",
        "updated_at": "<string>",
        "updated_by": "<string>"
      }
    ],
    "description": "<string>",
    "display_order": 123,
    "entitlements": "<array>",
    "environment_id": "<string>",
    "id": "<string>",
    "lookup_key": "<string>",
    "metadata": {},
    "name": "<string>",
    "prices": "<array>",
    "status": "published",
    "tenant_id": "<string>",
    "updated_at": "<string>",
    "updated_by": "<string>"
  },
  "plan_id": "<string>",
  "proration_behavior": "create_prorations",
  "start_date": "<string>",
  "status": "published",
  "subscription_status": "active",
  "tenant_id": "<string>",
  "trial_end": "<string>",
  "trial_start": "<string>",
  "updated_at": "<string>",
  "updated_by": "<string>",
  "version": 123
}

Authorizations

​
x-api-key
string
header
required

Enter your API key in the format x-api-key <api-key>*

Path Parameters

​
id
string
required

Subscription ID

Query Parameters

​
expand
string

Comma-separated list of fields to expand (e.g., 'subscription_line_items,prices,plan')

Response

OK

​
active_pause_id
string

ActivePauseID references the current active pause configuration This will be null if no pause is active or scheduled

​
billing_anchor
string

BillingAnchor is the reference point that aligns future billing cycle dates. It sets the day of week for week intervals, the day of month for month and year intervals, and the month of year for year intervals. The timestamp is in UTC format.

​
billing_cadence
enum<string>
Available options:
RECURRING,
ONETIME
​
billing_cycle
enum<string>
Available options:
anniversary,
calendar
​
billing_period
enum<string>
Available options:
MONTHLY,
ANNUAL,
WEEKLY,
DAILY,
QUARTERLY,
HALF_YEARLY
​
billing_period_count
integer

BillingPeriodCount is the total number units of the billing period.

​
cancel_at
string

CancelAt is the date the subscription will be canceled

​
cancel_at_period_end
boolean

CancelAtPeriodEnd is whether the subscription was canceled at the end of the current period

​
cancelled_at
string

CanceledAt is the date the subscription was canceled

​
collection_method
string

CollectionMethod determines how invoices are collected

​
commitment_amount
string

CommitmentAmount is the minimum amount a customer commits to paying for a billing period

​
coupon_associations
object[]

CouponAssociations are included when "coupon_associations" is in expand parameter

​
created_at
string
​
created_by
string
​
credit_grants
object[]

CreditGrants are included when "credit_grants" is in expand parameter

​
currency
string

Currency is the currency of the subscription in lowercase 3 digit ISO codes

​
current_period_end
string

CurrentPeriodEnd is the end of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.

​
current_period_start
string

CurrentPeriodStart is the end of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created.

​
customer
object

Customer response object containing all customer information

​
customer_id
string

CustomerID is the identifier for the customer in our system

​
customer_timezone
string
​
enable_true_up
boolean
​
end_date
string

EndDate is the end date of the subscription

​
environment_id
string

EnvironmentID is the environment identifier for the subscription

​
gateway_payment_method_id
string

GatewayPaymentMethodID is the gateway payment method ID for this subscription

​
id
string

ID is the unique identifier for the subscription

​
invoicing_customer_id
string

InvoicingCustomerID is the customer ID to use for invoicing This can differ from the subscription customer (e.g., parent company invoicing for child company)

​
line_items
object[]

LineItems is expanded only if "subscription_line_items" is in expand parameter Each line item can optionally include expanded price data

​
lookup_key
string

LookupKey is the key used to lookup the subscription in our system

​
metadata
object
​
overage_factor
string

OverageFactor is a multiplier applied to usage beyond the commitment amount

​
pause_status
enum<string>
Available options:
none,
active,
scheduled,
completed,
cancelled
​
pauses
object[]

Pauses are included when subscription has pause status

​
payment_behavior
string

PaymentBehavior determines how subscription payments are handled

​
phases
object[]

Phases are included when "phases" is in expand parameter

​
plan
object
​
plan_id
string

PlanID is the identifier for the plan in our system

​
proration_behavior
enum<string>
Available options:
create_prorations,
none
​
start_date
string

StartDate is the start date of the subscription

​
status
enum<string>
Available options:
published,
deleted,
archived
​
subscription_status
enum<string>
Available options:
active,
paused,
cancelled,
incomplete,
trialing,
draft
​
tenant_id
string
​
trial_end
string

TrialEnd is the end date of the trial period

​
trial_start
string

TrialStart is the start date of the trial period

​
updated_at
string
​
updated_by
string
​
version
integer

Version is used for optimistic locking