---
title: "Change the current cloud user's subscription"
method: POST
path: "/api/internal/subscription"
tags: ["Cloud Billing"]
---

# Change the current cloud user's subscription

`POST /api/internal/subscription`

Change the current cloud user's subscription.

## Request body

- CloudBillingChangeRequest — The request to change the self-billed cloud subscription.
  - `checkoutSession` CloudBillingChangeRequestCheckoutSessionRequestParams — Checkout session preferences.
    - `cancelUrlPath` string — The path component of the cancel URL.
    - `force` boolean — Whether to force the checkout session to be created. (debugging)
    - `redirectOnCompletion` 'always' | 'if_required' | 'never' — Create Stripe checkout session redirect on completion.
    - `returnUrlPath` string — The path component of the return URL.
    - `successUrlPath` string — The path component of the success URL.
    - `uiMode` 'embedded' | 'hosted', required — Stripe CheckoutSession.ui_mode
  - `targetPlanID` string, required — The target plan ID.

## Response `200`

The request has succeeded.

- union — The response to a cloud billing change request.
  - CloudBillingChangeResponseCheckoutRequired — The response to a cloud billing change request.
    - `checkoutSession` CreateStripeCheckoutSessionResult, required — Create Stripe Checkout Session response.
      - `cancelURL` string — Cancel URL.
      - `clientReferenceId` string — A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the session with your internal systems.
      - `clientSecret` string — The client secret of the checkout session. This can be used to initialize Stripe.js for your client-side implementation.
      - `createdAt` string, date-time, required — Timestamp at which the checkout session was created.
      - `currency` string — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience.
      - `customerEmail` string — Customer's email address provided to Stripe.
      - `customerId` string, required — The OpenMeter customer ID.
      - `expiresAt` string, date-time — Timestamp at which the checkout session will expire.
      - `metadata` object — Set of key-value pairs attached to the checkout session.
      - `mode` 'setup', required — Stripe CheckoutSession.mode
      - `returnURL` string — Return URL.
      - `sessionId` string, required — The checkout session ID.
      - `setupIntentId` string, required — The checkout session setup intent ID.
      - `status` string — The status of the checkout session.
      - `stripeCustomerId` string, required — The Stripe customer ID.
      - `successURL` string — Success URL.
      - `url` string — URL to show the checkout session.
    - `type` 'checkout_required', required
  - CloudBillingChangeResponseApplied — The response to a cloud billing change request.
    - `type` 'applied', required
  - CloudBillingChangeResponseWillApply — The response to a cloud billing change request.
    - `newSubscriptionStartsAt` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
    - `type` 'will_apply', required

## Other responses

- `400` — The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
- `401` — The request has not been applied because it lacks valid authentication credentials for the target resource.
- `403` — The server understood the request but refuses to authorize it.
- `412` — One or more conditions given in the request header fields evaluated to false when tested on the server.
- `500` — The server encountered an unexpected condition that prevented it from fulfilling the request.
- `503` — The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.
- `default` — An unexpected error response.

---

[API](https://skmtc.dev/openmeter/apis/openmeter-cloud-api.md) · [All operations](https://skmtc.dev/openmeter/apis/openmeter-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openmeter/openmeter-cloud-api/revisions/c9c0ec9cffe9/schema)