Create a promotion

Creates a new promotion for a shop. Promotions apply percentage or fixed-amount discounts via coupon codes or automatic rules. shop_id is required in the body.

POST/promotions

Authorization

AuthorizationBearer token (JWT) · headerrequired

Request body

requiredapplication/json

shop_idintegerrequired

ID of the shop (required on create)

namestringrequired

statusstring

default: "active"

Allowed:activeinactive

cumulativeboolean

Whether this promotion can stack with others. Defaults to `true`.

default: true

discount_typestringrequired

Allowed:fixedpercentagefree-shipping

discountnumberrequired

Discount value — a percentage (0–100) or a fixed amount in cents.

activation_modestringrequired

How the promotion is activated. `code` requires a coupon code; `auto` applies automatically to eligible orders; `fulfillment` activates for a specific fulfillment method; `payment` activates for a specific payment method.

Allowed:codeautofulfillmentpayment

codestring

Coupon code (required when `activation_mode` is `code`).

fulfillment_methodinteger

Fulfillment method ID (required when `activation_mode` is `fulfillment`).

payment_method_idinteger

Payment method ID (required when `activation_mode` is `payment`).

usage_limitinteger

Maximum total redemptions. Unlimited if omitted.

per_user_limitinteger

Maximum redemptions per customer. Unlimited if omitted.

starts_atstring<date-time>

expires_atstring<date-time>

price_range_frominteger

Minimum order subtotal in cents for the promotion to apply.

price_range_tointeger

Maximum order subtotal in cents for the promotion to apply.

product_range_frominteger

Minimum number of qualifying products required in the cart.

product_range_tointeger

Maximum number of qualifying products allowed in the cart.

product_discount_group_idinteger

ID of the group whose products receive the discount.

product_discount_group_typestring

Allowed:AllProductsAllBundlesCollectionProductTypeVendorTagProduct

product_discount_group_filter_modestring

Which items within the discount group receive the discount.

Allowed:allall_exceptsingle_cheapestsingle_most_expensiveall_but_cheapestall_but_most_expensivecheapest_halfmost_expensive_halfcheapest_thirdmost_expensive_thirdcheapest_fourthmost_expensive_fourthsingle_cheapest_from_count_groupsingle_most_expensive_from_count_groupcheapest_half_from_count_groupmost_expensive_half_from_count_groupcheapest_third_from_count_groupmost_expensive_third_from_count_groupcheapest_fourth_from_count_groupmost_expensive_fourth_from_count_group

product_count_group_idinteger

Group used to count qualifying products (for count-gated discounts).

product_count_group_typestring

Allowed:AllProductsAllBundlesCollectionProductTypeVendorTagProduct

price_list_idinteger

Restrict the promotion to orders using this price list.

apply_tagstring

Tag to apply to the order when this promotion is used.

Responses

201Promotion created

422Validation error

Request

curl -X POST "https://api.onbolder.com/v2/promotions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "shop_id": 1,
  "name": "Summer Sale",
  "code": "SUMMER20",
  "discount_type": "percentage",
  "discount": 20,
  "activation_mode": "code",
  "starts_at": "2024-06-01T00:00:00Z",
  "expires_at": "2024-08-31T23:59:59Z"
}'

const response = await fetch("https://api.onbolder.com/v2/promotions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "shop_id": 1,
  "name": "Summer Sale",
  "code": "SUMMER20",
  "discount_type": "percentage",
  "discount": 20,
  "activation_mode": "code",
  "starts_at": "2024-06-01T00:00:00Z",
  "expires_at": "2024-08-31T23:59:59Z"
})
});

import requests

response = requests.post(
    "https://api.onbolder.com/v2/promotions",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
  "shop_id": 1,
  "name": "Summer Sale",
  "code": "SUMMER20",
  "discount_type": "percentage",
  "discount": 20,
  "activation_mode": "code",
  "starts_at": "2024-06-01T00:00:00Z",
  "expires_at": "2024-08-31T23:59:59Z"
},
)

Response

{
  "id": 20,
  "name": "Summer Sale",
  "code": "SUMMER20",
  "discount_type": "percentage",
  "discount": 20,
  "status": "active",
  "starts_at": "2024-06-01T00:00:00Z",
  "expires_at": "2024-08-31T23:59:59Z",
  "_links": {
    "self": {
      "href": "https://api.onbolder.com/v2/promotions/20"
    }
  }
}