Skip to main content
GET
/
subscriptions
/
{id}
Get subscription
curl --request GET \
  --url https://api.cloud.flexprice.io/v1/subscriptions/{id} \
  --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": 123,
  "coupon_associations": [
    {
      "coupon": {
        "amount_off": 123,
        "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": 123,
        "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>",
      "environment_id": "<string>",
      "id": "<string>",
      "metadata": {},
      "status": "published",
      "subscription_id": "<string>",
      "subscription_line_item_id": "<string>",
      "tenant_id": "<string>",
      "updated_at": "<string>",
      "updated_by": "<string>"
    }
  ],
  "created_at": "<string>",
  "created_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>",
    "status": "published",
    "tenant_id": "<string>",
    "updated_at": "<string>",
    "updated_by": "<string>"
  },
  "customer_id": "<string>",
  "customer_timezone": "<string>",
  "end_date": "<string>",
  "environment_id": "<string>",
  "gateway_payment_method_id": "<string>",
  "id": "<string>",
  "latest_invoice": {
    "amount_due": 123,
    "amount_paid": 123,
    "amount_remaining": 123,
    "billing_period": "<string>",
    "billing_reason": "<string>",
    "billing_sequence": 123,
    "coupon_applications": [
      {
        "applied_at": "<string>",
        "coupon_association_id": "<string>",
        "coupon_id": "<string>",
        "coupon_snapshot": {},
        "created_at": "<string>",
        "created_by": "<string>",
        "currency": "<string>",
        "discount_percentage": 123,
        "discount_type": "fixed",
        "discounted_amount": 123,
        "environment_id": "<string>",
        "final_price": 123,
        "id": "<string>",
        "invoice_id": "<string>",
        "invoice_line_item_id": "<string>",
        "metadata": {},
        "original_price": 123,
        "status": "published",
        "subscription_id": "<string>",
        "tenant_id": "<string>",
        "updated_at": "<string>",
        "updated_by": "<string>"
      }
    ],
    "created_at": "<string>",
    "created_by": "<string>",
    "currency": "<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>",
      "status": "published",
      "tenant_id": "<string>",
      "updated_at": "<string>",
      "updated_by": "<string>"
    },
    "customer_id": "<string>",
    "description": "<string>",
    "due_date": "<string>",
    "finalized_at": "<string>",
    "id": "<string>",
    "idempotency_key": "<string>",
    "invoice_number": "<string>",
    "invoice_pdf_url": "<string>",
    "invoice_status": "DRAFT",
    "invoice_type": "SUBSCRIPTION",
    "line_items": [
      {
        "amount": 123,
        "created_at": "<string>",
        "created_by": "<string>",
        "currency": "<string>",
        "customer_id": "<string>",
        "display_name": "<string>",
        "entity_id": "<string>",
        "entity_type": "<string>",
        "id": "<string>",
        "invoice_id": "<string>",
        "metadata": {},
        "meter_display_name": "<string>",
        "meter_id": "<string>",
        "period_end": "<string>",
        "period_start": "<string>",
        "plan_display_name": "<string>",
        "plan_id": "<string>",
        "price_id": "<string>",
        "price_type": "<string>",
        "price_unit": "<string>",
        "price_unit_amount": 123,
        "price_unit_id": "<string>",
        "quantity": 123,
        "status": "<string>",
        "subscription_id": "<string>",
        "tenant_id": "<string>",
        "updated_at": "<string>",
        "updated_by": "<string>",
        "usage_analytics": [
          {
            "cost": "<string>",
            "event_count": 123,
            "percentage": "<string>",
            "source": "<string>",
            "usage": "<string>"
          }
        ],
        "usage_breakdown": [
          {
            "cost": "<string>",
            "event_count": 123,
            "grouped_by": {},
            "percentage": "<string>",
            "usage": "<string>"
          }
        ]
      }
    ],
    "metadata": {},
    "overpaid_amount": 123,
    "paid_at": "<string>",
    "payment_status": "INITIATED",
    "period_end": "<string>",
    "period_start": "<string>",
    "status": "<string>",
    "subscription": {},
    "subscription_id": "<string>",
    "subtotal": 123,
    "taxes": [
      {
        "applied_at": "<string>",
        "created_at": "<string>",
        "created_by": "<string>",
        "currency": "<string>",
        "entity_id": "<string>",
        "entity_type": "customer",
        "environment_id": "<string>",
        "id": "<string>",
        "idempotency_key": "<string>",
        "metadata": {},
        "status": "published",
        "tax_amount": 123,
        "tax_association_id": "<string>",
        "tax_rate": {
          "code": "<string>",
          "created_at": "<string>",
          "created_by": "<string>",
          "description": "<string>",
          "environment_id": "<string>",
          "fixed_value": 123,
          "id": "<string>",
          "metadata": {},
          "name": "<string>",
          "percentage_value": 123,
          "scope": "INTERNAL",
          "status": "published",
          "tax_rate_status": "ACTIVE",
          "tax_rate_type": "percentage",
          "tenant_id": "<string>",
          "updated_at": "<string>",
          "updated_by": "<string>"
        },
        "tax_rate_id": "<string>",
        "taxable_amount": 123,
        "tenant_id": "<string>",
        "updated_at": "<string>",
        "updated_by": "<string>"
      }
    ],
    "tenant_id": "<string>",
    "total": 123,
    "total_discount": 123,
    "total_tax": 123,
    "updated_at": "<string>",
    "updated_by": "<string>",
    "version": 123,
    "voided_at": "<string>"
  },
  "line_items": [
    {
      "billing_period": "MONTHLY",
      "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_id": "<string>",
      "price_type": "USAGE",
      "price_unit": "<string>",
      "price_unit_id": "<string>",
      "quantity": 123,
      "start_date": "<string>",
      "status": "published",
      "subscription_id": "<string>",
      "tenant_id": "<string>",
      "trial_period": 123,
      "updated_at": "<string>",
      "updated_by": "<string>"
    }
  ],
  "lookup_key": "<string>",
  "metadata": {},
  "overage_factor": 123,
  "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>",
  "plan": {
    "created_at": "<string>",
    "created_by": "<string>",
    "credit_grants": [
      {
        "cadence": "ONETIME",
        "created_at": "<string>",
        "created_by": "<string>",
        "credits": 123,
        "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",
        "status": "published",
        "subscription_id": "<string>",
        "tenant_id": "<string>",
        "updated_at": "<string>",
        "updated_by": "<string>"
      }
    ],
    "description": "<string>",
    "display_order": 123,
    "entitlements": [
      {
        "addon": {
          "created_at": "<string>",
          "created_by": "<string>",
          "description": "<string>",
          "entitlements": [
            {}
          ],
          "environment_id": "<string>",
          "id": "<string>",
          "lookup_key": "<string>",
          "metadata": {},
          "name": "<string>",
          "prices": [
            {
              "amount": 123,
              "billing_cadence": "RECURRING",
              "billing_model": "FLAT_FEE",
              "billing_period": "MONTHLY",
              "billing_period_count": 123,
              "conversion_rate": 123,
              "created_at": "<string>",
              "created_by": "<string>",
              "currency": "<string>",
              "description": "<string>",
              "display_amount": "<string>",
              "display_price_unit_amount": "<string>",
              "end_date": "<string>",
              "entity_id": "<string>",
              "entity_type": "PLAN",
              "environment_id": "<string>",
              "id": "<string>",
              "invoice_cadence": "ARREAR",
              "lookup_key": "<string>",
              "metadata": {},
              "meter": {
                "aggregation": {
                  "bucket_size": "MINUTE",
                  "field": "<string>",
                  "multiplier": 123,
                  "type": "COUNT"
                },
                "created_at": "2024-03-20T15:04:05Z",
                "event_name": "api_request",
                "filters": [
                  {
                    "key": "<string>",
                    "values": [
                      "<any>"
                    ]
                  }
                ],
                "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>",
              "parent_price_id": "<string>",
              "plan_id": "<string>",
              "price_unit": "<string>",
              "price_unit_amount": 123,
              "price_unit_id": "<string>",
              "price_unit_tiers": [
                {
                  "flat_amount": 123,
                  "unit_amount": 123,
                  "up_to": 123
                }
              ],
              "price_unit_type": "FIAT",
              "pricing_unit": {
                "base_currency": "<string>",
                "code": "<string>",
                "conversion_rate": 123,
                "created_at": "<string>",
                "created_by": "<string>",
                "environment_id": "<string>",
                "id": "<string>",
                "name": "<string>",
                "precision": 123,
                "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": 123,
                  "unit_amount": 123,
                  "up_to": 123
                }
              ],
              "transform_quantity": {
                "divide_by": 123,
                "round": "<string>"
              },
              "trial_period": 123,
              "type": "USAGE",
              "updated_at": "<string>",
              "updated_by": "<string>"
            }
          ],
          "status": "published",
          "tenant_id": "<string>",
          "type": "onetime",
          "updated_at": "<string>",
          "updated_by": "<string>"
        },
        "created_at": "<string>",
        "created_by": "<string>",
        "display_order": 123,
        "entity_id": "<string>",
        "entity_type": "PLAN",
        "environment_id": "<string>",
        "feature": {
          "created_at": "<string>",
          "created_by": "<string>",
          "description": "<string>",
          "environment_id": "<string>",
          "id": "<string>",
          "lookup_key": "<string>",
          "metadata": {},
          "meter": {
            "aggregation": {
              "bucket_size": "MINUTE",
              "field": "<string>",
              "multiplier": 123,
              "type": "COUNT"
            },
            "created_at": "2024-03-20T15:04:05Z",
            "event_name": "api_request",
            "filters": [
              {
                "key": "<string>",
                "values": [
                  "<any>"
                ]
              }
            ],
            "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,
        "plan": {},
        "plan_id": "<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": [
      {
        "amount": 123,
        "billing_cadence": "RECURRING",
        "billing_model": "FLAT_FEE",
        "billing_period": "MONTHLY",
        "billing_period_count": 123,
        "conversion_rate": 123,
        "created_at": "<string>",
        "created_by": "<string>",
        "currency": "<string>",
        "description": "<string>",
        "display_amount": "<string>",
        "display_price_unit_amount": "<string>",
        "end_date": "<string>",
        "entity_id": "<string>",
        "entity_type": "PLAN",
        "environment_id": "<string>",
        "id": "<string>",
        "invoice_cadence": "ARREAR",
        "lookup_key": "<string>",
        "metadata": {},
        "meter": {
          "aggregation": {
            "bucket_size": "MINUTE",
            "field": "<string>",
            "multiplier": 123,
            "type": "COUNT"
          },
          "created_at": "2024-03-20T15:04:05Z",
          "event_name": "api_request",
          "filters": [
            {
              "key": "<string>",
              "values": [
                "<any>"
              ]
            }
          ],
          "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>",
        "parent_price_id": "<string>",
        "plan_id": "<string>",
        "price_unit": "<string>",
        "price_unit_amount": 123,
        "price_unit_id": "<string>",
        "price_unit_tiers": [
          {
            "flat_amount": 123,
            "unit_amount": 123,
            "up_to": 123
          }
        ],
        "price_unit_type": "FIAT",
        "pricing_unit": {
          "base_currency": "<string>",
          "code": "<string>",
          "conversion_rate": 123,
          "created_at": "<string>",
          "created_by": "<string>",
          "environment_id": "<string>",
          "id": "<string>",
          "name": "<string>",
          "precision": 123,
          "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": 123,
            "unit_amount": 123,
            "up_to": 123
          }
        ],
        "transform_quantity": {
          "divide_by": 123,
          "round": "<string>"
        },
        "trial_period": 123,
        "type": "USAGE",
        "updated_at": "<string>",
        "updated_by": "<string>"
      }
    ],
    "status": "published",
    "tenant_id": "<string>",
    "updated_at": "<string>",
    "updated_by": "<string>"
  },
  "plan_id": "<string>",
  "proration_behavior": "create_prorations",
  "schedule": {
    "created_at": "<string>",
    "current_phase_index": 123,
    "end_behavior": "RELEASE",
    "id": "<string>",
    "phases": [
      {
        "commitment_amount": 123,
        "created_at": "<string>",
        "credit_grants": [
          {
            "cadence": "ONETIME",
            "created_at": "<string>",
            "created_by": "<string>",
            "credits": 123,
            "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",
            "status": "published",
            "subscription_id": "<string>",
            "tenant_id": "<string>",
            "updated_at": "<string>",
            "updated_by": "<string>"
          }
        ],
        "end_date": "<string>",
        "id": "<string>",
        "line_items": [
          {
            "billing_period": "MONTHLY",
            "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_id": "<string>",
            "price_type": "USAGE",
            "price_unit": "<string>",
            "price_unit_id": "<string>",
            "quantity": 123,
            "start_date": "<string>",
            "status": "published",
            "subscription_id": "<string>",
            "tenant_id": "<string>",
            "trial_period": 123,
            "updated_at": "<string>",
            "updated_by": "<string>"
          }
        ],
        "overage_factor": 123,
        "phase_index": 123,
        "schedule_id": "<string>",
        "start_date": "<string>",
        "updated_at": "<string>"
      }
    ],
    "start_date": "<string>",
    "status": "ACTIVE",
    "subscription_id": "<string>",
    "updated_at": "<string>"
  },
  "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

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
number

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

​
coupon_associations
object[]

CouponAssociations are the coupon associations for this subscription

​
created_at
string
​
created_by
string
​
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
​
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

​
latest_invoice
object
​
line_items
object[]
​
lookup_key
string

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

​
metadata
object
​
overage_factor
number

OverageFactor is a multiplier applied to usage beyond the commitment amount

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

PaymentBehavior determines how subscription payments are handled

​
plan
object
​
plan_id
string

PlanID is the identifier for the plan in our system

​
proration_behavior
enum<string>
Available options:
create_prorations,
none
​
schedule
object
​
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,
incomplete_expired,
past_due,
trialing,
unpaid
​
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

⌘I