Create subscription

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

POST /subscriptions

Create subscription

cURL

curl --request POST \
  --url https://us.api.flexprice.io/v1/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "currency": "<string>",
  "plan_id": "<string>",
  "addons": [
    {
      "addon_id": "<string>",
      "line_item_commitments": {},
      "metadata": {},
      "start_date": "2023-11-07T05:31:56Z"
    }
  ],
  "auto_invoice_threshold": "<string>",
  "billing_anchor": "2023-11-07T05:31:56Z",
  "billing_period_count": 123,
  "commitment_amount": "<string>",
  "coupons": [
    "<string>"
  ],
  "credit_grants": [
    {
      "credits": "<string>",
      "name": "<string>",
      "conversion_rate": "<string>",
      "end_date": "2023-11-07T05:31:56Z",
      "expiration_duration": 123,
      "metadata": {},
      "period_count": 123,
      "plan_id": "<string>",
      "priority": 123,
      "start_date": "2023-11-07T05:31:56Z",
      "subscription_id": "<string>",
      "topup_conversion_rate": "<string>"
    }
  ],
  "customer_id": "<string>",
  "customer_timezone": "<string>",
  "enable_true_up": true,
  "end_date": "2023-11-07T05:31:56Z",
  "external_customer_id": "<string>",
  "gateway_payment_method_id": "<string>",
  "inheritance": {
    "external_customer_ids_to_inherit_subscription": [
      "<string>"
    ],
    "invoicing_customer_external_id": "<string>",
    "parent_subscription_id": "<string>",
    "subscriptions_ids_for_grouped_invoicing": [
      "<string>"
    ]
  },
  "line_item_commitments": {},
  "line_item_coupons": {},
  "line_items": [
    {
      "commitment_amount": 123,
      "commitment_overage_factor": 123,
      "commitment_quantity": 123,
      "commitment_true_up_enabled": true,
      "commitment_windowed": true,
      "display_name": "<string>",
      "end_date": "2023-11-07T05:31:56Z",
      "metadata": {},
      "price_id": "<string>",
      "quantity": 123,
      "start_date": "2023-11-07T05:31:56Z",
      "subscription_phase_id": "<string>"
    }
  ],
  "lookup_key": "<string>",
  "metadata": {},
  "overage_factor": "<string>",
  "override_entitlements": [
    {
      "entitlement_id": "<string>",
      "is_enabled": true,
      "static_value": "<string>",
      "usage_limit": 123
    }
  ],
  "override_line_items": [
    {
      "price_id": "<string>",
      "amount": "<string>",
      "price_unit_amount": "<string>",
      "price_unit_tiers": [
        {
          "unit_amount": "<string>",
          "flat_amount": "<string>",
          "up_to": 123
        }
      ],
      "quantity": "<string>",
      "tiers": [
        {
          "unit_amount": "<string>",
          "flat_amount": "<string>",
          "up_to": 123
        }
      ],
      "transform_quantity": {
        "divide_by": 123
      }
    }
  ],
  "phases": [
    {
      "start_date": "2023-11-07T05:31:56Z",
      "coupons": [
        "<string>"
      ],
      "end_date": "2023-11-07T05:31:56Z",
      "line_item_coupons": {},
      "line_items": [
        {
          "commitment_amount": 123,
          "commitment_overage_factor": 123,
          "commitment_quantity": 123,
          "commitment_true_up_enabled": true,
          "commitment_windowed": true,
          "display_name": "<string>",
          "end_date": "2023-11-07T05:31:56Z",
          "metadata": {},
          "price_id": "<string>",
          "quantity": 123,
          "start_date": "2023-11-07T05:31:56Z",
          "subscription_phase_id": "<string>"
        }
      ],
      "metadata": {},
      "override_line_items": [
        {
          "price_id": "<string>",
          "amount": "<string>",
          "price_unit_amount": "<string>",
          "price_unit_tiers": [
            {
              "unit_amount": "<string>",
              "flat_amount": "<string>",
              "up_to": 123
            }
          ],
          "quantity": "<string>",
          "tiers": [
            {
              "unit_amount": "<string>",
              "flat_amount": "<string>",
              "up_to": 123
            }
          ],
          "transform_quantity": {
            "divide_by": 123
          }
        }
      ]
    }
  ],
  "start_date": "2023-11-07T05:31:56Z",
  "tax_rate_overrides": [
    {
      "currency": "<string>",
      "tax_rate_code": "<string>",
      "auto_apply": true,
      "metadata": {},
      "priority": 123
    }
  ],
  "trial_period_days": 123
}
'

201

{
  "active_pause_id": "<string>",
  "auto_invoice_threshold": "<string>",
  "billing_anchor": "2023-11-07T05:31:56Z",
  "billing_period_count": 123,
  "cancel_at": "2023-11-07T05:31:56Z",
  "cancel_at_period_end": true,
  "cancelled_at": "2023-11-07T05:31:56Z",
  "collection_method": "<string>",
  "commitment_amount": "<string>",
  "coupon_associations": [
    {
      "coupon": {
        "amount_off": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "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": {},
        "tenant_id": "<string>",
        "total_redemptions": 123,
        "updated_at": "2023-11-07T05:31:56Z",
        "updated_by": "<string>"
      },
      "coupon_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "created_by": "<string>",
      "end_date": "2023-11-07T05:31:56Z",
      "environment_id": "<string>",
      "id": "<string>",
      "metadata": {},
      "start_date": "2023-11-07T05:31:56Z",
      "subscription_id": "<string>",
      "subscription_line_item_id": "<string>",
      "subscription_phase_id": "<string>",
      "tenant_id": "<string>",
      "updated_at": "2023-11-07T05:31:56Z",
      "updated_by": "<string>"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "created_by": "<string>",
  "credit_grants": [
    {
      "conversion_rate": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "created_by": "<string>",
      "credit_grant_anchor": "2023-11-07T05:31:56Z",
      "credits": "<string>",
      "end_date": "2023-11-07T05:31:56Z",
      "environment_id": "<string>",
      "expiration_duration": 123,
      "id": "<string>",
      "metadata": {},
      "name": "<string>",
      "period_count": 123,
      "plan_id": "<string>",
      "priority": 123,
      "start_date": "2023-11-07T05:31:56Z",
      "subscription_id": "<string>",
      "tenant_id": "<string>",
      "topup_conversion_rate": "<string>",
      "updated_at": "2023-11-07T05:31:56Z",
      "updated_by": "<string>"
    }
  ],
  "currency": "<string>",
  "current_period_end": "2023-11-07T05:31:56Z",
  "current_period_start": "2023-11-07T05:31:56Z",
  "customer": {
    "address_city": "<string>",
    "address_country": "<string>",
    "address_line1": "<string>",
    "address_line2": "<string>",
    "address_postal_code": "<string>",
    "address_state": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "created_by": "<string>",
    "email": "<string>",
    "environment_id": "<string>",
    "external_id": "<string>",
    "id": "<string>",
    "integrations": [
      {
        "created_at": "2023-11-07T05:31:56Z",
        "created_by": "<string>",
        "entity_id": "<string>",
        "environment_id": "<string>",
        "id": "<string>",
        "provider_entity_id": "<string>",
        "provider_type": "<string>",
        "tenant_id": "<string>",
        "updated_at": "2023-11-07T05:31:56Z",
        "updated_by": "<string>"
      }
    ],
    "metadata": {},
    "name": "<string>",
    "tenant_id": "<string>",
    "updated_at": "2023-11-07T05:31:56Z",
    "updated_by": "<string>"
  },
  "customer_id": "<string>",
  "customer_timezone": "<string>",
  "enable_true_up": true,
  "end_date": "2023-11-07T05:31:56Z",
  "environment_id": "<string>",
  "gateway_payment_method_id": "<string>",
  "id": "<string>",
  "invoicing_customer_id": "<string>",
  "latest_invoice": {
    "adjustment_amount": "<string>",
    "amount_due": "<string>",
    "amount_paid": "<string>",
    "amount_remaining": "<string>",
    "billing_period": "<string>",
    "billing_reason": "<string>",
    "billing_sequence": 123,
    "coupon_applications": [
      {
        "applied_at": "2023-11-07T05:31:56Z",
        "coupon_association_id": "<string>",
        "coupon_id": "<string>",
        "coupon_snapshot": {},
        "created_at": "2023-11-07T05:31:56Z",
        "created_by": "<string>",
        "currency": "<string>",
        "discount_percentage": "<string>",
        "discounted_amount": "<string>",
        "environment_id": "<string>",
        "final_price": "<string>",
        "id": "<string>",
        "invoice_id": "<string>",
        "invoice_line_item_id": "<string>",
        "metadata": {},
        "original_price": "<string>",
        "subscription_id": "<string>",
        "tenant_id": "<string>",
        "updated_at": "2023-11-07T05:31:56Z",
        "updated_by": "<string>"
      }
    ],
    "created_at": "2023-11-07T05:31:56Z",
    "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": "2023-11-07T05:31:56Z",
      "created_by": "<string>",
      "email": "<string>",
      "environment_id": "<string>",
      "external_id": "<string>",
      "id": "<string>",
      "integrations": [
        {
          "created_at": "2023-11-07T05:31:56Z",
          "created_by": "<string>",
          "entity_id": "<string>",
          "environment_id": "<string>",
          "id": "<string>",
          "provider_entity_id": "<string>",
          "provider_type": "<string>",
          "tenant_id": "<string>",
          "updated_at": "2023-11-07T05:31:56Z",
          "updated_by": "<string>"
        }
      ],
      "metadata": {},
      "name": "<string>",
      "tenant_id": "<string>",
      "updated_at": "2023-11-07T05:31:56Z",
      "updated_by": "<string>"
    },
    "customer_id": "<string>",
    "description": "<string>",
    "due_date": "2023-11-07T05:31:56Z",
    "environment_id": "<string>",
    "finalized_at": "2023-11-07T05:31:56Z",
    "id": "<string>",
    "idempotency_key": "<string>",
    "invoice_number": "<string>",
    "invoice_pdf_url": "<string>",
    "last_computed_at": "2023-11-07T05:31:56Z",
    "line_items": [
      {
        "amount": "<string>",
        "commitment_info": {
          "amount": "<string>",
          "computed_commitment_utilized_amount": "<string>",
          "computed_overage_amount": "<string>",
          "computed_true_up_amount": "<string>",
          "is_windowed": true,
          "overage_factor": "<string>",
          "quantity": "<string>",
          "true_up_enabled": true
        },
        "created_at": "2023-11-07T05:31:56Z",
        "created_by": "<string>",
        "currency": "<string>",
        "customer_id": "<string>",
        "display_name": "<string>",
        "entity_id": "<string>",
        "entity_type": "<string>",
        "environment_id": "<string>",
        "id": "<string>",
        "invoice_id": "<string>",
        "invoice_level_discount": "<string>",
        "line_item_discount": "<string>",
        "metadata": {},
        "meter_display_name": "<string>",
        "meter_id": "<string>",
        "period_end": "2023-11-07T05:31:56Z",
        "period_start": "2023-11-07T05:31:56Z",
        "plan_display_name": "<string>",
        "prepaid_credits_applied": "<string>",
        "price_id": "<string>",
        "price_type": "<string>",
        "price_unit": "<string>",
        "price_unit_amount": "<string>",
        "price_unit_id": "<string>",
        "quantity": "<string>",
        "subscription_id": "<string>",
        "tenant_id": "<string>",
        "updated_at": "2023-11-07T05:31:56Z",
        "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": "<string>",
    "paid_at": "2023-11-07T05:31:56Z",
    "period_end": "2023-11-07T05:31:56Z",
    "period_start": "2023-11-07T05:31:56Z",
    "recalculated_invoice_id": "<string>",
    "refunded_amount": "<string>",
    "subscription": "<unknown>",
    "subscription_customer_id": "<string>",
    "subscription_id": "<string>",
    "subtotal": "<string>",
    "taxes": [
      {
        "applied_at": "2023-11-07T05:31:56Z",
        "created_at": "2023-11-07T05:31:56Z",
        "created_by": "<string>",
        "currency": "<string>",
        "entity_id": "<string>",
        "environment_id": "<string>",
        "id": "<string>",
        "idempotency_key": "<string>",
        "metadata": {},
        "tax_amount": "<string>",
        "tax_association_id": "<string>",
        "tax_rate": {
          "code": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "created_by": "<string>",
          "description": "<string>",
          "environment_id": "<string>",
          "fixed_value": "<string>",
          "id": "<string>",
          "metadata": {},
          "name": "<string>",
          "percentage_value": "<string>",
          "tenant_id": "<string>",
          "updated_at": "2023-11-07T05:31:56Z",
          "updated_by": "<string>"
        },
        "tax_rate_id": "<string>",
        "taxable_amount": "<string>",
        "tenant_id": "<string>",
        "updated_at": "2023-11-07T05:31:56Z",
        "updated_by": "<string>"
      }
    ],
    "tenant_id": "<string>",
    "total": "<string>",
    "total_discount": "<string>",
    "total_prepaid_credits_applied": "<string>",
    "total_tax": "<string>",
    "updated_at": "2023-11-07T05:31:56Z",
    "updated_by": "<string>",
    "version": 123,
    "voided_at": "2023-11-07T05:31:56Z"
  },
  "line_items": [
    {
      "addon_association_id": "<string>",
      "billing_period_count": 123,
      "commitment_amount": "<string>",
      "commitment_overage_factor": "<string>",
      "commitment_quantity": "<string>",
      "commitment_true_up_enabled": true,
      "commitment_windowed": true,
      "created_at": "2023-11-07T05:31:56Z",
      "created_by": "<string>",
      "currency": "<string>",
      "customer_id": "<string>",
      "display_name": "<string>",
      "end_date": "2023-11-07T05:31:56Z",
      "entity_id": "<string>",
      "environment_id": "<string>",
      "id": "<string>",
      "metadata": {},
      "meter_display_name": "<string>",
      "meter_id": "<string>",
      "plan_display_name": "<string>",
      "price": {
        "amount": "<string>",
        "billing_period_count": 123,
        "conversion_rate": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "created_by": "<string>",
        "currency": "<string>",
        "description": "<string>",
        "display_amount": "<string>",
        "display_name": "<string>",
        "display_price_unit_amount": "<string>",
        "end_date": "2023-11-07T05:31:56Z",
        "entity_id": "<string>",
        "environment_id": "<string>",
        "group_id": "<string>",
        "id": "<string>",
        "lookup_key": "<string>",
        "metadata": {},
        "meter_id": "<string>",
        "min_quantity": "<string>",
        "parent_price_id": "<string>",
        "price_unit": "<string>",
        "price_unit_amount": "<string>",
        "price_unit_id": "<string>",
        "price_unit_tiers": [
          {
            "flat_amount": "<string>",
            "unit_amount": "<string>",
            "up_to": 123
          }
        ],
        "start_date": "2023-11-07T05:31:56Z",
        "tenant_id": "<string>",
        "tiers": [
          {
            "flat_amount": "<string>",
            "unit_amount": "<string>",
            "up_to": 123
          }
        ],
        "transform_quantity": {
          "divide_by": 123
        },
        "trial_period_days": 123,
        "updated_at": "2023-11-07T05:31:56Z",
        "updated_by": "<string>"
      },
      "price_id": "<string>",
      "price_unit": "<string>",
      "price_unit_id": "<string>",
      "quantity": "<string>",
      "start_date": "2023-11-07T05:31:56Z",
      "subscription_id": "<string>",
      "subscription_phase_id": "<string>",
      "tenant_id": "<string>",
      "updated_at": "2023-11-07T05:31:56Z",
      "updated_by": "<string>"
    }
  ],
  "lookup_key": "<string>",
  "metadata": {},
  "overage_factor": "<string>",
  "parent_subscription_id": "<string>",
  "pauses": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "created_by": "<string>",
      "environment_id": "<string>",
      "id": "<string>",
      "metadata": {},
      "original_period_end": "2023-11-07T05:31:56Z",
      "original_period_start": "2023-11-07T05:31:56Z",
      "pause_end": "2023-11-07T05:31:56Z",
      "pause_start": "2023-11-07T05:31:56Z",
      "reason": "<string>",
      "resumed_at": "2023-11-07T05:31:56Z",
      "subscription_id": "<string>",
      "tenant_id": "<string>",
      "updated_at": "2023-11-07T05:31:56Z",
      "updated_by": "<string>"
    }
  ],
  "payment_behavior": "<string>",
  "phases": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "created_by": "<string>",
      "end_date": "2023-11-07T05:31:56Z",
      "environment_id": "<string>",
      "id": "<string>",
      "metadata": {},
      "start_date": "2023-11-07T05:31:56Z",
      "subscription_id": "<string>",
      "tenant_id": "<string>",
      "updated_at": "2023-11-07T05:31:56Z",
      "updated_by": "<string>"
    }
  ],
  "plan": {
    "created_at": "2023-11-07T05:31:56Z",
    "created_by": "<string>",
    "credit_grants": [
      {
        "conversion_rate": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "created_by": "<string>",
        "credit_grant_anchor": "2023-11-07T05:31:56Z",
        "credits": "<string>",
        "end_date": "2023-11-07T05:31:56Z",
        "environment_id": "<string>",
        "expiration_duration": 123,
        "id": "<string>",
        "metadata": {},
        "name": "<string>",
        "period_count": 123,
        "plan_id": "<string>",
        "priority": 123,
        "start_date": "2023-11-07T05:31:56Z",
        "subscription_id": "<string>",
        "tenant_id": "<string>",
        "topup_conversion_rate": "<string>",
        "updated_at": "2023-11-07T05:31:56Z",
        "updated_by": "<string>"
      }
    ],
    "description": "<string>",
    "display_order": 123,
    "entitlements": [
      {
        "addon": {
          "created_at": "2023-11-07T05:31:56Z",
          "created_by": "<string>",
          "description": "<string>",
          "entitlements": "<array>",
          "environment_id": "<string>",
          "id": "<string>",
          "lookup_key": "<string>",
          "metadata": {},
          "name": "<string>",
          "prices": [
            {
              "addon": "<unknown>",
              "amount": "<string>",
              "billing_period_count": 123,
              "conversion_rate": "<string>",
              "created_at": "2023-11-07T05:31:56Z",
              "created_by": "<string>",
              "currency": "<string>",
              "description": "<string>",
              "display_amount": "<string>",
              "display_name": "<string>",
              "display_price_unit_amount": "<string>",
              "end_date": "2023-11-07T05:31:56Z",
              "entity_id": "<string>",
              "environment_id": "<string>",
              "group": {
                "created_at": "2023-11-07T05:31:56Z",
                "entity_ids": [
                  "<string>"
                ],
                "entity_type": "<string>",
                "id": "<string>",
                "lookup_key": "<string>",
                "metadata": {},
                "name": "<string>",
                "status": "<string>",
                "updated_at": "2023-11-07T05:31:56Z"
              },
              "group_id": "<string>",
              "id": "<string>",
              "lookup_key": "<string>",
              "metadata": {},
              "meter": {
                "aggregation": {
                  "expression": "<string>",
                  "field": "<string>",
                  "group_by": "<string>",
                  "multiplier": "<string>"
                },
                "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",
                "status": "published",
                "tenant_id": "tenant123",
                "updated_at": "2024-03-20T15:04:05Z"
              },
              "meter_id": "<string>",
              "min_quantity": "<string>",
              "parent_price_id": "<string>",
              "plan": "<unknown>",
              "price_unit": "<string>",
              "price_unit_amount": "<string>",
              "price_unit_id": "<string>",
              "price_unit_tiers": [
                {
                  "flat_amount": "<string>",
                  "unit_amount": "<string>",
                  "up_to": 123
                }
              ],
              "pricing_unit": {
                "base_currency": "<string>",
                "code": "<string>",
                "conversion_rate": "<string>",
                "created_at": "2023-11-07T05:31:56Z",
                "created_by": "<string>",
                "environment_id": "<string>",
                "id": "<string>",
                "metadata": {},
                "name": "<string>",
                "symbol": "<string>",
                "tenant_id": "<string>",
                "updated_at": "2023-11-07T05:31:56Z",
                "updated_by": "<string>"
              },
              "start_date": "2023-11-07T05:31:56Z",
              "tenant_id": "<string>",
              "tiers": [
                {
                  "flat_amount": "<string>",
                  "unit_amount": "<string>",
                  "up_to": 123
                }
              ],
              "transform_quantity": {
                "divide_by": 123
              },
              "trial_period_days": 123,
              "updated_at": "2023-11-07T05:31:56Z",
              "updated_by": "<string>"
            }
          ],
          "tenant_id": "<string>",
          "updated_at": "2023-11-07T05:31:56Z",
          "updated_by": "<string>"
        },
        "created_at": "2023-11-07T05:31:56Z",
        "created_by": "<string>",
        "display_order": 123,
        "end_date": "2023-11-07T05:31:56Z",
        "entity_id": "<string>",
        "environment_id": "<string>",
        "feature": {
          "alert_settings": {
            "alert_enabled": true,
            "critical": {
              "threshold": 123
            },
            "info": {
              "threshold": 123
            },
            "warning": {
              "threshold": 123
            }
          },
          "created_at": "2023-11-07T05:31:56Z",
          "created_by": "<string>",
          "description": "<string>",
          "environment_id": "<string>",
          "group": {
            "created_at": "2023-11-07T05:31:56Z",
            "entity_ids": [
              "<string>"
            ],
            "entity_type": "<string>",
            "id": "<string>",
            "lookup_key": "<string>",
            "metadata": {},
            "name": "<string>",
            "status": "<string>",
            "updated_at": "2023-11-07T05:31:56Z"
          },
          "group_id": "<string>",
          "id": "<string>",
          "lookup_key": "<string>",
          "metadata": {},
          "meter": {
            "aggregation": {
              "expression": "<string>",
              "field": "<string>",
              "group_by": "<string>",
              "multiplier": "<string>"
            },
            "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",
            "status": "published",
            "tenant_id": "tenant123",
            "updated_at": "2024-03-20T15:04:05Z"
          },
          "meter_id": "<string>",
          "name": "<string>",
          "reporting_unit": {
            "conversion_rate": 123,
            "unit_plural": "<string>",
            "unit_singular": "<string>"
          },
          "tenant_id": "<string>",
          "unit_plural": "<string>",
          "unit_singular": "<string>",
          "updated_at": "2023-11-07T05:31:56Z",
          "updated_by": "<string>"
        },
        "feature_id": "<string>",
        "id": "<string>",
        "is_enabled": true,
        "is_soft_limit": true,
        "parent_entitlement_id": "<string>",
        "plan": "<unknown>",
        "plan_id": "<string>",
        "start_date": "2023-11-07T05:31:56Z",
        "static_value": "<string>",
        "tenant_id": "<string>",
        "updated_at": "2023-11-07T05:31:56Z",
        "updated_by": "<string>",
        "usage_limit": 123
      }
    ],
    "environment_id": "<string>",
    "id": "<string>",
    "lookup_key": "<string>",
    "metadata": {},
    "name": "<string>",
    "prices": [
      {
        "addon": "<unknown>",
        "amount": "<string>",
        "billing_period_count": 123,
        "conversion_rate": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "created_by": "<string>",
        "currency": "<string>",
        "description": "<string>",
        "display_amount": "<string>",
        "display_name": "<string>",
        "display_price_unit_amount": "<string>",
        "end_date": "2023-11-07T05:31:56Z",
        "entity_id": "<string>",
        "environment_id": "<string>",
        "group": {
          "created_at": "2023-11-07T05:31:56Z",
          "entity_ids": [
            "<string>"
          ],
          "entity_type": "<string>",
          "id": "<string>",
          "lookup_key": "<string>",
          "metadata": {},
          "name": "<string>",
          "status": "<string>",
          "updated_at": "2023-11-07T05:31:56Z"
        },
        "group_id": "<string>",
        "id": "<string>",
        "lookup_key": "<string>",
        "metadata": {},
        "meter": {
          "aggregation": {
            "expression": "<string>",
            "field": "<string>",
            "group_by": "<string>",
            "multiplier": "<string>"
          },
          "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",
          "status": "published",
          "tenant_id": "tenant123",
          "updated_at": "2024-03-20T15:04:05Z"
        },
        "meter_id": "<string>",
        "min_quantity": "<string>",
        "parent_price_id": "<string>",
        "plan": "<unknown>",
        "price_unit": "<string>",
        "price_unit_amount": "<string>",
        "price_unit_id": "<string>",
        "price_unit_tiers": [
          {
            "flat_amount": "<string>",
            "unit_amount": "<string>",
            "up_to": 123
          }
        ],
        "pricing_unit": {
          "base_currency": "<string>",
          "code": "<string>",
          "conversion_rate": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "created_by": "<string>",
          "environment_id": "<string>",
          "id": "<string>",
          "metadata": {},
          "name": "<string>",
          "symbol": "<string>",
          "tenant_id": "<string>",
          "updated_at": "2023-11-07T05:31:56Z",
          "updated_by": "<string>"
        },
        "start_date": "2023-11-07T05:31:56Z",
        "tenant_id": "<string>",
        "tiers": [
          {
            "flat_amount": "<string>",
            "unit_amount": "<string>",
            "up_to": 123
          }
        ],
        "transform_quantity": {
          "divide_by": 123
        },
        "trial_period_days": 123,
        "updated_at": "2023-11-07T05:31:56Z",
        "updated_by": "<string>"
      }
    ],
    "tenant_id": "<string>",
    "updated_at": "2023-11-07T05:31:56Z",
    "updated_by": "<string>"
  },
  "plan_id": "<string>",
  "start_date": "2023-11-07T05:31:56Z",
  "tenant_id": "<string>",
  "trial_end": "2023-11-07T05:31:56Z",
  "trial_start": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "updated_by": "<string>",
  "version": 123
}

Authorizations

x-api-key · string · header · required

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

Body

application/json

Subscription Request

billing_period · enum<string> · required

Available options: MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY, ONETIME

currency · string · required

plan_id · string · required

addons · object[]

Addons represents addons to be added to the subscription during creation

Show child attributes

auto_invoice_threshold · string

AutoInvoiceThreshold is the usage amount (in subscription currency) that triggers an intermediate invoice mid-period. Set once at creation; cannot be changed later. Allowed only when the subscription resolves to type standalone (no parent hierarchy rows). Plan line items must be usage-based only (no fixed or other non-usage plan prices). Nil means auto invoice threshold billing is disabled for this subscription.

billing_anchor · string<date-time>

BillingAnchor overrides the derived billing anchor when billing_cycle is anniversary. For monthly billing, the day-of-month (and time-of-day) define cycle boundaries: if start_date is before that day in the month, the first billing period ends on the next occurrence of that day in the same month (a shorter first period); subsequent periods follow the usual interval.

billing_cycle · enum<string>

Available options: anniversary, calendar

billing_period_count · integer

collection_method · enum<string>

Available options: charge_automatically, send_invoice

commitment_amount · string

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

commitment_duration · enum<string>

Available options: MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY, ONETIME

coupons · string[]

credit_grants · object[]

Credit grants to be applied when subscription is created

Show child attributes

customer_id · string

customer_id is the flexprice customer id and it is prioritized over external_customer_id in case both are provided.

customer_timezone · string

Timezone of the customer. If not set, the default value is UTC.

enable_true_up · boolean

Enable Commitment True Up Fee

end_date · string<date-time>

external_customer_id · string

external_customer_id is the customer id in your DB and must be same as what you provided as external_id while creating the customer in flexprice.

gateway_payment_method_id · string

inheritance · object

Show child attributes

line_item_commitments · object

LineItemCommitments allows setting commitment configuration per line item (keyed by price_id)

Show child attributes

line_item_coupons · object

Show child attributes

line_items · object[]

LineItems are extra line items to add at creation (each with price_id or price), in addition to plan prices

Show child attributes

lookup_key · string

metadata · object

Show child attributes

overage_factor · string

OverageFactor is a multiplier applied to usage beyond the commitment amount

override_entitlements · object[]

OverrideEntitlements allows customizing specific entitlements for this subscription

Show child attributes

override_line_items · object[]

OverrideLineItems allows customizing specific prices for this subscription

Show child attributes

payment_behavior · enum<string>

Available options: allow_incomplete, default_incomplete, error_if_incomplete, default_active

payment_terms · enum<string>

Available options: 15 NET, 30 NET, 45 NET, 60 NET, 75 NET, 90 NET

phases · object[]

Phases represents subscription phases to be created with the subscription

Show child attributes

proration_behavior · enum<string>

Available options: create_prorations, none

start_date · string<date-time>

subscription_status · enum<string>

Available options: active, paused, cancelled, incomplete, trialing, draft

tax_rate_overrides · object[]

tax_rate_overrides is the tax rate overrides to be applied to the subscription

Show child attributes

trial_period_days · integer

TrialPeriodDays: nil = inherit trial length from plan recurring-fixed prices (must be uniform). 0 = explicitly no trial (overrides catalog). >0 = override duration in days.

Response

201

application/json

Created

active_pause_id · string

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

auto_invoice_threshold · string

AutoInvoiceThreshold is the usage amount (in subscription currency) that triggers an intermediate invoice. Overrides the plan-level threshold when set. Nil means: inherit from the plan's threshold (which may also be nil = disabled).

billing_anchor · string<date-time>

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

billing_cycle · enum<string>

Available options: anniversary, calendar

billing_period · enum<string>

Available options: MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY, ONETIME

billing_period_count · integer

BillingPeriodCount is the total number units of the billing period.

cancel_at · string<date-time>

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<date-time>

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

commitment_duration · enum<string>

Available options: MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY, ONETIME

coupon_associations · object[]

CouponAssociations are the coupon associations for this subscription

Show child attributes

created_at · string<date-time>

created_by · string

credit_grants · object[]

Credit grants are the credit grants for this subscription

Show child attributes

currency · string

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

current_period_end · string<date-time>

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<date-time>

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

Show child attributes

customer_id · string

CustomerID is the identifier for the customer in our system

customer_timezone · string

enable_true_up · boolean

end_date · string<date-time>

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)

latest_invoice · object

Show child attributes

line_items · object[]

Show child attributes

lookup_key · string

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

metadata · object

Show child attributes

overage_factor · string

OverageFactor is a multiplier applied to usage beyond the commitment amount

parent_subscription_id · string

ParentSubscriptionID is the parent subscription ID for hierarchy (e.g. child subscription under a parent)

pause_status · enum<string>

Available options: none, active, scheduled, completed, cancelled

pauses · object[]

Show child attributes

payment_behavior · string

PaymentBehavior determines how subscription payments are handled

payment_terms · enum<string>

Available options: 15 NET, 30 NET, 45 NET, 60 NET, 75 NET, 90 NET

phases · object[]

Phases are the subscription phases for this subscription

Show child attributes

plan · object

Show child attributes

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<date-time>

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

subscription_type · enum<string>

Available options: standalone, delegated_invoicing, parent, inherited, grouped_invoicing

tenant_id · string

trial_end · string<date-time>

TrialEnd is the end date of the trial period

trial_start · string<date-time>

TrialStart is the start date of the trial period

updated_at · string<date-time>

updated_by · string

version · integer

Version is used for optimistic locking