Pricing

Admin API endpoints for managing price lists, price preferences, and product pricing strategies.

Overview

The Pricing API enables sophisticated pricing strategies including price lists, customer group pricing, region-specific pricing, and currency management.

Base Path: /admin/price-lists

Source: packages/medusa/src/api/admin/price-lists/route.ts

Price Lists

Price lists allow you to define custom prices for products based on customer groups, regions, or specific conditions.

List Price Lists

Retrieve all price lists with filtering and pagination.

GET /admin/price-lists

Query Parameters

fields · string

Comma-separated list of fields to include.

limit · number · default: "15"

Maximum number of price lists to return.

offset · number · default: "0"

Number of price lists to skip.

q · string

Search query for price list name or description.

status · string[]

Filter by status: active or draft.

type · string[]

Filter by type: sale or override.

Request

curl -X GET http://localhost:9000/admin/price-lists \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "status=active"

Response

{
  "price_lists": [
    {
      "id": "pl_123",
      "title": "VIP Customer Pricing",
      "description": "Special pricing for VIP customers",
      "type": "override",
      "status": "active",
      "starts_at": "2024-01-01T00:00:00.000Z",
      "ends_at": "2024-12-31T23:59:59.000Z",
      "rules": [
        {
          "rule_type_id": "customer_group_id",
          "value": "cgrp_vip"
        }
      ],
      "prices": [...],
      "created_at": "2024-03-03T10:00:00.000Z",
      "updated_at": "2024-03-03T10:00:00.000Z"
    }
  ],
  "count": 10,
  "offset": 0,
  "limit": 15
}

price_lists · PriceList[]

Array of price list objects.

type · string

Price list type:

• sale: Reduces prices during promotions
• override: Replaces default prices for specific groups/regions

status · string

Price list status:

• active: Currently in effect
• draft: Not yet active

Source: packages/medusa/src/api/admin/price-lists/route.ts:13

Create Price List

Create a new price list.

POST /admin/price-lists

Request Body

title · string · required

The price list’s name.

description · string

Description of the price list.

type · string · required

Price list type: sale or override.

status · string · default: "draft"

Status: active or draft.

starts_at · string

ISO 8601 datetime when the price list becomes active.

ends_at · string

ISO 8601 datetime when the price list expires.

rules · object[]

Rules that determine when this price list applies.

Show child attributes

rule_type · string · required

Type of rule: customer_group_id, region_id, etc.

value · string · required

The value to match (e.g., customer group ID).

prices · object[]

Price overrides for variants.

Show child attributes

variant_id · string · required

Product variant ID.

currency_code · string · required

Currency code (e.g., “usd”).

amount · number · required

Price amount in cents.

min_quantity · number

Minimum quantity for this price to apply.

max_quantity · number

Maximum quantity for this price to apply.

Request

curl -X POST http://localhost:9000/admin/price-lists \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer Sale 2024",
    "description": "20% off summer collection",
    "type": "sale",
    "status": "active",
    "starts_at": "2024-06-01T00:00:00Z",
    "ends_at": "2024-08-31T23:59:59Z",
    "prices": [
      {
        "variant_id": "variant_123",
        "currency_code": "usd",
        "amount": 2399
      }
    ]
  }'

Response

{
  "price_list": {
    "id": "pl_456",
    "title": "Summer Sale 2024",
    "type": "sale",
    "status": "active",
    "starts_at": "2024-06-01T00:00:00.000Z",
    "ends_at": "2024-08-31T23:59:59.000Z",
    "prices": [...]
  }
}

Source: packages/medusa/src/api/admin/price-lists/route.ts:38

Get Price List

Retrieve a single price list by ID.

GET /admin/price-lists/{id}

Path Parameters

id · string · required

The price list’s ID.

Update Price List

Update a price list.

POST /admin/price-lists/{id}

Request Body

Accepts the same fields as Create Price List, all optional.

Request

curl -X POST http://localhost:9000/admin/price-lists/pl_123 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "ends_at": "2024-12-31T23:59:59Z"
  }'

Delete Price List

Delete a price list.

DELETE /admin/price-lists/{id}

Request

curl -X DELETE http://localhost:9000/admin/price-lists/pl_123 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "pl_123",
  "object": "price-list",
  "deleted": true
}

Price List Prices

Add Prices to Price List

Add variant prices to an existing price list.

POST /admin/price-lists/{id}/prices/batch

Request Body

create · object[]

Prices to add.

Show child attributes

variant_id · string · required

Product variant ID.

currency_code · string · required

Currency code.

amount · number · required

Price amount in cents.

update · object[]

Existing prices to update.

Show child attributes

id · string · required

Price ID to update.

amount · number

New price amount.

delete · string[]

Array of price IDs to remove.

Remove Prices from Price List

Remove specific prices from a price list.

DELETE /admin/price-lists/{id}/prices/{price_id}

Price Preferences

List Price Preferences

Retrieve pricing preferences configuration.

GET /admin/price-preferences

Source: packages/medusa/src/api/admin/price-preferences/route.ts

Update Price Preferences

Configure global pricing preferences.

POST /admin/price-preferences

Variant Pricing

Update Variant Prices

Update prices for a specific product variant.

POST /admin/products/{id}/variants/{variant_id}/prices

Request Body

prices · object[] · required

Array of prices to set.

Show child attributes

currency_code · string · required

Currency code (e.g., “usd”, “eur”).

amount · number · required

Price amount in smallest currency unit (cents).

min_quantity · number

Minimum order quantity for this price.

max_quantity · number

Maximum order quantity for this price.

rules · object

Pricing rules (e.g., region-specific pricing).

Show child attributes

region_id · string

Region ID for region-specific pricing.

Request

curl -X POST http://localhost:9000/admin/products/prod_123/variants/variant_456/prices \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "prices": [
      {
        "currency_code": "usd",
        "amount": 2999
      },
      {
        "currency_code": "eur",
        "amount": 2799
      },
      {
        "currency_code": "usd",
        "amount": 2699,
        "min_quantity": 10
      }
    ]
  }'

Currencies

List Currencies

Retrieve available currencies.

GET /admin/currencies

Response

{
  "currencies": [
    {
      "code": "usd",
      "symbol": "$",
      "symbol_native": "$",
      "name": "US Dollar",
      "decimal_digits": 2
    },
    {
      "code": "eur",
      "symbol": "€",
      "symbol_native": "€",
      "name": "Euro",
      "decimal_digits": 2
    }
  ]
}

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

Update Currency

Enable or disable a currency.

POST /admin/currencies/{code}

Request Body

is_default · boolean

Set as the default currency.

Source: packages/medusa/src/api/admin/currencies/[code]/route.ts

Pricing Examples

Quantity-Based Pricing

Set up volume discounts:

{
  "prices": [
    {
      "currency_code": "usd",
      "amount": 1999,
      "min_quantity": 1,
      "max_quantity": 9
    },
    {
      "currency_code": "usd",
      "amount": 1799,
      "min_quantity": 10,
      "max_quantity": 49
    },
    {
      "currency_code": "usd",
      "amount": 1599,
      "min_quantity": 50
    }
  ]
}

Customer Group Pricing

Create a price list for wholesale customers:

{
  "title": "Wholesale Pricing",
  "type": "override",
  "status": "active",
  "rules": [
    {
      "rule_type": "customer_group_id",
      "value": "cgrp_wholesale"
    }
  ],
  "prices": [...]
}

Region-Specific Pricing

Set different prices per region:

{
  "prices": [
    {
      "currency_code": "usd",
      "amount": 2999,
      "rules": {
        "region_id": "reg_us"
      }
    },
    {
      "currency_code": "eur",
      "amount": 2799,
      "rules": {
        "region_id": "reg_eu"
      }
    }
  ]
}

Next Steps

Products

Manage product pricing

Promotions

Create promotional discounts