---
title: "Start checkout or open the billing portal"
method: POST
path: "/v1/workspaces/{workspaceId}/billing/checkout"
---

# Start checkout or open the billing portal

`POST /v1/workspaces/{workspaceId}/billing/checkout`

## Request

- Base URL: `https://api.bangermail.com`
- URL: `https://api.bangermail.com/v1/workspaces/{workspaceId}/billing/checkout`
- Auth: HTTP bearer

Requires workspace:admin. Premium (plan key starter) is the one plan sold online. An active subscription opens the customer portal. Snake-case fields take precedence over camel-case aliases.

## Path parameters

- `workspaceId` string, uuid, required

## Request body

- union
  - object
    - `plan_key` 'premium' | 'starter', required: Premium; its plan key is starter.
    - `planKey` 'premium' | 'starter'
    - `interval` 'month' | 'year'
    - `billing_attempt_id` string: Optional retry identifier: 8–64 letters, digits or hyphens. Invalid identifiers are ignored.
    - `billingAttemptId` string
  - object
    - `plan_key` 'premium' | 'starter': Premium; its plan key is starter.
    - `planKey` 'premium' | 'starter', required
    - `interval` 'month' | 'year'
    - `billing_attempt_id` string: Optional retry identifier: 8–64 letters, digits or hyphens. Invalid identifiers are ignored.
    - `billingAttemptId` string

## Response `200`

Successful response.

- object
  - `data` object, required
    - `url` string, uri, required
    - `kind` 'checkout' | 'portal', required
    - `discount` SwitchMonthDiscount: Switch from Mailchimp: one month off the first yearly invoice.
      - `offer` 'switch_from_mailchimp', required
      - `source` 'signup_campaign' | 'mailchimp_connection', required
      - `planKey` 'starter', required
      - `interval` 'year', required
      - `currency` string, required: Lowercase ISO currency the amounts are in.
      - `amountOff` integer, required: In the currency's smallest unit.
      - `yearlyPrice` integer, required: In the currency's smallest unit.
      - `firstYearPrice` integer, required: In the currency's smallest unit.
      - `message` string, required: A sentence to tell the person.
    - `switchOffer` SwitchMonthDiscount: Switch from Mailchimp: one month off the first yearly invoice.
      - `offer` 'switch_from_mailchimp', required
      - `source` 'signup_campaign' | 'mailchimp_connection', required
      - `planKey` 'starter', required
      - `interval` 'year', required
      - `currency` string, required: Lowercase ISO currency the amounts are in.
      - `amountOff` integer, required: In the currency's smallest unit.
      - `yearlyPrice` integer, required: In the currency's smallest unit.
      - `firstYearPrice` integer, required: In the currency's smallest unit.
      - `message` string, required: A sentence to tell the person.

## Other responses

- `default`: Request failed.

---

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