Subscriptions

curl -H "x-api-key: $KEY" -H "accept: application/json" \
  "$BASE/organizations/$ORG/subscription"

{
  "meta": {},
  "links": { "self": "/organizations/<org>/subscription" },
  "data": {
    "plan_key": "starter",
    "status": "active",
    "current_period_end": "2027-09-04T00:00:00.000Z",
    "cancel_at_period_end": false,
    "included_units": 8
  }
}

data is null when the organisation has no live subscription. That is not an error.

Field	Meaning
plan_key	The plan: starter, growth or pro, or a negotiated plan key.
status	pending, incomplete, trialing, active, past_due or unpaid.
current_period_end	When the paid period ends. null while pending.
cancel_at_period_end	true when the subscription stops at current_period_end.
included_units	Supplier locations the plan credits per year. null for a negotiated plan.

curl -X DELETE -H "x-api-key: $KEY" -H "accept: application/json" \
  "$BASE/organizations/$ORG/subscription"

The response has the same shape as GET, with cancel_at_period_end: true.

• Stripe does not bill the renewal.
• The subscription stays active until current_period_end.
• The organisation keeps its plan allowance until current_period_end.
• The call never cancels immediately.

Show the payer "Active until current_period_end" when cancel_at_period_end is true.

A cancelled subscription keeps its slot until current_period_end, so the organisation cannot buy a different plan before then. A checkout with a plan returns 409 CHECKOUT_SUBSCRIPTION_EXISTS. To change plan now, undo the cancellation and contact support: plan switching is not available yet.

curl -X POST -H "x-api-key: $KEY" -H "accept: application/json" \
  "$BASE/organizations/$ORG/subscription/resume"

The response has cancel_at_period_end: false. The subscription then renews as normal.

Undo also clears an end date that staff set in the Stripe dashboard.

Undo the cancellation before current_period_end. After that date the subscription is canceled, and this call returns 404. Buy a new plan instead.

Cancel and undo do not change:

• the credit balance,
• the credit ledger,
• the plan allowance.

Undo does not add credits. Cancel does not remove credits.

Stripe ends the subscription at current_period_end. After that:

• GET /organizations/:id/subscription returns data: null.
• The plan allowance stops.
• Credits in the balance stay.

Both calls are safe to repeat. A second cancel, or an undo on a subscription that already renews, returns 200 with the current state.

Both responses show the new state at once. You do not need a second GET.

These apply to DELETE /organizations/:id/subscription and POST /organizations/:id/subscription/resume.

Status	Code	Meaning
400	BAD_REQUEST	The id is not a UUID.
401		The API key is missing or not valid.
403		The key does not hold billing:write.
404	NOT_FOUND	The organisation is not in this key's scope.
404	SUBSCRIPTION_NOT_FOUND	The organisation has no live subscription.
409	SUBSCRIPTION_NOT_CANCELLABLE	The subscription is pending or incomplete, it has no Stripe subscription yet, or it is a negotiated plan. Or Stripe applied the change, but reports a status this endpoint does not show, for example paused. details.status names the status.
502	CHECKOUT_GATEWAY_REJECTED	Stripe refused the request. Do not retry.
503	CHECKOUT_UPSTREAM_ERROR	fm-api could not reach Stripe, or Stripe rate-limited the call. Retry. Nothing changed.
503	CHECKOUT_NOT_CONFIGURED	This deployment has no Stripe gateway.

A pending subscription has a checkout in progress. An incomplete subscription has a first payment that did not succeed, and Stripe expires it after 23 hours.

Call	Scope
GET /organizations/:id/subscription	billing:read
DELETE /organizations/:id/subscription	billing:write
POST /organizations/:id/subscription/resume	billing:write

A parent organisation's key can act on its child organisations.