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

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

```bash theme={null}
GET /admin/price-lists
```

#### 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 price lists to return.
</ParamField>

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

<ParamField query="q" type="string">
  Search query for price list name or description.
</ParamField>

<ParamField query="status" type="string[]">
  Filter by status: `active` or `draft`.
</ParamField>

<ParamField query="type" type="string[]">
  Filter by type: `sale` or `override`.
</ParamField>

#### Request

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

#### Response

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

<ResponseField name="price_lists" type="PriceList[]">
  Array of price list objects.
</ResponseField>

<ResponseField name="type" type="string">
  Price list type:

  * `sale`: Reduces prices during promotions
  * `override`: Replaces default prices for specific groups/regions
</ResponseField>

<ResponseField name="status" type="string">
  Price list status:

  * `active`: Currently in effect
  * `draft`: Not yet active
</ResponseField>

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

### Create Price List

Create a new price list.

```bash theme={null}
POST /admin/price-lists
```

#### Request Body

<ParamField body="title" type="string" required>
  The price list's name.
</ParamField>

<ParamField body="description" type="string">
  Description of the price list.
</ParamField>

<ParamField body="type" type="string" required>
  Price list type: `sale` or `override`.
</ParamField>

<ParamField body="status" type="string" default="draft">
  Status: `active` or `draft`.
</ParamField>

<ParamField body="starts_at" type="string">
  ISO 8601 datetime when the price list becomes active.
</ParamField>

<ParamField body="ends_at" type="string">
  ISO 8601 datetime when the price list expires.
</ParamField>

<ParamField body="rules" type="object[]">
  Rules that determine when this price list applies.

  <Expandable>
    <ParamField body="rule_type" type="string" required>
      Type of rule: `customer_group_id`, `region_id`, etc.
    </ParamField>

    <ParamField body="value" type="string" required>
      The value to match (e.g., customer group ID).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="prices" type="object[]">
  Price overrides for variants.

  <Expandable>
    <ParamField body="variant_id" type="string" required>
      Product variant ID.
    </ParamField>

    <ParamField body="currency_code" type="string" required>
      Currency code (e.g., "usd").
    </ParamField>

    <ParamField body="amount" type="number" required>
      Price amount in cents.
    </ParamField>

    <ParamField body="min_quantity" type="number">
      Minimum quantity for this price to apply.
    </ParamField>

    <ParamField body="max_quantity" type="number">
      Maximum quantity for this price to apply.
    </ParamField>
  </Expandable>
</ParamField>

#### Request

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

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

```bash theme={null}
GET /admin/price-lists/{id}
```

#### Path Parameters

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

### Update Price List

Update a price list.

```bash theme={null}
POST /admin/price-lists/{id}
```

#### Request Body

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

#### Request

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

```bash theme={null}
DELETE /admin/price-lists/{id}
```

#### Request

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

#### Response

```json theme={null}
{
  "id": "pl_123",
  "object": "price-list",
  "deleted": true
}
```

## Price List Prices

### Add Prices to Price List

Add variant prices to an existing price list.

```bash theme={null}
POST /admin/price-lists/{id}/prices/batch
```

#### Request Body

<ParamField body="create" type="object[]">
  Prices to add.

  <Expandable>
    <ParamField body="variant_id" type="string" required>
      Product variant ID.
    </ParamField>

    <ParamField body="currency_code" type="string" required>
      Currency code.
    </ParamField>

    <ParamField body="amount" type="number" required>
      Price amount in cents.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="update" type="object[]">
  Existing prices to update.

  <Expandable>
    <ParamField body="id" type="string" required>
      Price ID to update.
    </ParamField>

    <ParamField body="amount" type="number">
      New price amount.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="delete" type="string[]">
  Array of price IDs to remove.
</ParamField>

### Remove Prices from Price List

Remove specific prices from a price list.

```bash theme={null}
DELETE /admin/price-lists/{id}/prices/{price_id}
```

## Price Preferences

### List Price Preferences

Retrieve pricing preferences configuration.

```bash theme={null}
GET /admin/price-preferences
```

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

### Update Price Preferences

Configure global pricing preferences.

```bash theme={null}
POST /admin/price-preferences
```

## Variant Pricing

### Update Variant Prices

Update prices for a specific product variant.

```bash theme={null}
POST /admin/products/{id}/variants/{variant_id}/prices
```

#### Request Body

<ParamField body="prices" type="object[]" required>
  Array of prices to set.

  <Expandable>
    <ParamField body="currency_code" type="string" required>
      Currency code (e.g., "usd", "eur").
    </ParamField>

    <ParamField body="amount" type="number" required>
      Price amount in smallest currency unit (cents).
    </ParamField>

    <ParamField body="min_quantity" type="number">
      Minimum order quantity for this price.
    </ParamField>

    <ParamField body="max_quantity" type="number">
      Maximum order quantity for this price.
    </ParamField>

    <ParamField body="rules" type="object">
      Pricing rules (e.g., region-specific pricing).

      <Expandable>
        <ParamField body="region_id" type="string">
          Region ID for region-specific pricing.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

#### Request

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

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

#### Response

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

```bash theme={null}
POST /admin/currencies/{code}
```

#### Request Body

<ParamField body="is_default" type="boolean">
  Set as the default currency.
</ParamField>

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

## Pricing Examples

### Quantity-Based Pricing

Set up volume discounts:

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

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

```json theme={null}
{
  "prices": [
    {
      "currency_code": "usd",
      "amount": 2999,
      "rules": {
        "region_id": "reg_us"
      }
    },
    {
      "currency_code": "eur",
      "amount": 2799,
      "rules": {
        "region_id": "reg_eu"
      }
    }
  ]
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Products" icon="box" href="/api/admin/products">
    Manage product pricing
  </Card>

  <Card title="Promotions" icon="tag" href="/api/admin/promotions">
    Create promotional discounts
  </Card>
</CardGroup>