Create Subscription

Create a new subscription for a customer. Use when onboarding a customer to a plan or starting a new subscription. Supports draft subscriptions (activate later) or active from start.

POST /v1/subscriptions

Create Subscription

cURL

curl --request POST \
  --url https://api.example.com/v1/subscriptions \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "<string>",
  "external_customer_id": "<string>",
  "plan_id": "<string>",
  "currency": "<string>",
  "billing_cadence": "<string>",
  "billing_period": "<string>",
  "billing_period_count": 123,
  "billing_cycle": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "trial_start": "<string>",
  "trial_end": "<string>",
  "lookup_key": "<string>",
  "metadata": {},
  "collection_method": "<string>",
  "payment_behavior": "<string>",
  "subscription_status": "<string>",
  "commitment_amount": "<string>",
  "commitment_duration": "<string>",
  "overage_factor": "<string>",
  "enable_true_up": true,
  "proration_behavior": "<string>",
  "customer_timezone": "<string>",
  "parent_subscription_id": "<string>",
  "payment_terms": "<string>",
  "invoice_billing": "<string>",
  "override_line_items": [
    {
      "override_line_items[].price_id": "<string>",
      "override_line_items[].quantity": "<string>",
      "override_line_items[].amount": "<string>"
    }
  ],
  "line_items": [
    {
      "line_items[].price_id": "<string>",
      "line_items[].quantity": "<string>",
      "line_items[].display_name": "<string>"
    }
  ],
  "phases": [
    {
      "phases[].start_date": "<string>",
      "phases[].end_date": "<string>",
      "phases[].override_line_items": [
        {}
      ]
    }
  ]
}
'

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>",
  "start_date": "<string>",
  "end_date": "<string>",
  "current_period_start": "<string>",
  "current_period_end": "<string>",
  "trial_start": "<string>",
  "trial_end": "<string>",
  "metadata": {},
  "created_at": "<string>",
  "updated_at": "<string>",
  "plan": {},
  "customer": {}
}

Request Body

customer_id · string

FlexPrice customer ID. Required if external_customer_id is not provided.

Example: "cust_a1b2c3d4e5f6g7h8i9j0"

external_customer_id · string

Your internal customer ID (must match the external_id used when creating the customer). Required if customer_id is not provided.

Example: "customer-12345"

plan_id · string · required

ID of the plan to subscribe to.

Example: "plan_a1b2c3d4e5f6g7h8i9j0"

currency · string · required

Three-letter ISO currency code (lowercase).

Example: "usd"

billing_cadence · string · required

Billing frequency.

Options: "IN_ADVANCE", "IN_ARREARS"

billing_period · string · required

Billing period unit.

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

billing_period_count · integer · default: "1"

Number of billing periods in each billing cycle.

Example: 3 (for quarterly billing with monthly periods)

billing_cycle · string · default: "ANNIVERSARY"

Determines billing date calculation.

Options: "ANNIVERSARY" (uses start date), "CALENDAR" (uses calendar dates)

start_date · string

ISO 8601 timestamp for when the subscription starts. Defaults to now.

Example: "2024-03-20T00:00:00Z"

end_date · string

ISO 8601 timestamp for when the subscription ends (optional).

Example: "2025-03-20T00:00:00Z"

trial_start · string

ISO 8601 timestamp for trial period start.

Example: "2024-03-20T00:00:00Z"

trial_end · string

ISO 8601 timestamp for trial period end.

Example: "2024-04-20T00:00:00Z"

lookup_key · string

Optional unique identifier for programmatic lookup.

Example: "customer-12345-pro-subscription"

metadata · object

Arbitrary key-value pairs for storing additional information.

Example: {"source": "website", "campaign": "spring2024"}

collection_method · string · default: "CHARGE_AUTOMATICALLY"

How invoices are collected.

Options: "CHARGE_AUTOMATICALLY", "SEND_INVOICE"

payment_behavior · string · default: "DEFAULT_ACTIVE"

Payment handling behavior.

Options: "DEFAULT_ACTIVE", "DEFAULT_INCOMPLETE", "ALLOW_INCOMPLETE", "ERROR_IF_INCOMPLETE"

subscription_status · string

Initial status. Set to “DRAFT” to create without activating.

Options: "ACTIVE", "DRAFT", "INCOMPLETE"

commitment_amount · string

Minimum committed amount for the billing period (decimal as string).

Example: "1000.00"

commitment_duration · string

Time frame of the commitment.

Options: "MONTH", "QUARTER", "YEAR"

overage_factor · string

Multiplier for usage beyond commitment (decimal as string).

Example: "1.5"

enable_true_up · boolean · default: "false"

Whether to apply true-up fee when usage is below commitment.

proration_behavior · string · default: "NONE"

How proration is handled.

Options: "CREATE_PRORATIONS", "NONE"

customer_timezone · string · default: "UTC"

Customer’s timezone for billing calculations.

Example: "America/New_York"

parent_subscription_id · string

Parent subscription ID for hierarchy (e.g., child subscription under a parent).

Example: "sub_parent123"

payment_terms · string

Payment terms for invoice due date.

Options: "15_NET", "30_NET", "45_NET", "60_NET", "75_NET", "90_NET"

invoice_billing · string · default: "INVOICE_TO_SELF"

Determines which customer receives invoices.

Options: "INVOICE_TO_PARENT", "INVOICE_TO_SELF"

override_line_items · array

Customize specific prices for this subscription.

Show override_line_items properties

override_line_items[].price_id · string · required

ID of the plan price to override.

override_line_items[].quantity · string

Custom quantity (decimal as string).

override_line_items[].amount · string

Custom amount (decimal as string).

line_items · array

Additional line items to add at creation (in addition to plan prices).

Show line_items properties

line_items[].price_id · string · required

ID of the price to add.

line_items[].quantity · string · required

Quantity (decimal as string).

line_items[].display_name · string

Custom display name for this line item.

phases · array

Subscription phases for phased pricing.

Show phases properties

phases[].start_date · string · required

ISO 8601 timestamp for phase start.

phases[].end_date · string

ISO 8601 timestamp for phase end (required for all phases except last).

phases[].override_line_items · array

Price overrides for this phase.

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.

currency · string

Currency code.

billing_cadence · string

Billing frequency.

billing_period · string

Billing period unit.

billing_period_count · integer

Number of billing periods per cycle.

billing_anchor · string

ISO 8601 timestamp of the billing anchor date.

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.

trial_start · string

ISO 8601 timestamp of trial start (if applicable).

trial_end · string

ISO 8601 timestamp of trial end (if applicable).

metadata · object

Custom metadata.

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 (if included).

customer · object

Customer details (if included).

Example Request

cURL

curl --request POST \
  --url https://api.flexprice.io/v1/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_id": "cust_a1b2c3d4e5f6g7h8i9j0",
    "plan_id": "plan_a1b2c3d4e5f6g7h8i9j0",
    "currency": "usd",
    "billing_cadence": "IN_ADVANCE",
    "billing_period": "MONTH",
    "billing_period_count": 1,
    "start_date": "2024-03-20T00:00:00Z",
    "metadata": {
      "source": "website"
    }
  }'

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",
  "start_date": "2024-03-20T00:00:00Z",
  "current_period_start": "2024-03-20T00:00:00Z",
  "current_period_end": "2024-04-20T00:00:00Z",
  "metadata": {
    "source": "website"
  },
  "created_at": "2024-03-20T15:04:05Z",
  "updated_at": "2024-03-20T15:04:05Z"
}