Overview The Pricing API enables sophisticated pricing strategies including price lists, customer group pricing, region-specific pricing, and currency management.
Base Path: /admin/price-listsSource: packages/medusa/src/api/admin/price-lists/route.tsPrice 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.
Query Parameters Comma-separated list of fields to include.
Maximum number of price lists to return.
Number of price lists to skip.
Search query for price list name or description.
Filter by status: active or draft.
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 }
Array of price list objects.
Price list type:
sale: Reduces prices during promotionsoverride: Replaces default prices for specific groups/regions Price list status:
active: Currently in effectdraft: Not yet active Source: packages/medusa/src/api/admin/price-lists/route.ts:13Create Price List Create a new price list.
Request Body Description of the price list.
Price list type: sale or override.
ISO 8601 datetime when the price list becomes active.
ISO 8601 datetime when the price list expires.
Rules that determine when this price list applies. Type of rule: customer_group_id, region_id, etc.
The value to match (e.g., customer group ID).
Price overrides for variants. Currency code (e.g., “usd”).
Minimum quantity for this price to apply.
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:38Get Price List Retrieve a single price list by ID.
GET /admin/price-lists/{id}
Path Parameters 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 Existing prices to update. 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.tsUpdate 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 Array of prices to set. Currency code (e.g., “usd”, “eur”).
Price amount in smallest currency unit (cents).
Minimum order quantity for this price.
Maximum order quantity for this price.
Pricing rules (e.g., region-specific pricing). 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.
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.tsUpdate Currency Enable or disable a currency.
POST /admin/currencies/{code}
Request Body Set as the default currency.
Source: packages/medusa/src/api/admin/currencies/[code]/route.tsPricing 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