Skip to main content
POST
/
api
/
v3
/
admin
/
promotions
Spree Admin SDK
import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

// Single coupon code, no rules/actions
const promotion = await client.promotions.create({
  name: 'Black Friday',
  code: 'BLACKFRIDAY',
  starts_at: '2026-11-29T00:00:00Z',
  expires_at: '2026-12-01T00:00:00Z',
})

// One-shot: promotion + rules + actions in a single request
const blackFriday = await client.promotions.create({
  name: 'Black Friday',
  code: 'BLACKFRIDAY',
  kind: 'coupon_code',
  starts_at: '2026-11-29T00:00:00Z',
  expires_at: '2026-12-01T00:00:00Z',
  match_policy: 'all',
  rules: [
    {
      type: 'currency',
      preferences: { currency: 'USD' },
    },
    {
      type: 'item_total',
      preferences: { amount_min: 100, operator_min: 'gte' },
    },
    {
      type: 'product',
      preferences: { match_policy: 'any' },
      product_ids: ['prod_abc123', 'prod_def456'],
    },
  ],
  actions: [
    {
      type: 'create_item_adjustments',
      calculator: {
        type: 'percent_on_line_item',
        preferences: { percent: 25 },
      },
    },
    { type: 'free_shipping' },
  ],
})
{
  "id": "promo_gbHJdmfrXB",
  "name": "Black Friday",
  "description": null,
  "code": "blackfriday-os",
  "starts_at": "2026-06-17T13:37:50.547Z",
  "expires_at": null,
  "usage_limit": null,
  "match_policy": "all",
  "path": null,
  "kind": "coupon_code",
  "multi_codes": false,
  "number_of_codes": null,
  "code_prefix": null,
  "promotion_category_id": null,
  "metadata": {},
  "created_at": "2026-06-17T13:37:50.548Z",
  "updated_at": "2026-06-17T13:37:50.567Z",
  "action_ids": [
    "pact_UkLWZg9DAJ",
    "pact_gbHJdmfrXB"
  ],
  "rule_ids": [
    "prorule_UkLWZg9DAJ",
    "prorule_gbHJdmfrXB",
    "prorule_EfhxLZ9ck8"
  ]
}

Authorizations

​
x-spree-api-key
string
header
required

Secret API key for admin access

​
Authorization
string
header
required

JWT token for admin user authentication

Headers

​
x-spree-api-key
string
required
​
Authorization
string
required

Body

application/json
​
name
string
required
​
code
string | null
​
description
string | null
​
starts_at
string<date-time> | null
​
expires_at
string<date-time> | null
​
usage_limit
integer | null
​
match_policy
enum<string>
Available options:
all,
any
​
kind
enum<string>
Available options:
coupon_code,
automatic
​
multi_codes
boolean
​
number_of_codes
integer | null
​
code_prefix
string | null
​
promotion_category_id
string | null
​
rules
object[]
​
actions
object[]

Response

promotion created with rules and actions