---
title: "Create a self-serve upgrade checkout"
method: POST
path: "/v1/billing/upgrade/checkout"
tags: ["Billing"]
---

# Create a self-serve upgrade checkout

`POST /v1/billing/upgrade/checkout`

## Request

- Base URL: `https://api.prod.keyban.io`
- URL: `https://api.prod.keyban.io/v1/billing/upgrade/checkout`
- Auth: `bearer` (a scheme the document does not define)

Creates a Chargebee hosted page that changes the organization's existing subscription to a paid plan of the same vertical. Refuses any target that is not a strict upgrade — a downgrade, a cross-vertical plan, or Enterprise. An organization that signed up to the free Agent Wallet trial must also send its billing identity in `customer`: it is written to Chargebee, then the trial ends on the hosted page (or a new subscription is opened if the trial subscription is already cancelled).

## Request body

- UpgradeCheckoutRequestDto
  - `itemPriceId` string, required: Chargebee item-price ID of the target plan. Must be a strict upgrade of the organization's current plan, within the same vertical (Dpp / AgentWallet / Trust).
  - `customer` object: Billing identity of the organization. Required for the first paid plan of an organization that signed up to the free Agent Wallet trial (422 BILLING_UPGRADE_IDENTITY_REQUIRED when missing); ignored otherwise.
    - `type` 'company', required: Billing identity of the organization owner. Only `company` is accepted today; it drives the required identifiers (SIREN/VAT) and the Chargebee `cf_customer_type` custom field.
    - `legalName` string: Registered legal name of the company. Required when `type` is `company`, ignored for an `individual`.
    - `siren` string: 9-digit French company identifier. Required for a French company, refused for an individual.
    - `vatNumber` string: EU VAT number. Required for a non-French company; when the billing country is France it must match the FRxx999999999 format.
    - `firstName` string, required: Given name of the person completing onboarding.
    - `lastName` string, required: Family name of the person completing onboarding.
    - `phone` string, required: Contact phone number in E.164 notation.
    - `billingEmail` string, email: Invoice delivery address, when different from the account e-mail used to sign in.
    - `address` object, required
      - `line1` string, required: First line of the postal address (street and number). Required, 1–100 characters.
      - `line2` string: Optional second line of the postal address (apartment, suite, building). Up to 100 characters.
      - `city` string, required: City or locality of the billing address. Required.
      - `state` string: State, region, or province. Free-form text to accommodate heterogeneous tax jurisdictions; prefer ISO 3166-2 subdivision codes when known.
      - `zip` string, required: Postal / ZIP code. Required. Kept as a string to preserve leading zeros and non-numeric formats (UK, Canada, …).
      - `country` 'FR' | 'BE' | 'DE' | 'ES' | 'IT', required: ISO 3166-1 alpha-2 country code of the billing address, limited to the countries onboarding v3 supports at launch.

## Response `200`

Upgrade checkout URL returned successfully

- UpgradeCheckoutResponseDto
  - `url` string, uri, required: Chargebee-hosted page URL that changes the organization's existing subscription to the requested item price. Redirect the user to it.
  - `hostedPageId` string, required: Chargebee hosted page ID to submit to POST /billing/upgrade/complete once the checkout redirects back.

## Other responses

- `400`: Organization has no active Chargebee subscription
- `422`: Not an upgrade of the current plan (BILLING_UPGRADE_NOT_ALLOWED), billing identity missing for the first paid plan of a trial organization (BILLING_UPGRADE_IDENTITY_REQUIRED), identity inconsistent, or company closed (ONBOARDING_COMPANY_CLOSED)

---

[API](https://skmtc.dev/keyban/apis/keyban-rest-apis.md) · [All operations](https://skmtc.dev/keyban/apis/keyban-rest-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/keyban/apis/keyban-rest-apis/revisions/0bb79a1da961?raw)