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

201

Promotion created

422

Validation error

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (JWT)Remember on this deviceInclude my values in samples

Bodyapplication/json

shop_idinteger*ID of the shop (required on create)namestring*statusstringcumulativebooleanWhether this promotion can stack with others. Defaults to `true`.discount_typestring*discountnumber*Discount value — a percentage (0–100) or a fixed amount in cents.activation_modestring*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. codestringCoupon code (required when `activation_mode` is `code`).fulfillment_methodintegerFulfillment method ID (required when `activation_mode` is `fulfillment`).payment_method_idintegerPayment method ID (required when `activation_mode` is `payment`).usage_limitintegerMaximum total redemptions. Unlimited if omitted.per_user_limitintegerMaximum redemptions per customer. Unlimited if omitted.starts_atstringexpires_atstringprice_range_fromintegerMinimum order subtotal in cents for the promotion to apply.price_range_tointegerMaximum order subtotal in cents for the promotion to apply.product_range_fromintegerMinimum number of qualifying products required in the cart.product_range_tointegerMaximum number of qualifying products allowed in the cart.product_discount_group_idintegerID of the group whose products receive the discount.product_discount_group_typestringproduct_discount_group_filter_modestringWhich items within the discount group receive the discount.product_count_group_idintegerGroup used to count qualifying products (for count-gated discounts).product_count_group_typestringprice_list_idintegerRestrict the promotion to orders using this price list.apply_tagstringTag to apply to the order when this promotion is used.

Request

curl -X POST 'https://api.onbolder.com/v2/promotions' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -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",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"shop_id\": 1,\n  \"name\": \"Summer Sale\",\n  \"code\": \"SUMMER20\",\n  \"discount_type\": \"percentage\",\n  \"discount\": 20,\n  \"activation_mode\": \"code\",\n  \"starts_at\": \"2024-06-01T00:00:00Z\",\n  \"expires_at\": \"2024-08-31T23:59:59Z\"\n}"
});

import requests

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

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"
    }
  }
}