Customers
Invoices
Wallets
Entitlements
Environments
Events
Features
Payments
Integrations
Subscriptions
Tenants
Users
Create subscription
Create a new subscription
curl --request POST \
--url https://api.cloud.flexprice.io/v1/subscriptions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '{
"billing_cadence": "RECURRING",
"billing_period": "MONTHLY",
"billing_period_count": 2,
"currency": "<string>",
"customer_id": "<string>",
"end_date": "<string>",
"lookup_key": "<string>",
"metadata": {},
"plan_id": "<string>",
"start_date": "<string>",
"trial_end": "<string>",
"trial_start": "<string>"
}'{
"active_pause_id": "<string>",
"billing_anchor": "<string>",
"billing_cadence": "RECURRING",
"billing_period": "MONTHLY",
"billing_period_count": 123,
"cancel_at": "<string>",
"cancel_at_period_end": true,
"cancelled_at": "<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>",
"end_date": "<string>",
"environment_id": "<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>",
"environment_id": "<string>",
"id": "<string>",
"invoice_cadence": "ARREAR",
"metadata": {},
"meter_display_name": "<string>",
"meter_id": "<string>",
"plan_display_name": "<string>",
"plan_id": "<string>",
"price_id": "<string>",
"price_type": "USAGE",
"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": {},
"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>"
}
],
"plan": {
"created_at": "<string>",
"created_by": "<string>",
"description": "<string>",
"entitlements": [
{
"created_at": "<string>",
"created_by": "<string>",
"environment_id": "<string>",
"feature": {
"created_at": "<string>",
"created_by": "<string>",
"description": "<string>",
"environment_id": "<string>",
"id": "<string>",
"lookup_key": "<string>",
"metadata": {},
"meter": {
"aggregation": {
"field": "<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,
"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>",
"name": "<string>",
"prices": [
{
"amount": 123,
"billing_cadence": "RECURRING",
"billing_model": "FLAT_FEE",
"billing_period": "MONTHLY",
"billing_period_count": 123,
"created_at": "<string>",
"created_by": "<string>",
"currency": "<string>",
"description": "<string>",
"display_amount": "<string>",
"environment_id": "<string>",
"id": "<string>",
"invoice_cadence": "ARREAR",
"lookup_key": "<string>",
"metadata": {},
"meter": {
"aggregation": {
"field": "<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>",
"plan_id": "<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>",
"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
Enter your API key in the format x-api-key <api-key>*
Body
RECURRING, ONETIME MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY x >= 1Response
ActivePauseID references the current active pause configuration This will be null if no pause is active or scheduled
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.
RECURRING, ONETIME MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY BillingPeriodCount is the total number units of the billing period.
CancelAt is the date the subscription will be canceled
CancelAtPeriodEnd is whether the subscription was canceled at the end of the current period
CanceledAt is the date the subscription was canceled
Currency is the currency of the subscription in lowercase 3 digit ISO codes
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.
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.
AddressCity is the city of the customer's address
AddressCountry is the country of the customer's address (ISO 3166-1 alpha-2)
AddressLine1 is the first line of the customer's address
AddressLine2 is the second line of the customer's address
AddressPostalCode is the postal code of the customer's address
AddressState is the state of the customer's address
Email is the email of the customer
EnvironmentID is the environment identifier for the customer
ExternalID is the external identifier for the customer
ID is the unique identifier for the customer
Name is the name of the customer
published, deleted, archived CustomerID is the identifier for the customer in our system
EndDate is the end date of the subscription
EnvironmentID is the environment identifier for the subscription
ID is the unique identifier for the subscription
MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY ARREAR, ADVANCE USAGE, FIXED published, deleted, archived LookupKey is the key used to lookup the subscription in our system
none, active, scheduled, completed, cancelled EnvironmentID is the environment identifier for the pause
ID is the unique identifier for the subscription pause
OriginalPeriodEnd is the end of the billing period when the pause was created
OriginalPeriodStart is the start of the billing period when the pause was created
PauseEnd is when the pause will end (null for indefinite)
immediate, scheduled, period_end PauseStart is when the pause actually started
none, active, scheduled, completed, cancelled Reason is the reason for pausing
immediate, scheduled, auto ResumedAt is when the pause was actually ended (if manually resumed)
published, deleted, archived SubscriptionID is the identifier for the subscription
"2024-03-20T15:04:05Z"
"api_request"
"550e8400-e29b-41d4-a716-446655440000"
"API Usage Meter"
BILLING_PERIOD, NEVER "published"
"tenant123"
"2024-03-20T15:04:05Z"
published, deleted, archived metered, boolean, static metered, boolean, static metered, boolean, static published, deleted, archived MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY Amount stored in main currency units (e.g., dollars, not cents) For USD: 12.50 means $12.50
RECURRING, ONETIME FLAT_FEE, PACKAGE, TIERED MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY BillingPeriodCount is the count of the billing period ex 1, 3, 6, 12
Currency 3 digit ISO currency code in lowercase ex usd, eur, gbp
Description of the price
DisplayAmount is the formatted amount with currency symbol For USD: $12.50
EnvironmentID is the environment identifier for the price
ID uuid identifier for the price
ARREAR, ADVANCE LookupKey used for looking up the price in the database
MeterID is the id of the meter for usage based pricing
PlanID is the id of the plan for plan based pricing
published, deleted, archived VOLUME, SLAB TrialPeriod is the number of days for the trial period Note: This is only applicable for recurring prices (BILLING_CADENCE_RECURRING)
USAGE, FIXED published, deleted, archived published, deleted, archived MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY Amount stored in main currency units (e.g., dollars, not cents) For USD: 12.50 means $12.50
RECURRING, ONETIME FLAT_FEE, PACKAGE, TIERED MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY BillingPeriodCount is the count of the billing period ex 1, 3, 6, 12
Currency 3 digit ISO currency code in lowercase ex usd, eur, gbp
Description of the price
DisplayAmount is the formatted amount with currency symbol For USD: $12.50
EnvironmentID is the environment identifier for the price
ID uuid identifier for the price
ARREAR, ADVANCE LookupKey used for looking up the price in the database
Field is the key in $event.properties on which the aggregation is to be applied For ex if the aggregation type is sum for API usage, the field could be "duration_ms"
COUNT, SUM, AVG, COUNT_UNIQUE "2024-03-20T15:04:05Z"
"api_request"
Key is the key for the filter from $event.properties Currently we support only first level keys in the properties and not nested keys
Values are the possible values for the filter to be considered for the meter For ex "model_name" could have values "o1-mini", "gpt-4o" etc
"550e8400-e29b-41d4-a716-446655440000"
"API Usage Meter"
BILLING_PERIOD, NEVER "published"
"tenant123"
"2024-03-20T15:04:05Z"
MeterID is the id of the meter for usage based pricing
PlanID is the id of the plan for plan based pricing
published, deleted, archived VOLUME, SLAB FlatAmount is the flat amount for the given tier and it is applied on top of the unit amount*quantity. It solves cases in banking like 2.7% + 5c
UnitAmount is the amount per unit for the given tier
Upto is the quantity up to which this tier applies. It is null for the last tier
TrialPeriod is the number of days for the trial period Note: This is only applicable for recurring prices (BILLING_CADENCE_RECURRING)
USAGE, FIXED published, deleted, archived PlanID is the identifier for the plan in our system
StartDate is the start date of the subscription
published, deleted, archived active, paused, cancelled, incomplete, incomplete_expired, past_due, trialing, unpaid TrialEnd is the end date of the trial period
TrialStart is the start date of the trial period
Version is used for optimistic locking
curl --request POST \
--url https://api.cloud.flexprice.io/v1/subscriptions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '{
"billing_cadence": "RECURRING",
"billing_period": "MONTHLY",
"billing_period_count": 2,
"currency": "<string>",
"customer_id": "<string>",
"end_date": "<string>",
"lookup_key": "<string>",
"metadata": {},
"plan_id": "<string>",
"start_date": "<string>",
"trial_end": "<string>",
"trial_start": "<string>"
}'{
"active_pause_id": "<string>",
"billing_anchor": "<string>",
"billing_cadence": "RECURRING",
"billing_period": "MONTHLY",
"billing_period_count": 123,
"cancel_at": "<string>",
"cancel_at_period_end": true,
"cancelled_at": "<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>",
"end_date": "<string>",
"environment_id": "<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>",
"environment_id": "<string>",
"id": "<string>",
"invoice_cadence": "ARREAR",
"metadata": {},
"meter_display_name": "<string>",
"meter_id": "<string>",
"plan_display_name": "<string>",
"plan_id": "<string>",
"price_id": "<string>",
"price_type": "USAGE",
"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": {},
"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>"
}
],
"plan": {
"created_at": "<string>",
"created_by": "<string>",
"description": "<string>",
"entitlements": [
{
"created_at": "<string>",
"created_by": "<string>",
"environment_id": "<string>",
"feature": {
"created_at": "<string>",
"created_by": "<string>",
"description": "<string>",
"environment_id": "<string>",
"id": "<string>",
"lookup_key": "<string>",
"metadata": {},
"meter": {
"aggregation": {
"field": "<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,
"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>",
"name": "<string>",
"prices": [
{
"amount": 123,
"billing_cadence": "RECURRING",
"billing_model": "FLAT_FEE",
"billing_period": "MONTHLY",
"billing_period_count": 123,
"created_at": "<string>",
"created_by": "<string>",
"currency": "<string>",
"description": "<string>",
"display_amount": "<string>",
"environment_id": "<string>",
"id": "<string>",
"invoice_cadence": "ARREAR",
"lookup_key": "<string>",
"metadata": {},
"meter": {
"aggregation": {
"field": "<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>",
"plan_id": "<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>",
"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
}