Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Promotions
description: Build percentage and fixed-amount discounts, free shipping, BOGO offers, and coupon codes with Spree's rule and action-based promotion system.
---
## Overview
A promotion is a campaign: a percentage off, free shipping, or free items in the cart. **Rules** decide when it applies, **actions** decide what it does.
A promotion is a *rule that exists on its own*, set up in advance and lasting across many orders. What lands on any one order is a [Discount](/developer/core-concepts/discounts) — the record of money actually coming off. The promotion is the campaign; the discount is what a particular customer got.
```mermaid
erDiagram
Promotion {
string name
string kind
string code
datetime starts_at
datetime expires_at
integer usage_limit
string match_policy
}
PromotionRule {
string type
text preferences
}
PromotionAction {
string type
}
CouponCode {
string code
string state
}
Discount {
string label
string kind
string code
string amount
}
Promotion ||--o{ PromotionRule : "has many"
Promotion ||--o{ PromotionAction : "has many"
Promotion ||--o{ CouponCode : "has many"
PromotionAction ||--o{ Discount : "writes"
Order ||--o{ Discount : "has many"
```
Promotions can be activated in two ways:
- **Automatic promotions** — applied on their own when the rules are met (e.g. free shipping on orders over $50)
- **Coupon code promotions** — applied when a customer enters a valid code during checkout
### When promotions compete
Several promotions can qualify for the same item at once. Spree applies **only the one that saves the customer the most**, and records just that one.
Losing candidates aren't stored or tracked — they're simply reconsidered on every cart change. So a promotion that loses today can win tomorrow, when the basket changes, without any bookkeeping to keep straight.
What an applied promotion leaves behind on the order is a [Discount](/developer/core-concepts/discounts) — a permanent record that survives the promotion being edited or deleted.
## Promotion Attributes
| Attribute | Description | Example |
|-----------|-------------|---------|
| `name` | The name of the promotion | Summer Sale |
| `description` | Brief description (max 255 chars) | 20% off all summer items |
| `kind` | Type: `coupon_code` or `automatic` | `automatic` |
| `starts_at` | When the promotion becomes active | 2026-06-01 00:00:00 |
| `expires_at` | When the promotion expires | 2026-09-01 23:59:59 |
| `usage_limit` | Max times the promotion can be used | 500 |
| `match_policy` | How rules are evaluated: `all` or `any` | `all` |
| `advertise` | Whether to display on storefront | `true` |
### Multi-Code Promotions
For promotions that need unique codes per customer (e.g. influencer campaigns), Spree supports bulk code generation:
| Attribute | Description | Example |
|-----------|-------------|---------|
| `multi_codes` | Enable bulk code generation | `true` |
| `number_of_codes` | How many codes to generate | 1000 |
| `code_prefix` | Prefix for generated codes | `SUMMER` |
Generated codes follow the pattern `{prefix}{random}`, e.g. `SUMMER22A0F62A230BD919`.
## Rules
Rules decide when a promotion is eligible. You can combine multiple rules and configure whether **all** must match or **any** is enough (via `match_policy`).
| Rule | Applies when |
|---|---|
| **FirstOrder** | It's the customer's first order (checked by account and email) |
| **ItemTotal** | The order subtotal, not counting free gifts, is within configured minimum/maximum thresholds |
| **Product** | Specific products are in the order (`any` / `all` / `none` match policy) |
| **Category** | Products from specific categories are in the order — child categories count |
| **OptionValue** | Products with specific option values (size, color) are in the order |
| **User** | The customer is one of the listed accounts |
| **UserLoggedIn** | The customer is logged in |
| **OneUsePerUser** | The customer hasn't used this promotion before |
| **CustomerGroup** | The customer belongs to one of the configured customer groups |
| **Country** | The order ships to a specific country |
| **Currency** | The order is in a specific currency |
| **Channel** | The order was placed through one of the configured [channels](/developer/core-concepts/channels) |
| **Market** | The order belongs to one of the configured [markets](/developer/core-concepts/markets) |
You can also [build your own rules](/developer/how-to/custom-promotion) for business-specific conditions.
## Actions
Actions define what happens when a promotion applies.
### Order discount (`CreateAdjustment`)
A discount on the whole order. The amount is distributed proportionally across the line items — there is no single order-level row, so per-item reporting and partial returns always know their share.
**Default calculator:** `FlatPercentItemTotal` (percentage off the order). Also available: `FlatRate`, `FlexiRate`, `TieredFlatRate`, `TieredPercent`.
**Use case:** "10% off your order", "\$20 off orders over \$100".
### Item discount (`CreateItemAdjustments`)
A discount on individual line items. Only items that match the promotion's rules receive it — if a Category rule says "Electronics", only electronics are discounted.
**Default calculator:** `PercentOnLineItem` (percentage off each item).
**Use case:** "15% off shoes", "Buy 2+ shirts get 10% off each".
### Free shipping (`FreeShipping`)
Writes a discount on each fulfillment covering its delivery cost. The row is kept even when the cost is zero — its presence is what marks the order as having free shipping.
**Use case:** "Free shipping on orders over $75", "Free shipping with code FREESHIP".
### Free items (`CreateLineItems`)
Adds specified products to the cart when the promotion is eligible, checking stock first, and discounts them to zero. A customer who already has the gift in their cart gets theirs free rather than a duplicate; any further copies they bought stay paid for. The gift is taken back when the promotion stops applying.
No second action is needed to make the gift free — pairing this with an order discount set to the gift's price discounts it twice.
A gift the promotion gives away does not count toward what other promotions measure: it cannot lift an order over an `ItemTotal` threshold, and an order discount's percentage is taken from the paid goods only. Nor does it count toward its own promotion's threshold, so in "Spend \$100 get a free sample" the sample is taken back once the paid goods drop to \$100 or less. A copy of the gift the customer pays for counts toward other promotions like any other item, but not toward its own promotion's threshold.
**Use case:** "Free gift with purchase", "Spend $100 get a free sample".
## Managing Promotions
Create and manage promotions via the [Admin API](/api-reference/admin-api/introduction). Rules and actions can be supplied inline on create — each is a `{ type, preferences }` draft using the rule and action types described above:
<CodeGroup>
```typescript Admin SDK
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://store.example.com',
secretKey: 'sk_xxx',
})
// "20% off orders over $100 with code SUMMER20"
const promotion = await client.promotions.create({
name: 'Summer Sale',
code: 'SUMMER20',
kind: 'coupon_code',
rules: [{ type: 'item_total', preferences: { amount_min: 100 } }],
actions: [
{
type: 'create_adjustment',
calculator: { type: 'flat_percent_item_total', preferences: { flat_percent: 20 } },
},
],
})
```
```bash CLI
spree api post /promotions -d '{
"name": "Summer Sale",
"code": "SUMMER20",
"kind": "coupon_code",
"rules": [{ "type": "item_total", "preferences": { "amount_min": 100 } }]
}'
```
</CodeGroup>
You can also add rules and actions to an existing promotion, or update and remove the promotion itself:
<CodeGroup>
```typescript Admin SDK
await client.promotions.rules.create('promo_xxx', {
type: 'first_order',
})
await client.promotions.update('promo_xxx', { expires_at: '2026-09-01T00:00:00Z' })
await client.promotions.delete('promo_xxx')
```
```bash CLI
spree api post /promotions/promo_xxx/promotion_rules -d '{"type": "first_order"}'
spree api patch /promotions/promo_xxx -d '{"expires_at": "2026-09-01T00:00:00Z"}'
```
</CodeGroup>
The available rule and action types — including any custom ones you register — are discoverable at `/api/v3/admin/promotion_rules/types` and `/api/v3/admin/promotion_actions/types`, together with their preference schemas. The dashboard's promotion editor is built on these endpoints, so custom types show up there without any UI work.
<Note>
Deleting a promotion doesn't disturb the orders that used it. Their discount rows stay, keeping the code and value they were created with — only the link back to the promotion is cleared.
</Note>
## Coupon Codes
Coupon codes track promotion usage and can be single-use or multi-use.
- **Single code** — set the `code` attribute on the promotion; `usage_limit` controls how many times it can be redeemed.
- **Multi-code** — bulk-generated codes each track their own state (`unused` / `used`). A code is used up only when an order is placed with it. Applying it to a cart just holds it there, even before the cart qualifies, and only the cart holding a code gets its discount. A shopper who presents a code held by an abandoned cart takes it over, so an unfinished checkout never burns a code. The cart that lost it drops the code and gets a `coupon_code_unavailable` warning on its next Store API request that reads or changes the cart, and placing an order with a code that has been taken is refused rather than charged more than the shopper was shown.
Customers apply codes on the cart via the Store API:
<CodeGroup>
```typescript Store SDK
// Apply a discount code to the cart
const cart = await client.carts.discountCodes.apply('cart_abc123', 'SUMMER20', {
spreeToken: '<token>',
})
// Remove a discount code from the cart
await client.carts.discountCodes.remove('cart_abc123', 'SUMMER20', {
spreeToken: '<token>',
})
```
```bash cURL
# Apply a coupon code
curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_abc123/discount_codes' \
-H 'X-Spree-API-Key: pk_xxx' \
-H 'X-Spree-Token: <token>' \
-H 'Content-Type: application/json' \
-d '{ "code": "SUMMER20" }'
```
</CodeGroup>
The returned cart already carries the updated discounts and totals. If the cart doesn't qualify yet — say the code needs a \$100 minimum and the cart holds \$80 — the code stays on the cart and the discount activates on its own the moment the cart qualifies.
Automatic promotions need no customer action at all — they are evaluated on every cart change.
## Promotion Flow
1. **Cart change** — every change to a cart (item added, address entered, code applied) triggers a recalculation
2. **Eligibility** — each connected promotion is checked: active dates, usage limits, then rules per `match_policy`
3. **Competition** — candidate discounts are computed for every eligible promotion; per item, per fulfillment, and order-wide, the largest saving wins
4. **Persistence** — winning discounts are written as rows; anything stale from the previous pass is removed; tax is then estimated on the discounted amounts
5. **Placement** — once the order is placed, its discount rows are frozen; usage counts are recorded against the promotion
## Related Documentation
- [Discounts](/developer/core-concepts/discounts) — the rows promotions write, and manual discounts
- [Build Custom Promotion Rules & Actions](/developer/how-to/custom-promotion) — step-by-step guide to custom rules, actions and adjusters
- [Calculators](/developer/core-concepts/calculators) — promotion calculators
- [Carts](/developer/core-concepts/carts) — the cart lifecycle promotions act on
- [Admin SDK Resources](/developer/sdk/admin/resources) — the `client.promotions.*` resource-client pattern used above