---
title: "Create a new Promotion."
method: POST
path: "/promotions.json"
tags: ["Promotions"]
---

# Create a new Promotion.

`POST /promotions.json`

## Request body

- PromotionEdit
  - `promotion` PromotionEditFields
    - `name` string — Name of the product
    - `enabled` boolean — If the promotion is to be temporarily disabled
    - `discount_target` string — Where the promotion will be applied ('order', 'shipping', 'categories', 'buy_x_get_y)
    - `buys_at_least` string — Controls the promotion's condition ('none', 'price', 'qty, 'single_item')
    - `condition_price` number, float — Minimum order amount to validate the promotion (requires 'buys_at_least' param - 'price')
    - `condition_qty` integer — Minimum quantity of ordered itens to validate the promotion (requires 'buys_at_least' param - 'qty' or 'single_item')
    - `quantity_x` integer — Number of sets of products_x needed to be able to apply the promotion (requires 'discount_target' param - 'buy_x_get_y')
    - `type` string — Controls if the discount will be a fixed area ('fix', 'percentage')
    - `discount_amount_fix` number, float — Fixed discount amount of the promotion (requires 'type' param - 'fix')
    - `discount_amount_percent` number, float — Percentual discount amount of the promotion (requires 'type' param - 'percentage')
    - `lasts` string — Controls when the promotion will expire ('none', 'date', 'max_times_used', 'both')
    - `begins_at` string — Creation date of the promotion (requires 'lasts' param - 'date' or 'both')
    - `expires_at` string — Expiration date of the promotion (requires 'lasts' param - 'date' or 'both')
    - `max_times_used` integer — Maximum amount a promotion can be used (requires 'lasts' param - 'max_times_used' or 'both')
    - `cumulative` boolean — True if the promotion can be acumulated with others
    - `customers` string — Controls to which customers the promotion will be applied ('all', 'loggedin', 'categories', 'guests')
    - `categories` Id[] — Products Categories where the promotion will be applied
      - `id` integer
    - `categories_x` Id[] — Categories required to apply the promotion (requires 'discount_target' param - 'buy_x_get_y')
      - `id` integer
    - `customer_categories` Id[] — Customer Categories to whom the promotion will be applied (requires 'customers' param - 'categories')
      - `id` integer
    - `products` Id[] — Products where the promotion will be applied (requires 'discount_target' param - 'categories' or 'buy_x_get_y')
      - `id` integer
    - `products_x` Id[] — Products required to apply the promotion (requires 'discount_target' param - 'buy_x_get_y')
      - `id` integer
    - `coupons` CouponEditFields[] — Coupons associated to the promotion.
      - `code` string — Unique code that can be used to activate the promotion.
      - `usage_limit` integer — Maximum number of times the coupon can be used. Zero when there is no limit.
    - `countries` string[] — Country codes (ISO 3166-1 alpha-2) to apply the promotion (requires `discount_target` param - `shipping`). `*` means 'All Countries'.
    - `regions` string[] — Region codes (Use the FIPS standard - http://www.geonames.org/countries/) to apply the promotion (requires `discount_target` param - `shipping`). Format as follows `country_region` (e.g. `CL_03` for region Antofagasta in Chile). `*_*` for 'All regions'.
    - `municipalities` string[] — Municipality codes to apply the promotion (requires `discount_target` param - `shipping`). Format as follows `country_region_municipality` (e.g. `CL_03_8261495` for Calama municipality in Chile region Antofagasta). `*_*_*` for 'All municipalities'

## Response `200`

OK

- Promotion
  - `promotion` PromotionFields
    - `id` integer — Unique identifier of the product
    - `name` string — Name of the product
    - `status` string — Status of the promotion ('active', 'expired')
    - `enabled` boolean — If the promotion is currently enabled
    - `discount_target` string — Where the promotion will be applied ('order', 'shipping', 'categories', 'buy_x_get_y)
    - `condition_price` number, float — Minimum order amount to validate the promotion
    - `condition_qty` integer — Minimum quantity of ordered itens to validate the promotion
    - `quantity_x` integer — Number of sets of products_x needed to be able to apply the promotion (requires 'discount_target' param - 'buy_x_get_y')
    - `discount_amount_fix` number, float — Fixed discount amount of the promotion
    - `discount_amount_percent` number, float — Percentual discount amount of the promotion
    - `lasts` string — Controls when the promotion will expire ('none', 'both', 'date', 'max_times_used')
    - `begins_at` string — Creation date of the promotion (requires 'lasts' param - 'date' or 'both)
    - `expires_at` string — Expiration date of the promotion (requires 'lasts' param - 'date' or 'both')
    - `times_used` integer — Amount of times the promotion was used
    - `max_times_used` integer — Maximum amount a promotion can be used (requires 'lasts' param - 'max_times_used' or 'both)
    - `cumulative` boolean — True if the promotion can be acumulated with others
    - `categories` Id[] — Products Categories where the promotion will be applied (requires 'discount_target' param - 'categories')
      - `id` integer
    - `customer_categories` Id[] — Customer Categories to whom the promotion will be applied (requires 'customers' param - 'categories')
      - `id` integer
    - `products` Id[] — Products where the promotion will be applied (requires 'discount_target' param - 'categories' or 'buy_x_get_y')
      - `id` integer
    - `products_x` Id[] — Products required to apply the promotion (requires 'discount_target' param - 'buy_x_get_y')
      - `id` integer
    - `coupons` Coupon[] — Coupons associated to the promotion.
      - `id` integer — Unique identifier of the coupon.
      - `code` string — Unique code that can be used to activate the promotion.
      - `usage_limit` integer — Maximum number of times the coupon can be used. Zero when there is no limit.
      - `times_used` integer — Number of times the coupon has been used.
    - `countries` string[] — Country codes (ISO 3166-1 alpha-2) to apply the promotion (requires `discount_target` param - `shipping`). `*` means 'All Countries'.
    - `regions` string[] — Region codes (Use the FIPS standard - http://www.geonames.org/countries/) to apply the promotion (requires `discount_target` param - `shipping`). Format as follows `country_region` (e.g. `CL_03` for region Antofagasta in Chile). `*_*` for 'All regions'.
    - `municipalities` string[] — Municipality codes to apply the promotion (requires `discount_target` param - `shipping`). Format as follows `country_region_municipality` (e.g. `CL_03_8261495` for Calama municipality in Chile region Antofagasta). `*_*_*` for 'All municipalities'

## Other responses

- `404` — Promotion Not Found.

---

[API](https://skmtc.net/jumpseller/apis/jumpseller-api.md) · [All operations](https://skmtc.net/jumpseller/apis/jumpseller-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/jumpseller/jumpseller-api/versions/7512c6ae3524/schema)