> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/product-price/extra-product-price.md).

# Extra Product Price

Administrative endpoints for **extra product price** — a per-price-list override price for a product. The primary selling price lives on `product_price` (one record per product); an extra product price adds a price for the same product in a **specific price list** (for example a marketplace-seller list, a B2B tier, or a per-currency list). A product may have many extra prices, but at most one per price list.

### Core Capabilities

**1. Listing & Filtering**

* Retrieve a paginated list of extra product-price records.
* Filter by record identifier (`id`), product (`product`), or price list (`price_list`).
* Order results with the `sort` parameter.

**2. Full CRUD**

* Create an extra price for a product in a price list.
* Retrieve a single record — by its identifier, or by the combined `{price_list_code}-{pk}` form (see **Addressing a Record**).
* Fully or partially update a record.
* Call `DELETE` to have the endpoint acknowledge the request without making any change — the record is **never removed** (see **Deleting an Extra Product Price**).

### Extra Product Price Fields

| Field                 | Type                       | Description                                                                                                                              |
| --------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `pk`                  | integer                    | The unique identifier of the record. Read-only.                                                                                          |
| `product`             | integer                    | The identifier of the priced product. Required on create.                                                                                |
| `price`               | string (decimal)           | The selling price, tax included. A decimal with up to 12 digits and 2 decimal places. Required on create.                                |
| `currency_type`       | string                     | The ISO 4217 currency code (see **Currency Codes** under **Product Price**). Defaults to `try`. Must match the currency of `price_list`. |
| `tax_rate`            | string (decimal)           | The VAT rate applied to `price`, as a percentage. A decimal with up to 5 digits and 2 decimal places. Required on create.                |
| `retail_price`        | string (decimal) or `null` | The original or reference retail price. Optional; `null` when not set.                                                                   |
| `price_list`          | integer                    | The identifier of the price list this price belongs to. Required on create.                                                              |
| `price_list_detailed` | object                     | Read-only expansion of `price_list` — its `pk`, `name`, `code`, and `currency`.                                                          |
| `extra_field`         | object                     | Free-form JSON for extra data. Optional; defaults to an empty object.                                                                    |

A record is unique per `(product, price_list)` pair: creating a second extra price for the same product in the same price list is rejected with a validation error.

### Addressing a Record

A single record can be addressed two ways: by its numeric identifier (`/extra_product_price/{pk}/`) or by the combined form `/extra_product_price/{price_list_code}-{pk}/`, where `{price_list_code}` is the `code` of the record's price list. The combined value is split on its **last** hyphen, so a price-list code that itself contains hyphens is supported.

### Currency Consistency

The `currency_type` of an extra product price must equal the `currency` of its `price_list`. A mismatch is rejected with a `400` validation error on the `currency_type` field. This is enforced on both create and update; on update the effective values fall back to the record's current `price_list`/`currency_type` for any field not supplied.

### Deleting an Extra Product Price

> **Important:** `DELETE /extra_product_price/{id}/` is a **no-op** — the endpoint returns `204 No Content` but the record is **not** modified and **not** removed. An extra price cannot be deleted through the API.

### Filtering & Ordering

| Parameter    | Match                                         |
| ------------ | --------------------------------------------- |
| `id`         | The record by its exact identifier.           |
| `product`    | The related product by identifier (exact).    |
| `price_list` | The related price list by identifier (exact). |

Results can be ordered with the `sort` parameter; prefix a field with a hyphen for descending order.

### Dynamic Settings & Environment Variables

The write endpoints are affected by the following dynamic setting, configured in the management panel. It is referenced again in the description of the operations it affects.

| Key                              | Type                        | Default                                                         | Effect                                                                                                                                                                                                                                                                                                                                                                                               |
| -------------------------------- | --------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GROUPED_PRODUCT_PRICE_SELECTOR` | string (dotted Python path) | `"omnishop.catalogs.selector.group_product_min_price_selector"` | After an extra price is written for a **simple** product that belongs to a grouped product, the grouped product's representative price is recomputed with the selected strategy. Available selectors: `group_product_min_price_selector` (minimum), `group_product_max_price_selector` (maximum), `group_product_sum_price_selector` (sum). Does not affect read operations or non-grouped products. |

**Environment variables:** No environment variables are read directly by these endpoints.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/admin/product-price/extra-product-price.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
