---
title: "Add new promotion"
method: POST
path: "/promotions"
tags: ["Promotions"]
---

# Add new promotion

`POST /promotions`

## Request

- Base URL: `https://api.c1st.com/api`
- URL: `https://api.c1st.com/api/promotions`
- Auth: HTTP bearer

**NB:** If you want to add discount price to a specific product use discountprice on [Product](https://api-docs.c1st.com/#tag/Products/operation/replaceProduct) instead.

Create a new promotion that results in an automatic discount when matching products are put in the POS cart.

The automatic assignment of discounts is based product filters (explained in more detail below).
When these filters match, the promotion triggers an action resulting in some kind of discount presentend in the cart.
Currently, actions come in two flavors: *single product discounts* and *bundle discounts*.
How the promotion will trigger depends on this flavor.

Single product discounts (`percentage`, `adjustPriceBy`, `percentageByCostprice`, `totalPriceUnit`):
  Here, a single product gets discount by some amount.
  The filters can match against productnos, brands and tags.

Each promotion has a required `name` which shown in the cart when the discount is given.
`description` is optional and designed only for humans to read. It is only shown in the settings.
`active` can be used to disable promotions until they are ready.
Promotions will also only be considered active when today's date is inside the `startdate`-`enddate`-range.
If `enddate` is `null`, the promotion is considered to run forever.

Product filters are inclusive by nature. In the future, excluding filters will be added as well.
Filters have an `attribute` and a `value`. The attribute can be various attributes of a product, like `tag` and `productno`.
For instance, to give a discount on all bikes with tag *Bike*, see the example below).
The `value` can be a list of values in which case, if either of the values match, the filter matches.
And if either of the filters matches, the promotion will trigger (in case of single product discounts).

The filters for bundle discounts currently needs to be very specific:
A single filter with `attribute` = productno and `value` = *list of productnos*.

In the future, it will be possible to filter based on customer attributes as well, such that specific customers can get certain discounts.

## Request body

- object
  - `content` Promotion: Object representing a promotion.
    - `id` integer, nullable: A unique ID. Use this to handle this subscription.
    - `name` string: Short name for the promotion
    - `description` string, nullable: Description of the promotion. This is only displayed in the controlpanel, not for the customers.
    - `deleted` 0 | 1, nullable: Whether or not the promotion is deleted. Disabled promotions do not trigger even when inside the date range.
    - `startdate` string, nullable: Specifies when the promotion starts. Null if the promotion has no startdate and thus is always in effect (except if deleted).
    - `enddate` string, nullable: Specifies when the promotion ends. Null if the promotion has no enddate.
    - `minproducts` integer, nullable: Minimum number of prodcts before the promotion is in effect
    - `applyall` boolean, nullable: Whether or not to apply promotion to all
    - `productfilters` PromotionProductFilter[], nullable
      - `attribute` 'product_productno' | 'product_tag' | 'product_brand' | 'product_styleno': What attribute to filter the promotion on.
      - `value` union
        - string, nullable: The value that the attribute needs to have to match.
        - string[], nullable: A list of possible values. The attribute needs to match at least one of the values for the rule to apply.
    - `customerfilters` PromotionCustomerFilter[], nullable
      - `attribute` 'customer_tag': What attribute to filter the promotion on.
      - `value` union
        - string[]: A list of possible values. The attribute needs to match at least one of the values for the rule to apply.
        - string: The value that the attribute needs to have to match.
    - `loyalty_members_only` boolean, nullable
    - `serviceplanfilters` PromotionServicePlanFilter[], nullable
      - `attribute` 'serviceplan_handle': What attribute to filter the promotion on.
      - `value` union
        - string[]: A list of possible values. The attribute needs to match at least one of the values for the rule to apply.
        - string: The value that the attribute needs to have to match.
    - `articles` CartArticle[], nullable: A list of products from the cart that match the promotion. This will only be set in the case of the lookup endpoint.
      - `productno` string, nullable: The product number of the product that the article represents.
      - `quantity` number, nullable: The amount that is present of that product.
    - `storeid` integer, nullable
    - `productno_counts` object[]
      - `productno` string, nullable
      - `count` number, nullable
    - `count` integer, nullable: The number of times this promotion matches things in the cart. This will only be set in the case of the lookup endpoint.
    - `action` PromotionAction: The action / effect the promotion has on checkout.
      - `type` 'percentage' | 'adjustPriceBy' | 'percentageByCostprice' | 'totalPriceUnit': The type of the action.
      - `amount` number, double: The amount to be deducted, depending on the `type`.

## Response `200`

Ok

- object
  - `id` integer: The id of the promotion.

---

[API](https://skmtc.dev/c1st/apis/customers-1st-api.md) - [All operations](https://skmtc.dev/c1st/apis/customers-1st-api/llms.txt) - [OpenAPI document](https://skmtc.dev/c1st/apis/customers-1st-api/revisions/4250bb326f2a?raw)