---
title: "Change the monthly plan subscription: switch between Starter and Scale from the next renewal, or cancel or resume at the month's end"
method: PATCH
path: "/billing/subscription"
tags: ["billing"]
---

# Change the monthly plan subscription: switch between Starter and Scale from the next renewal, or cancel or resume at the month's end

`PATCH /billing/subscription`

## Request

- Base URL: `https://api.letsship.ai/v1`
- URL: `https://api.letsship.ai/v1/billing/subscription`
- Auth: none declared

## Request body

- UpdateSubscriptionRequest
  - `orgId` string
  - `plan` 'starter' | 'scale'
  - `cancelAtPeriodEnd` boolean

## Response `200`

The subscription

- SubscriptionResponse
  - `subscription` TeamSubscription, required
    - `plan` 'starter' | 'scale', required
    - `name` string, required
    - `priceUsd` number, required
    - `creditsPerMonth` integer, required
    - `perCreditUsd` number, required
    - `agentsAtOnce` integer, required
    - `status` 'incomplete' | 'active' | 'past_due' | 'canceled', required
    - `nextPlan` SubscribedPlan, required
      - `plan` 'starter' | 'scale', required
      - `name` string, required
      - `priceUsd` number, required
      - `creditsPerMonth` integer, required
      - `perCreditUsd` number, required
      - `agentsAtOnce` integer, required
    - `currentPeriodEnd` integer, nullable, required
    - `cancelAtPeriodEnd` boolean, required

## Other responses

- `400`: Nothing to change (code nothing_to_change), or an unknown plan
- `401`: Unauthenticated
- `403`: Not a billing manager (code billing_manage_required)
- `404`: Not one of the caller's orgs
- `409`: The org has no monthly plan (code team_subscription_required)
- `502`: The change could not be made (code subscription_change_failed); nothing changed
- `503`: Checkout is not set up in this environment (code checkout_not_configured)

---

[API](https://skmtc.dev/letsship/apis/ship-api.md) · [All operations](https://skmtc.dev/letsship/apis/ship-api/llms.txt) · [OpenAPI document](https://skmtc.dev/letsship/apis/ship-api/revisions/e6eac1bcadd4?raw)