Subscriptions

A subscription is an ongoing commitment from an account to a plan.

• GET /api/v1/subscriptions — list

• POST /api/v1/subscriptions — create

• GET /api/v1/subscriptions/{id} — retrieve

• POST /api/v1/subscriptions/{id}/change-plan

• POST /api/v1/subscriptions/{id}/change-quantity

• POST /api/v1/subscriptions/{id}/cancel

• POST /api/v1/subscriptions/{id}/renew

---

GET /api/v1/subscriptions

List all subscriptions in this tenant.

• Auth scope: read

Response 200

{
  "data": [
    {
      "id": "sub_01H...",
      "tenantId": "ten_01H...",
      "productId": "prod_01H...",
      "contactId": null,
      "organizationId": "org_01H...",
      "priceCents": 4900,
      "currency": "USD",
      "billingInterval": "month",
      "status": "active",
      "currentPeriodStart": "2026-04-01T00:00:00Z",
      "currentPeriodEnd": "2026-05-01T00:00:00Z",
      "createdAt": "2026-04-01T00:00:00Z"
    }
  ],
  "nextActions": [
    { "rel": "createSubscription", "method": "POST", "href": "/api/v1/subscriptions" }
  ]
}

cURL

curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/subscriptions

---

POST /api/v1/subscriptions

Create a subscription.

• Auth scope: commerce

Body

Field	Type	Required	Description
productId	UUID	yes	Product to subscribe to
contactId	UUID	no	Subscriber contact
organizationId	UUID	no	Account
priceCents	integer	no	Override price in cents
currency	string (≤10)	no	Defaults to USD
billingInterval	string (≤50)	no	e.g. month, year
externalId	string (≤255)	no	External billing-system reference

Response 201

{
  "data": {
    "id": "sub_01H...",
    "productId": "prod_01H...",
    "status": "active",
    "priceCents": 4900,
    "currency": "USD",
    "billingInterval": "month",
    "createdAt": "2026-05-02T14:01:23Z"
  },
  "nextActions": [
    { "rel": "self", "method": "GET", "href": "/api/v1/subscriptions/sub_01H..." },
    { "rel": "changePlan", "method": "POST", "href": "/api/v1/subscriptions/sub_01H.../change-plan" },
    { "rel": "cancel", "method": "POST", "href": "/api/v1/subscriptions/sub_01H.../cancel" },
    { "rel": "renew", "method": "POST", "href": "/api/v1/subscriptions/sub_01H.../renew" }
  ]
}

cURL

curl -X POST https://api.example.com/api/v1/subscriptions \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "5f1c2d34-3b1f-4f9a-8c7c-2c3a4d5e6f70",
    "organizationId": "org_uuid_here",
    "currency": "USD",
    "billingInterval": "month"
  }'

---

GET /api/v1/subscriptions/{id}

Retrieve a subscription.

• Auth scope: read

Response 200

Same shape as the data field returned by POST.

Errors

Status	When
404	Subscription not found in this tenant

cURL

curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/subscriptions/sub_01H...

---

POST /api/v1/subscriptions/{id}/change-plan

Change a subscription's plan. The platform evaluates plan_change policies first; a blocking policy returns 403.

• Auth scope: commerce

Body

Field	Type	Description
productId	UUID	New product
priceCents	integer	New price
billingInterval	string (≤50)	New interval

All fields are optional, but you should provide at least one.

Response 200

Same shape as GET. Audit-log entry: api.subscription.changePlan.

Errors

Status	When
403	A plan_change policy blocked the operation
404	Subscription not found

cURL

curl -X POST https://api.example.com/api/v1/subscriptions/sub_01H.../change-plan \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "new_prod_uuid",
    "billingInterval": "year"
  }'

---

POST /api/v1/subscriptions/{id}/change-quantity

Change a charge's quantity (or includedUnits) on a subscription. Routes through the plan-dependency engine so dependent charges adjust automatically.

• Auth scope: commerce

Body

Field	Type	Required	Description
accountId	string	yes	Billing-system account ID
chargeId	string	yes	Billing-system charge ID
newQuantity	integer ≥ 0	yes	Target quantity
editedField	quantity | includedUnits	no	Defaults to quantity
catalogChargeId	string	no	Local catalog charge ID for resolver hints
integrationId	string	no	Pin a specific integration; defaults to active

Response 200

{
  "data": {
    "applied": [
      { "chargeId": "charge_a", "field": "quantity", "previous": 5, "next": 7 },
      { "chargeId": "charge_b", "field": "quantity", "previous": 5, "next": 7, "viaLink": "Base seats ↔ add-on seats" }
    ],
    "warnings": []
  },
  "nextActions": [ /* subscription nextActions */ ]
}

Errors

Status	When
400	Validation failed; no billing integration; adapter lacks self-service
403	Subscription does not belong to this account
404	Subscription not found

cURL

curl -X POST https://api.example.com/api/v1/subscriptions/sub_01H.../change-quantity \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "A00000123",
    "chargeId": "C-1234",
    "newQuantity": 10
  }'

---

POST /api/v1/subscriptions/{id}/cancel

Cancel a subscription. Evaluates subscription_cancel policies first.

• Auth scope: commerce

Body

None required. Cancellation timing follows the matched cancellation business rule (immediate or at_period_end).

Response 200

Same shape as GET, with status: "cancelled".

Errors

Status	When
403	A cancellation policy blocked the operation
404	Subscription not found

cURL

curl -X POST https://api.example.com/api/v1/subscriptions/sub_01H.../cancel \
  -H "Authorization: Bearer $PEAK_API_KEY"

---

POST /api/v1/subscriptions/{id}/renew

Renew a subscription for one period. For paid subscriptions, a processing payment session is recorded; the provider's webhook finalizes it.

• Auth scope: commerce

Response 200

{
  "data": {
    "id": "sub_01H...",
    "status": "active",
    "currentPeriodStart": "2026-05-02T14:01:23Z",
    "currentPeriodEnd": "2026-06-02T14:01:23Z"
  },
  "paymentSessionId": "pmt_01H...",
  "nextActions": [ /* subscription nextActions */ ]
}

paymentSessionId is null for free renewals.

Errors

Status	When
404	Subscription not found

cURL

curl -X POST https://api.example.com/api/v1/subscriptions/sub_01H.../renew \
  -H "Authorization: Bearer $PEAK_API_KEY"

---

Related

• Pricing previews — preview a plan change before committing

• Orders

• Payments