Update Subscription

Update subscription details. Use when changing subscription status, cancellation date, or parent relationship. Supports partial updates.

PUT /v1/subscriptions/{id}

Update Subscription

cURL

curl --request PUT \
  --url https://api.example.com/v1/subscriptions/{id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "<string>",
  "cancel_at": "<string>",
  "cancel_at_period_end": true,
  "parent_subscription_id": "<string>"
}
'

200

{
  "id": "<string>",
  "customer_id": "<string>",
  "plan_id": "<string>",
  "subscription_status": "<string>",
  "cancel_at": "<string>",
  "cancel_at_period_end": true,
  "parent_subscription_id": "<string>",
  "currency": "<string>",
  "billing_cadence": "<string>",
  "billing_period": "<string>",
  "start_date": "<string>",
  "current_period_start": "<string>",
  "current_period_end": "<string>",
  "metadata": {},
  "created_at": "<string>",
  "updated_at": "<string>"
}

Path Parameters

id · string · required

Unique identifier of the subscription to update.

Example: "sub_x1y2z3a4b5c6d7e8f9g0"

Request Body

status · string

Updated subscription status.

Options: "ACTIVE", "CANCELLED", "INCOMPLETE", "EXPIRED", "PAUSED", "DRAFT"

cancel_at · string

ISO 8601 timestamp for when the subscription should be cancelled.

Example: "2024-12-31T23:59:59Z"

cancel_at_period_end · boolean

Whether the subscription should cancel at the end of the current period.

Example: true

parent_subscription_id · string

Parent subscription ID for hierarchy. Set to empty string "" to remove parent relationship. Omit to leave unchanged.

Example: "sub_parent123"

Response

id · string

Unique identifier for the subscription.

customer_id · string

FlexPrice customer ID.

plan_id · string

Plan ID.

subscription_status · string

Updated subscription status.

cancel_at · string

Updated cancellation date (if set).

cancel_at_period_end · boolean

Updated cancel at period end flag.

parent_subscription_id · string

Updated parent subscription ID (if set).

currency · string

Currency code.

billing_cadence · string

Billing frequency.

billing_period · string

Billing period unit.

start_date · string

ISO 8601 timestamp when subscription starts.

current_period_start · string

ISO 8601 timestamp of current billing period start.

current_period_end · string

ISO 8601 timestamp of current billing period end.

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.

Example Request

cURL

curl --request PUT \
  --url https://api.flexprice.io/v1/subscriptions/sub_x1y2z3a4b5c6d7e8f9g0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "cancel_at_period_end": true
  }'

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