Promotions

Admin API endpoints for creating and managing promotions, discounts, and campaigns.

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.

q · 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

id · 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

id · 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
  }
}

Next Steps

Pricing

Manage product pricing

Orders

View promotion usage in orders