Error

A valid request URL is required to generate request examples

{
  "cancellation": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "reason": "too_expensive",
    "comment": "<string>",
    "offer_shown": "",
    "offer_taken": "",
    "at_period_end": true,
    "confirmed_at": "2023-11-07T05:31:56Z",
    "created_at": "2023-11-07T05:31:56Z"
  },
  "subscription": {}
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

Customer billing

Carry out a recorded cancellation

Cancels the subscription the record names. Owner-only.

at_period_end defaults to true here, which is the opposite of POST /v1/contact/customer/billing/cancel and deliberate: that route is an API call with nobody watching, so it refuses to choose between two different acts, while this is the last step of a flow whose previous screen said “access until the 30th” out loud. The default is that promise. Cancelling today throws away days already paid for, so a caller who wants it says so.

Confirming twice reaches the gateway once. The record carries the moment the gateway accepted, so a repeat answers it without asking again — which matters because cancelling is not universally idempotent at a gateway, and a second refusal reads to the person as their cancellation having failed.

A gateway failure leaves the record untouched and still confirmable: nothing recorded is lost to a timeout.

POST

contact

customer

billing

cancellation

{id}

confirm

Error

A valid request URL is required to generate request examples

{
  "cancellation": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "reason": "too_expensive",
    "comment": "<string>",
    "offer_shown": "",
    "offer_taken": "",
    "at_period_end": true,
    "confirmed_at": "2023-11-07T05:31:56Z",
    "created_at": "2023-11-07T05:31:56Z"
  },
  "subscription": {}
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "your role does not allow this action"
  }
}

Autorizações

Authorization

string

header

obrigatório

A contact session token, uk_ct_…. Belongs to one of the developer's own users, and reads only that user's data.

Cabeçalhos

X-Customer-Id

string<uuid>

The customer this call is acting inside — the same arrangement as X-Organization-Id, one plane down. Switching customers is navigation, not a mutation: nothing is stored, you send a different header, and the membership JOIN behind it decides what you may do there. An id you are not a member of matches no row and answers 404. Absent, the contact's oldest membership answers.

Idempotency-Key

string

Forwarded to the payment gateway as its idempotency key, so a retry of this call does not charge twice or move a subscription twice.

This is not the guarantee Idempotency-Key carries on the API-key surface: nothing is stored here and a replay is not answered with the original response. It is passed through, and what it buys is whatever the gateway does with it — for Stripe, the original result is replayed for 24 hours.

Send a fresh key per act you mean to perform, and the same key with the same body when you are retrying one. The gateway compares the parameters, so a key reused for a different act is refused there rather than replayed.

Maximum string length: 255

Parâmetros de caminho

string<uuid>

obrigatório

The cancellation record's id, from the POST that recorded the reason. It identifies; the caller's membership is what authorizes — another team's id answers 404.

Corpo

application/json

at_period_end

boolean

padrão:true

Keep access until the paid period ends. Defaults to true — the date the confirmation screen just promised.

Resposta

The record as it now stands and the subscription re-read from the gateway.

cancellation

object

One person's answer to "why are you leaving", and what happened next.

It is recorded before any gateway is asked anything, so a record exists whether or not the cancellation was ever carried out — and a record nobody carried out is the only churn signal that arrives while the customer is still a customer.

Show child attributes

subscription