---
title: "createCoupon"
method: POST
path: "/v1/coupon"
tags: ["Coupon"]
---

# createCoupon

`POST /v1/coupon`

Create a new coupon entity

## Request body

- CouponCreate
  - `_schema` 'coupon'
  - `name` string, required
  - `description` string
  - `type` 'fixed' | 'percentage', required
  - `category` 'discount' | 'cashback', required
  - `percentage_value` string — Use if type is set to percentage. The percentage to be discounted, represented as a whole integer.
  - `fixed_value` number — Use if type is set to fixed. The fixed amount in cents to be discounted, represented as a whole integer.
  - `fixed_value_decimal` string — Use if type is set to fixed. The unit amount in cents to be discounted, represented as a decimal string with at most 12 decimal places.
  - `fixed_value_currency` string — Three-letter ISO currency code, in lowercase. Must be a supported currency. ISO 4217 CURRENCY CODES as specified in the documentation: https://www.iso.org/iso-4217-currency-codes.html
  - `cashback_period` '0' | '12' — The cashback period, for now it's limited to either 0 months or 12 months
  - `active` boolean, required
  - `requires_promo_code` boolean — Whether the coupon requires a promo code to be applied
  - `prices` BaseRelation
    - `$relation` object[], required
      - `entity_id` string, uuid
      - `_tags` string[], nullable
  - `promo_codes` PromoCode[]
    - `id` string, required — The id of the promo code
    - `code` string, required — The code of the promo code
    - `has_usage_limit` boolean — Whether the promo code has a usage limit
    - `usage_limit` number, nullable — The usage limit of the promo code
  - `promo_code_usage` object — Map of ids of promo codes with their usage count
  - `_tags` string[], nullable
  - `_purpose` string[], nullable
  - `_files` BaseRelation
    - `$relation` object[], required
      - `entity_id` string, uuid
      - `_tags` string[], nullable
  - `_manifest` string[] — Manifest ID used to create/update the entity
  - `__additional` object, nullable — Additional fields that are not part of the schema

## Response `201`

Coupon entity response

- Coupon
  - `_id` string, uuid
  - `_schema` 'coupon', required
  - `_org` string, required — Organization Id the entity belongs to
  - `_tags` string[], nullable
  - `_files` BaseRelation
    - `$relation` object[], required
      - `entity_id` string, uuid
      - `_tags` string[], nullable
  - `_owners` BaseEntityOwner[]
    - `org_id` string, required
    - `user_id` string
  - `_title` string
  - `_created_at` string, date-time
  - `_updated_at` string, date-time
  - `_acl` BaseEntityAcl — Access control list (ACL) for an entity. Defines sharing access to external orgs or users.
    - `view` string[]
    - `edit` string[]
    - `delete` string[]
  - `name` string, required
  - `description` string
  - `type` 'fixed' | 'percentage', required
  - `category` 'discount' | 'cashback', required
  - `percentage_value` string — Use if type is set to percentage. The percentage to be discounted, represented as a whole integer.
  - `fixed_value` number — Use if type is set to fixed. The fixed amount in cents to be discounted, represented as a whole integer.
  - `fixed_value_decimal` string — Use if type is set to fixed. The unit amount in cents to be discounted, represented as a decimal string with at most 12 decimal places.
  - `fixed_value_currency` string — Three-letter ISO currency code, in lowercase. Must be a supported currency. ISO 4217 CURRENCY CODES as specified in the documentation: https://www.iso.org/iso-4217-currency-codes.html
  - `cashback_period` '0' | '12' — The cashback period, for now it's limited to either 0 months or 12 months
  - `active` boolean, required
  - `requires_promo_code` boolean — Whether the coupon requires a promo code to be applied
  - `prices` BaseRelation
    - `$relation` object[], required
      - `entity_id` string, uuid
      - `_tags` string[], nullable
  - `promo_codes` PromoCode[]
    - `id` string, required — The id of the promo code
    - `code` string, required — The code of the promo code
    - `has_usage_limit` boolean — Whether the promo code has a usage limit
    - `usage_limit` number, nullable — The usage limit of the promo code
  - `promo_code_usage` object — Map of ids of promo codes with their usage count
  - `_purpose` string[], nullable
  - `_manifest` string[] — Manifest ID used to create/update the entity
  - `__additional` object, nullable — Additional fields that are not part of the schema

## Other responses

- `400` — Any error based on client data errors
- `500` — Any error based on the server-side

---

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