> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
GET /admin/promotions
```

### Query Parameters

<ParamField query="fields" type="string">
  Comma-separated list of fields to include.
</ParamField>

<ParamField query="limit" type="number" default="15">
  Maximum number of promotions to return.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of promotions to skip.
</ParamField>

<ParamField query="q" type="string">
  Search query for promotion code or name.
</ParamField>

<ParamField query="campaign_id" type="string">
  Filter by campaign ID.
</ParamField>

<ParamField query="is_automatic" type="boolean">
  Filter by whether promotion is automatically applied.
</ParamField>

### Request

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

### Response

```json theme={null}
{
  "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
}
```

<ResponseField name="promotions" type="Promotion[]">
  Array of promotion objects.
</ResponseField>

<ResponseField name="type" type="string">
  Promotion type: `standard` or `buyget`.
</ResponseField>

<ResponseField name="is_automatic" type="boolean">
  Whether the promotion is automatically applied without a code.
</ResponseField>

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

## Create Promotion

Create a new promotion.

```bash theme={null}
POST /admin/promotions
```

### Request Body

<ParamField body="code" type="string">
  Unique promotion code. Required if `is_automatic` is false.
</ParamField>

<ParamField body="type" type="string" required>
  Promotion type: `standard` or `buyget`.
</ParamField>

<ParamField body="is_automatic" type="boolean" default="false">
  Whether to automatically apply the promotion.
</ParamField>

<ParamField body="campaign_id" type="string">
  Associate promotion with a campaign.
</ParamField>

<ParamField body="application_method" type="object" required>
  How the discount is applied.

  <Expandable>
    <ParamField body="type" type="string" required>
      Application type:

      * `percentage`: Percentage discount
      * `fixed`: Fixed amount discount
      * `free_shipping`: Free shipping
    </ParamField>

    <ParamField body="target_type" type="string" required>
      What the discount applies to:

      * `order`: Entire order
      * `items`: Specific items
      * `shipping_methods`: Shipping methods
    </ParamField>

    <ParamField body="allocation" type="string">
      How to distribute the discount:

      * `each`: Apply to each item
      * `across`: Distribute across items
    </ParamField>

    <ParamField body="value" type="number" required>
      Discount value (percentage or amount in cents).
    </ParamField>

    <ParamField body="max_quantity" type="number">
      Maximum quantity of items the discount applies to.
    </ParamField>

    <ParamField body="currency_code" type="string">
      Currency for fixed amount discounts.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="rules" type="object[]">
  Conditions that must be met for the promotion to apply.

  <Expandable>
    <ParamField body="attribute" type="string" required>
      The attribute to check (e.g., `customer_group_id`, `product_id`, `subtotal`).
    </ParamField>

    <ParamField body="operator" type="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
    </ParamField>

    <ParamField body="values" type="array" required>
      Values to compare against.
    </ParamField>
  </Expandable>
</ParamField>

### Request

```bash theme={null}
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

```json theme={null}
{
  "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.

```bash theme={null}
GET /admin/promotions/{id}
```

### Path Parameters

<ParamField path="id" type="string" required>
  The promotion's ID.
</ParamField>

### Request

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

### Response

```json theme={null}
{
  "promotion": {
    "id": "promo_123",
    "code": "SUMMER20",
    "application_method": {...},
    "rules": [...]
  }
}
```

## Update Promotion

Update an existing promotion.

```bash theme={null}
POST /admin/promotions/{id}
```

### Path Parameters

<ParamField path="id" type="string" required>
  The promotion's ID.
</ParamField>

### Request Body

Accepts the same fields as Create Promotion, all optional.

### Request

```bash theme={null}
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.

```bash theme={null}
DELETE /admin/promotions/{id}
```

### Request

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

### Response

```json theme={null}
{
  "id": "promo_123",
  "object": "promotion",
  "deleted": true
}
```

## Campaigns

Campaigns group related promotions together.

### List Campaigns

Retrieve all campaigns.

```bash theme={null}
GET /admin/campaigns
```

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

### Create Campaign

Create a new campaign.

```bash theme={null}
POST /admin/campaigns
```

#### Request Body

<ParamField body="name" type="string" required>
  Campaign name.
</ParamField>

<ParamField body="description" type="string">
  Campaign description.
</ParamField>

<ParamField body="campaign_identifier" type="string" required>
  Unique identifier for the campaign.
</ParamField>

<ParamField body="starts_at" type="string">
  Campaign start date.
</ParamField>

<ParamField body="ends_at" type="string">
  Campaign end date.
</ParamField>

<ParamField body="budget" type="object">
  Campaign budget configuration.

  <Expandable>
    <ParamField body="type" type="string">
      Budget type: `spend` or `usage`.
    </ParamField>

    <ParamField body="limit" type="number">
      Budget limit.
    </ParamField>
  </Expandable>
</ParamField>

### Add Promotions to Campaign

Associate promotions with a campaign.

```bash theme={null}
POST /admin/campaigns/{id}/promotions
```

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

## Promotion Examples

### Percentage Discount

20% off entire order:

```json theme={null}
{
  "code": "SAVE20",
  "type": "standard",
  "application_method": {
    "type": "percentage",
    "target_type": "order",
    "value": 20
  }
}
```

### Fixed Amount Discount

$10 off orders over $50:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "type": "standard",
  "is_automatic": true,
  "application_method": {
    "type": "percentage",
    "target_type": "order",
    "value": 5
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Pricing" icon="dollar-sign" href="/api/admin/pricing">
    Manage product pricing
  </Card>

  <Card title="Orders" icon="shopping-cart" href="/api/admin/orders">
    View promotion usage in orders
  </Card>
</CardGroup>