---
title: "Create promotion code"
method: POST
path: "/v1/promotion-codes"
tags: ["Coupons > Promotion codes"]
---

# Create promotion code

`POST /v1/promotion-codes`

Create a new promotion code.

## Request body

- object
  - `code` string, required — Promotion code.
  - `coupon_id` string, required — Coupon ID.
  - `customer_id` string, nullable — If a `customer_id` is set, this promotion code will only be available to this customer.
  - `plan_id` string, nullable — If a `plan_id` is set, this promotion code will only be available for subscriptions with this plan ID.
  - `product_id` string, nullable — If a `product_id` is set, this promotion code will only be available for subscriptions with this product ID.
  - `expires_at` string, date-time, nullable — Date and time when the promotion code expires.
  - `max_redemptions` number, nullable — Maximum number of redemptions for the promotion code. Independent from coupon's max redemptions.
  - `current_redemptions` integer, nullable — Current number of redemptions for the promotion code.
  - `duration_count` integer, nullable — Duration count applied to the subscription for the promotion code. 0 or null for `once`
  - `duration_period` 'once' | 'days' | 'weeks' | 'months' | 'years', nullable — Duration period applied to the subscription for the promotion code for the promotion code. Valid values are `once`, `days`, `weeks`, `months`, `years`
  - `only_for_first_time_order` boolean, nullable — Whether the promotion code is only for first time orders. Defaults to `false`

## Response `201`

The newly created promotion code

- object
  - `id` string, required — Promotion code ID.
  - `code` string, required — Promotion code.
  - `coupon_id` string, required — Coupon ID.
  - `client_id` string, required — Client ID.
  - `customer_id` string, nullable, required — If a `customer_id` is set, this promotion code will only be available to this customer.
  - `plan_id` string, nullable, required — If a `plan_id` is set, this promotion code will only be available for subscriptions with this plan ID.
  - `product_id` string, nullable, required — If a `product_id` is set, this promotion code will only be available for subscriptions with this product ID.
  - `created_at` string, date-time, required — Promotion code creation date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
  - `updated_at` string, date-time, required — Promotion code last edition date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
  - `expires_at` string, date-time, nullable, required — Date and time when the promotion code expires.
  - `max_redemptions` number, nullable, required — Maximum number of redemptions for the promotion code. Independent from coupon's max redemptions.
  - `current_redemptions` number, nullable, required — Current number of redemptions for the promotion code.
  - `duration_count` number, nullable, required — Duration count applied to the subscription for the promotion code. 0 or null for `once`
  - `duration_period` 'once' | 'days' | 'weeks' | 'months' | 'years', nullable, required — Duration period applied to the subscription for the promotion code for the promotion code. Valid values are `once`, `days`, `weeks`, `months`, `years`
  - `only_for_first_time_order` boolean, nullable, required — Whether the promotion code is only for first time orders. Defaults to `false`

---

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