---
title: "Publish plan version"
method: PUT
path: "/plans/version/{plan_version_id}/publish"
tags: ["plans"]
---

# Publish plan version

`PUT /plans/version/{plan_version_id}/publish`

## Path parameters

- `plan_version_id` string, required

## Request body

- PublishPlanVersionRequestBody
  - `activation_strategy` 'on_payment' | 'on_publish'
  - `address` CustomerBillingAddress
    - `city` string, required
    - `country` string, required
    - `line1` string, required
    - `line2` string, required
    - `postal_code` string, required
    - `state` string, required
  - `billing_cycle_anchor` string, date-time, nullable — The date the subscription's billing period renews on. Only honored on a first publish that starts a subscription.
  - `coupon_external_id` string, nullable
  - `custom_field_values` CheckoutFieldValue[], nullable
    - `id` string, required
    - `value` string, required
  - `customer_email` string, nullable
  - `days_until_due` integer, nullable
  - `excluded_company_ids` string[], required
  - `migration_strategy` 'end_of_billing_period' | 'immediate' | 'leave', required
  - `phone` string, nullable
  - `prorate_first_period` boolean, nullable — When true, the partial period between the subscription starting and its renewal date is billed pro rata straight away. When false that period is free and no invoice is raised until the renewal date. Only applies alongside billing_cycle_anchor. Defaults to true.
  - `proration_behavior` 'always_invoice' | 'create_prorations' | 'none'
  - `require_no_migration` boolean, nullable — Refuse the publish if any company would be migrated onto the new version
  - `send_invoice` boolean, nullable — Whether Stripe emails the invoice when it is finalized. Defaults to true.
  - `tax_id` TaxIDInput
    - `type` 'ae_trn' | 'au_abn' | 'au_arn' | 'br_cnpj' | 'br_cpf' | 'ca_bn' | 'ca_gst_hst' | 'ca_pst_bc' | 'ca_pst_mb' | 'ca_pst_sk' | 'ca_qst' | 'ch_uid' | 'ch_vat' | 'eu_vat' | 'gb_vat' | 'hk_br' | 'id_npwp' | 'il_vat' | 'in_gst' | 'jp_cn' | 'jp_rn' | 'jp_trn' | 'kr_brn' | 'mx_rfc' | 'my_frp' | 'my_itn' | 'my_sst' | 'no_vat' | 'nz_gst' | 'ph_tin' | 'sa_vat' | 'sg_gst' | 'sg_uen' | 'th_vat' | 'tr_tin' | 'tw_vat' | 'us_ein' | 'za_vat', required
    - `value` string, required

## Response `200`

OK

- object
  - `data` PlanVersionResponseData, required
    - `created_at` string, date-time, required
    - `description` string, required
    - `environment_id` string, required
    - `icon` 'amber' | 'blue' | 'blueGray' | 'blueGreen' | 'cyan' | 'emerald' | 'fuchsia' | 'gray' | 'green' | 'indigo' | 'lightBlue' | 'lime' | 'orange' | 'pink' | 'purple' | 'red' | 'redOrange' | 'rose' | 'sky' | 'slate' | 'teal' | 'trueGray' | 'violet' | 'warmGray' | 'yellow', required
    - `id` string, required
    - `name` string, required
    - `original_plan_id` string, nullable
    - `plan_type` 'plan' | 'add_on', required
    - `status` 'published' | 'draft' | 'archived', required
    - `updated_at` string, date-time, required
    - `version` integer, required
  - `params` object, required — Input parameters

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `500` — Server error

## Changes

> 125 revisions in range; 1 could not be searched.

- **2026-08-24** `05da7dce1cf9` — 2 info
  - added the new optional request property `billing_cycle_anchor`
  - added the new optional request property `prorate_first_period`
- **2026-08-24** `54c21fb8a4b7` — 1 info
  - added the new `end_of_billing_period` enum value to the request property `migration_strategy`
- **2026-08-18** `82656c1cb6fc` — 1 info
  - added the new `none` enum value to the request property `proration_behavior/allOf[#/components/schemas/MigrationProrationBehavior]/`
- **2026-08-17** `7b61d0321b14` — 1 info
  - added the new optional request property `require_no_migration`

[Change history](https://skmtc.dev/schematichq/apis/schematic-api/changes/plans/version/:plan_version_id/publish/put.md)

---

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