Create plan - Commet

cURL

curl --request POST \
  --url https://commet.co/api/v1/plans \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "code": "<string>"
}
'

client, err := commet.New("ck_xxx")
if err != nil {
	log.Fatal(err)
}
ctx := context.Background()

plan, err := client.Plans.Create(ctx, &commet.CreatePlanParams{
	Name: "example",
	Code: "api_calls",
})
if err != nil {
	log.Fatal(err)
}

import co.commet.Commet;
import co.commet.params.CreatePlanParams;

var commet = Commet.builder().apiKey("ck_xxx").build();

var plan = commet.plans().create(
    CreatePlanParams.builder("example", "api_calls").build()
);

{
  "id": "plan_1a2b3c4d",
  "name": "Pro",
  "code": "pro",
  "description": "For growing API products",
  "consumptionModel": "metered",
  "isPublic": true,
  "isDefault": false,
  "isFree": false,
  "blockOnExhaustion": true,
  "sortOrder": 0,
  "planGroupId": "group_1a2b3c4d",
  "metadata": {},
  "createdAt": "2026-09-07T12:00:00.000Z",
  "updatedAt": "2026-09-07T12:00:00.000Z",
  "features": [
    {
      "code": "api_calls",
      "name": "API Calls",
      "type": "usage",
      "unitName": "calls",
      "enabled": true,
      "includedAmount": 1000,
      "unlimited": false,
      "overage": {
        "enabled": false,
        "model": null,
        "unitPrice": null
      },
      "regionalPrices": []
    }
  ],
  "prices": [
    {
      "id": "price_1a2b3c4d",
      "billingInterval": "monthly",
      "price": 2000,
      "isDefault": true,
      "trialDays": 0,
      "includedBalance": null,
      "includedCredits": null,
      "offerId": null,
      "inheritsFromPriceId": null,
      "metadata": {},
      "marketPrices": [],
      "regionalPrices": []
    }
  ],
  "exchangeRates": [],
  "object": "plan",
  "livemode": false
}

{
  "error": {
    "type": "validation_error",
    "code": "validation_error",
    "message": "The request contains an invalid parameter.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized",
    "message": "A valid API key is required.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "forbidden",
    "message": "You do not have permission to perform this operation.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md"
  }
}

{
  "error": {
    "type": "not_found_error",
    "code": "not_found",
    "message": "The requested resource was not found.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md"
  }
}

{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_in_progress",
    "message": "A request with this idempotency key is still being processed.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. Retry after the interval specified in the Retry-After header.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md"
  }
}

{
  "error": {
    "type": "internal_error",
    "code": "internal_error",
    "message": "An unexpected error occurred while processing the request.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md"
  }
}

{
  "error": {
    "type": "internal_error",
    "code": "idempotency_unavailable",
    "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md"
  }
}

POST

plans

cURL

curl --request POST \
  --url https://commet.co/api/v1/plans \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "code": "<string>"
}
'

client, err := commet.New("ck_xxx")
if err != nil {
	log.Fatal(err)
}
ctx := context.Background()

plan, err := client.Plans.Create(ctx, &commet.CreatePlanParams{
	Name: "example",
	Code: "api_calls",
})
if err != nil {
	log.Fatal(err)
}

import co.commet.Commet;
import co.commet.params.CreatePlanParams;

var commet = Commet.builder().apiKey("ck_xxx").build();

var plan = commet.plans().create(
    CreatePlanParams.builder("example", "api_calls").build()
);

{
  "id": "plan_1a2b3c4d",
  "name": "Pro",
  "code": "pro",
  "description": "For growing API products",
  "consumptionModel": "metered",
  "isPublic": true,
  "isDefault": false,
  "isFree": false,
  "blockOnExhaustion": true,
  "sortOrder": 0,
  "planGroupId": "group_1a2b3c4d",
  "metadata": {},
  "createdAt": "2026-09-07T12:00:00.000Z",
  "updatedAt": "2026-09-07T12:00:00.000Z",
  "features": [
    {
      "code": "api_calls",
      "name": "API Calls",
      "type": "usage",
      "unitName": "calls",
      "enabled": true,
      "includedAmount": 1000,
      "unlimited": false,
      "overage": {
        "enabled": false,
        "model": null,
        "unitPrice": null
      },
      "regionalPrices": []
    }
  ],
  "prices": [
    {
      "id": "price_1a2b3c4d",
      "billingInterval": "monthly",
      "price": 2000,
      "isDefault": true,
      "trialDays": 0,
      "includedBalance": null,
      "includedCredits": null,
      "offerId": null,
      "inheritsFromPriceId": null,
      "metadata": {},
      "marketPrices": [],
      "regionalPrices": []
    }
  ],
  "exchangeRates": [],
  "object": "plan",
  "livemode": false
}

{
  "error": {
    "type": "validation_error",
    "code": "validation_error",
    "message": "The request contains an invalid parameter.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized",
    "message": "A valid API key is required.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "forbidden",
    "message": "You do not have permission to perform this operation.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md"
  }
}

{
  "error": {
    "type": "not_found_error",
    "code": "not_found",
    "message": "The requested resource was not found.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md"
  }
}

{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_in_progress",
    "message": "A request with this idempotency key is still being processed.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. Retry after the interval specified in the Retry-After header.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md"
  }
}

{
  "error": {
    "type": "internal_error",
    "code": "internal_error",
    "message": "An unexpected error occurred while processing the request.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md"
  }
}

{
  "error": {
    "type": "internal_error",
    "code": "idempotency_unavailable",
    "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.",
    "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md"
  }
}

Create a new plan with optional consumption model, visibility, and plan group assignment.

Authorizations

x-api-key

string

header

required

Headers

Idempotency-Key

string

Unique key used to safely retry this write for 24 hours without applying it twice.

Required string length: 1 - 200

Commet-Version

string

default:2026-08-27

API version used by this reference. Send this header to select this contract explicitly.

Body

application/json

name

string

required

Minimum string length: 1

code

string

required

Minimum string length: 1

Pattern: ^[a-z0-9_]+$

description

string

consumptionModel

enum<string>

Available options:

metered,

credits,

balance

isPublic

boolean

isFree

boolean

blockOnExhaustion

boolean

Credits and balance plans. Omitted, credits plans and free plans stop usage when the plan and purchased amounts run out, and paid balance plans bill the missing balance as overage. A new credits plan always stops usage: it allows overage only with a price per credit, which is set after creation, and then PATCH /v1/plans/{id} turns overage on.

unusedPlanCredits

object

Credits plans only. What happens to unused plan credits at each reset; omitted means they expire.

Option 1
Option 2

Show child attributes

planCreditLimit

object | null

Credits plans only. The most plan credits a subscription spends per day or per week; omitted or null means no limit.

Show child attributes

unusedPlanBalance

object

Balance plans only. What happens to unused plan balance at each reset; omitted means it expires.

Option 1
Option 2

Show child attributes

planBalanceLimit

object | null

Balance plans only. The most plan balance a subscription spends per day or per week, in USD cents; omitted or null means no limit.

Show child attributes

planGroupId

string

isDefault

boolean

Make this plan the default plan of its plan group: customers created with that planGroupId start on it, and a paid plan of the group that ends from the customer portal, a revoked payment authorization or exhausted dunning moves to it instead of canceling. Requires a free plan with a planGroupId; replaces the group's previous default plan.

metadata

object

Show child attributes

Response

Success

string

required

name

string

required

code

string

required

description

string | null

required

consumptionModel

enum<string> | null

required

Available options:

metered,

credits,

balance

isPublic

boolean

required

isDefault

boolean

required

isFree

boolean

required

blockOnExhaustion

boolean | null

required

Credits and balance plans: true stops usage when the plan and purchased amounts run out; false lets usage continue and bills the missing amount as overage at the next renewal (credits at the price per credit). Trials and free plans always stop.

unusedPlanCredits

object

required

Credits plans only; null for other consumption models. What happens to unused plan credits at each reset. Purchased credits never expire and never count toward maxPlanCredits.

Option 1
Option 2

Show child attributes

planCreditLimit

object | null

required

Credits plans only. The most plan credits a subscription spends per day or per week; null means no limit.

Show child attributes

unusedPlanBalance

object

required

Balance plans only; null for other consumption models. What happens to unused plan balance at each reset. Purchased balance never expires and never counts toward maxPlanBalance.

Option 1
Option 2

Show child attributes

planBalanceLimit

object | null

required

Balance plans only. The most plan balance a subscription spends per day or per week, in USD cents; null means no limit.

Show child attributes

sortOrder

integer

required

Required range: -9007199254740991 <= x <= 9007199254740991

planGroupId

string | null

required

metadata

object | null

required

Show child attributes

createdAt

string<date-time>

required

updatedAt

string<date-time>

required

features

object[]

required

Show child attributes

prices

object[]

required

Show child attributes

exchangeRates

object[]

required

Show child attributes

countries

object[]

required

Countries with their own currency or prices in the current version. Buyers from any other country pay the USD prices.

Show child attributes

object

string

required

Allowed value: "plan"

livemode

boolean

required