Promotions - Medusa

Overview

The Promotions API enables you to create flexible discount campaigns including percentage discounts, fixed amount discounts, free shipping, and buy X get Y offers. Base Path: /admin/promotions Source: packages/medusa/src/api/admin/promotions/route.ts

List Promotions

Retrieve all promotions with filtering and pagination.

GET /admin/promotions

Query Parameters

fields

string

Comma-separated list of fields to include.

limit

number

default:"15"

Maximum number of promotions to return.

offset

number

default:"0"

Number of promotions to skip.

string

Search query for promotion code or name.

campaign_id

string

Filter by campaign ID.

is_automatic

boolean

Filter by whether promotion is automatically applied.

Request

curl -X GET http://localhost:9000/admin/promotions \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "limit=50"

Response

{
  "promotions": [
    {
      "id": "promo_123",
      "code": "SUMMER20",
      "type": "standard",
      "is_automatic": false,
      "campaign_id": "camp_456",
      "application_method": {
        "id": "promoapp_123",
        "type": "percentage",
        "target_type": "order",
        "allocation": "each",
        "value": 20,
        "max_quantity": null,
        "apply_to_quantity": null,
        "buy_rules_min_quantity": null
      },
      "rules": [
        {
          "id": "rule_123",
          "attribute": "customer_group_id",
          "operator": "in",
          "values": ["cgrp_vip"]
        }
      ],
      "created_at": "2024-03-03T10:00:00.000Z",
      "updated_at": "2024-03-03T10:00:00.000Z"
    }
  ],
  "count": 25,
  "offset": 0,
  "limit": 50
}

promotions

Promotion[]

Array of promotion objects.

type

string

Promotion type: standard or buyget.

is_automatic

boolean

Whether the promotion is automatically applied without a code.

Source: packages/medusa/src/api/admin/promotions/route.ts:13

Create Promotion

Create a new promotion.

POST /admin/promotions

Request Body

code

string

Unique promotion code. Required if is_automatic is false.

type

string

required

Promotion type: standard or buyget.

is_automatic

boolean

default:"false"

Whether to automatically apply the promotion.

campaign_id

string

Associate promotion with a campaign.

application_method

object

required

How the discount is applied.

Show child attributes

type

string

required

Application type:

percentage: Percentage discount
fixed: Fixed amount discount
free_shipping: Free shipping

target_type

string

required

What the discount applies to:

order: Entire order
items: Specific items
shipping_methods: Shipping methods

allocation

string

How to distribute the discount:

each: Apply to each item
across: Distribute across items

value

number

required

Discount value (percentage or amount in cents).

max_quantity

number

Maximum quantity of items the discount applies to.

currency_code

string

Currency for fixed amount discounts.

rules

object[]

Conditions that must be met for the promotion to apply.

Show child attributes

attribute

string

required

The attribute to check (e.g., customer_group_id, product_id, subtotal).

operator

string

required

Comparison operator:

eq: Equals
ne: Not equals
in: In list
gt: Greater than
gte: Greater than or equal
lt: Less than
lte: Less than or equal

values

array

required

Values to compare against.

Request

curl -X POST http://localhost:9000/admin/promotions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME10",
    "type": "standard",
    "is_automatic": false,
    "application_method": {
      "type": "percentage",
      "target_type": "order",
      "allocation": "across",
      "value": 10
    },
    "rules": [
      {
        "attribute": "subtotal",
        "operator": "gte",
        "values": [5000]
      }
    ]
  }'

Response

{
  "promotion": {
    "id": "promo_789",
    "code": "WELCOME10",
    "type": "standard",
    "is_automatic": false,
    "application_method": {
      "type": "percentage",
      "target_type": "order",
      "value": 10
    },
    "rules": [...]
  }
}

Source: packages/medusa/src/api/admin/promotions/route.ts:38

Get Promotion

Retrieve a single promotion by ID.

GET /admin/promotions/{id}

Path Parameters

string

required

The promotion’s ID.

Request

curl -X GET http://localhost:9000/admin/promotions/promo_123 \
  -H "Authorization: Bearer {token}"

Response

{
  "promotion": {
    "id": "promo_123",
    "code": "SUMMER20",
    "application_method": {...},
    "rules": [...]
  }
}

Update Promotion

Update an existing promotion.

POST /admin/promotions/{id}

Path Parameters

string

required

The promotion’s ID.

Request Body

Accepts the same fields as Create Promotion, all optional.

Request

curl -X POST http://localhost:9000/admin/promotions/promo_123 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "is_automatic": true,
    "application_method": {
      "value": 25
    }
  }'

Delete Promotion

Delete a promotion.

DELETE /admin/promotions/{id}

Request

curl -X DELETE http://localhost:9000/admin/promotions/promo_123 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "promo_123",
  "object": "promotion",
  "deleted": true
}

Campaigns

Campaigns group related promotions together.

List Campaigns

Retrieve all campaigns.

GET /admin/campaigns

Source: packages/medusa/src/api/admin/campaigns/route.ts

Create Campaign

Create a new campaign.

POST /admin/campaigns

Request Body

name

string

required

Campaign name.

description

string

Campaign description.

campaign_identifier

string

required

Unique identifier for the campaign.

starts_at

string

Campaign start date.

ends_at

string

Campaign end date.

budget

object

Campaign budget configuration.

Show child attributes

type

string

Budget type: spend or usage.

limit

number

Budget limit.

Add Promotions to Campaign

Associate promotions with a campaign.

POST /admin/campaigns/{id}/promotions

Source: packages/medusa/src/api/admin/campaigns/[id]/promotions/route.ts

Promotion Examples

Percentage Discount

20% off entire order:

{
  "code": "SAVE20",
  "type": "standard",
  "application_method": {
    "type": "percentage",
    "target_type": "order",
    "value": 20
  }
}

Fixed Amount Discount

10 off orders over

50:

{
  "code": "10OFF50",
  "type": "standard",
  "application_method": {
    "type": "fixed",
    "target_type": "order",
    "value": 1000,
    "currency_code": "usd"
  },
  "rules": [
    {
      "attribute": "subtotal",
      "operator": "gte",
      "values": [5000]
    }
  ]
}

Free Shipping

Free shipping for VIP customers:

{
  "code": "FREESHIP",
  "type": "standard",
  "application_method": {
    "type": "free_shipping",
    "target_type": "shipping_methods"
  },
  "rules": [
    {
      "attribute": "customer_group_id",
      "operator": "in",
      "values": ["cgrp_vip"]
    }
  ]
}

Buy X Get Y

Buy 2 items, get 1 free:

{
  "code": "BUY2GET1",
  "type": "buyget",
  "application_method": {
    "type": "percentage",
    "target_type": "items",
    "value": 100,
    "max_quantity": 1,
    "buy_rules_min_quantity": 2
  },
  "rules": [
    {
      "attribute": "product_id",
      "operator": "in",
      "values": ["prod_123"]
    }
  ]
}

Product-Specific Discount

30% off specific products:

{
  "code": "TSHIRT30",
  "type": "standard",
  "application_method": {
    "type": "percentage",
    "target_type": "items",
    "allocation": "each",
    "value": 30
  },
  "rules": [
    {
      "attribute": "product_id",
      "operator": "in",
      "values": ["prod_123", "prod_456"]
    }
  ]
}

Automatic Promotion

Automatic 5% discount for all orders:

{
  "type": "standard",
  "is_automatic": true,
  "application_method": {
    "type": "percentage",
    "target_type": "order",
    "value": 5
  }
}

Getting Started

Admin API

Store API

JavaScript SDK

​Overview

​List Promotions

​Query Parameters

​Request

​Response

​Create Promotion

​Request Body

​Request

​Response

​Get Promotion

​Path Parameters

​Request

​Response

​Update Promotion

​Path Parameters

​Request Body

​Request

​Delete Promotion

​Request

​Response

​Campaigns

​List Campaigns

​Create Campaign

​Request Body

​Add Promotions to Campaign

​Promotion Examples

​Percentage Discount

​Fixed Amount Discount

​Free Shipping

​Buy X Get Y

​Product-Specific Discount

​Automatic Promotion

​Next Steps

Pricing

Orders

Build docs developers (and LLMs) love

Overview

List Promotions

Query Parameters

Request

Response

Create Promotion

Request Body

Request

Response

Get Promotion

Path Parameters

Request

Response

Update Promotion

Path Parameters

Request Body

Request

Delete Promotion

Request

Response

Campaigns

List Campaigns

Create Campaign

Request Body

Add Promotions to Campaign

Promotion Examples

Percentage Discount

Fixed Amount Discount

Free Shipping

Buy X Get Y

Product-Specific Discount

Automatic Promotion

Next Steps