Create a promotion

Creates a new promotion. code is required for single-code coupon promotions; pass multi_codes: true with number_of_codes to auto-generate a batch.

Rules and actions can be created in the same request by passing arrays of { type, preferences, ... } rows. The server reconciles to the desired set: new rows are built, existing rows (by id) are updated, omitted rows are removed.

Required scope: write_promotions (for API-key authentication).

POST

api

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' },
  ],
})

spree api post /promotions -d '{"name":"Black Friday","code":"BLACKFRIDAY","starts_at":"2026-11-29T00:00:00Z","expires_at":"2026-12-01T00:00:00Z"}'

{
  "id": "promo_gbHJdmfrXB",
  "name": "Black Friday",
  "description": null,
  "code": "blackfriday-os",
  "starts_at": "2026-07-26T14:25:46.152Z",
  "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-07-26T14:25:46.152Z",
  "updated_at": "2026-07-26T14:25:46.179Z",
  "action_ids": [
    "pact_UkLWZg9DAJ",
    "pact_gbHJdmfrXB"
  ],
  "rule_ids": [
    "prorule_UkLWZg9DAJ",
    "prorule_gbHJdmfrXB",
    "prorule_EfhxLZ9ck8"
  ]
}

{
  "error": {
    "code": "validation_error",
    "message": "Name can't be blank and Code can't be blank",
    "details": {
      "name": [
        "can't be blank"
      ],
      "code": [
        "can't be blank"
      ]
    }
  }
}

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[]

Show child attributes

actions

object[]

Show child attributes

Response

promotion created with rules and actions

List promotions

Show a promotion

⌘I

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' },
  ],
})

spree api post /promotions -d '{"name":"Black Friday","code":"BLACKFRIDAY","starts_at":"2026-11-29T00:00:00Z","expires_at":"2026-12-01T00:00:00Z"}'

{
  "id": "promo_gbHJdmfrXB",
  "name": "Black Friday",
  "description": null,
  "code": "blackfriday-os",
  "starts_at": "2026-07-26T14:25:46.152Z",
  "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-07-26T14:25:46.152Z",
  "updated_at": "2026-07-26T14:25:46.179Z",
  "action_ids": [
    "pact_UkLWZg9DAJ",
    "pact_gbHJdmfrXB"
  ],
  "rule_ids": [
    "prorule_UkLWZg9DAJ",
    "prorule_gbHJdmfrXB",
    "prorule_EfhxLZ9ck8"
  ]
}

{
  "error": {
    "code": "validation_error",
    "message": "Name can't be blank and Code can't be blank",
    "details": {
      "name": [
        "can't be blank"
      ],
      "code": [
        "can't be blank"
      ]
    }
  }
}

API basics

Endpoints

Create a promotion

Authorizations

Headers

Body

Response