> For the complete documentation index, see [llms.txt](https://help.mimeeq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.mimeeq.com/developers/market-cost-prices.md).

# Market Cost Prices

Cost and RRP per market, product code and quantity.

## List Market Cost Prices

> List market cost prices for your customer. Optionally filter by \`market\` or by \`search\` (a substring over the full code \`market|code|quantity\`). Results are cursor-paginated. At most 10000 records can be paged through. \`page.totalRecords\` is how many your customer actually has (ignoring filters); when that exceeds what you can page through, \`page.truncated\` is \`true\` and reaching \`nextCursor: null\` still leaves records unseen. Only \`search\` reaches them — it is applied before the cap, while \`market\` filters the records already returned.\
> \
> Requires the \`marketCostPrices:read\` scope.

```json
{"openapi":"3.1.0","info":{"title":"Mimeeq External API","version":"1.0.0"},"tags":[{"name":"Market Cost Prices","description":"Cost and RRP per market, product code and quantity."}],"servers":[{"url":"https://admin.mimeeqapi.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key sent as a bearer token (mk_live_… / mk_test_…)."}},"schemas":{"MarketCostPricesList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"marketCostPriceId":{"type":"string","pattern":"^MCP-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"Market cost price identifier (MCP-<uuid>)."},"market":{"anyOf":[{"type":"string"},{"type":"null"}]},"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"quantity":{"anyOf":[{"type":"number"},{"type":"null"}]},"cost":{"anyOf":[{"type":"number","minimum":0,"description":"Cost price in the market currency."},{"type":"null"}]},"rrp":{"anyOf":[{"type":"number","minimum":0,"description":"Recommended retail price in the market currency."},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Currency symbol derived from the market."},"createdAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 creation timestamp."},"modifiedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 last-modified timestamp."}},"required":["marketCostPriceId","market","code","quantity","cost","rrp","currency","createdAt","modifiedAt"],"additionalProperties":false}},"page":{"type":"object","properties":{"limit":{"type":"number"},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor for the next page, or null on the last page."},"truncated":{"type":"boolean","description":"True when this query matched at least as many records as the API can return in one go, so records matching it may exist beyond the last page and paging to `nextCursor: null` would not reach them. Narrow the result set with `search` to bring them into range."},"totalRecords":{"type":"number","description":"Total market cost prices stored for your customer. Always the stored total, unaffected by `search` and `market`, so it is not the size of a filtered result set."}},"required":["limit","nextCursor","truncated","totalRecords"],"additionalProperties":false}},"required":["data","page"],"additionalProperties":false},"PublicError":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"details":{"description":"Optional error-specific details (e.g. per-field validation reasons)."}}}}},"paths":{"/v1/market-cost-prices":{"get":{"summary":"List Market Cost Prices","tags":["Market Cost Prices"],"description":"List market cost prices for your customer. Optionally filter by `market` or by `search` (a substring over the full code `market|code|quantity`). Results are cursor-paginated. At most 10000 records can be paged through. `page.totalRecords` is how many your customer actually has (ignoring filters); when that exceeds what you can page through, `page.truncated` is `true` and reaching `nextCursor: null` still leaves records unseen. Only `search` reaches them — it is applied before the cap, while `market` filters the records already returned.\n\nRequires the `marketCostPrices:read` scope.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketCostPricesList"}}}},"400":{"description":"Invalid request data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"403":{"description":"The API key lacks the required scope (`scope_denied`), or the operation is not permitted for this account (`operation_not_permitted`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"description":"Page size (1–5000, default 50).","type":"integer","minimum":1,"maximum":5000}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"description":"Pagination cursor returned as page.nextCursor."}},{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":1,"description":"Substring match over the full code (market|code|quantity)."}},{"name":"market","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Filter to a single market (case-insensitive)."}}]}}}}
```

## Create Market Cost Price

> Create a single market cost price. The \`market\` must be one of your configured markets (\`400 market\_not\_configured\` otherwise). Returns 409 if the market/code/quantity combination already exists.\
> \
> Requires the \`marketCostPrices:write\` scope.

```json
{"openapi":"3.1.0","info":{"title":"Mimeeq External API","version":"1.0.0"},"tags":[{"name":"Market Cost Prices","description":"Cost and RRP per market, product code and quantity."}],"servers":[{"url":"https://admin.mimeeqapi.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key sent as a bearer token (mk_live_… / mk_test_…)."}},"schemas":{"MarketCostPricesMutation":{"type":"object","properties":{"data":{"type":"object","properties":{"marketCostPriceId":{"type":"string","pattern":"^MCP-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"Market cost price identifier (MCP-<uuid>)."}},"required":["marketCostPriceId"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"PublicError":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"details":{"description":"Optional error-specific details (e.g. per-field validation reasons)."}}},"MarketCostPricesCreateRequest":{"type":"object","properties":{"market":{"type":"string","minLength":1,"maxLength":255,"description":"Market the price applies to, as configured for the customer."},"code":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[./\\\\_\\-\\w]+$","description":"Product/variant code."},"quantity":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Quantity tier the price applies to (integer ≥ 0)."},"cost":{"type":"number","minimum":0,"description":"Cost price in the market currency."},"rrp":{"type":"number","minimum":0,"description":"Recommended retail price in the market currency."}},"required":["market","code","quantity","cost"],"additionalProperties":false}}},"paths":{"/v1/market-cost-prices":{"post":{"summary":"Create Market Cost Price","tags":["Market Cost Prices"],"description":"Create a single market cost price. The `market` must be one of your configured markets (`400 market_not_configured` otherwise). Returns 409 if the market/code/quantity combination already exists.\n\nRequires the `marketCostPrices:write` scope.","responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketCostPricesMutation"}}}},"400":{"description":"Invalid request data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"403":{"description":"The API key lacks the required scope (`scope_denied`), or the operation is not permitted for this account (`operation_not_permitted`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"409":{"description":"Conflict with the current state (e.g. the resource already exists).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketCostPricesCreateRequest"}}}}}}}}
```

## Bulk upsert Market Cost Prices

> Create or upsert market cost prices in bulk (1–5000). With \`mode: UPSERT\` existing full codes are updated (counted under \`updated\`); the market must be configured for the customer, or the row is reported in \`invalidCodes\`. Currency is not accepted — it is derived from the market. Each item is a full replacement: omitting \`rrp\` clears any stored RRP.\
> \
> Requires the \`marketCostPrices:write\` scope.

```json
{"openapi":"3.1.0","info":{"title":"Mimeeq External API","version":"1.0.0"},"tags":[{"name":"Market Cost Prices","description":"Cost and RRP per market, product code and quantity."}],"servers":[{"url":"https://admin.mimeeqapi.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key sent as a bearer token (mk_live_… / mk_test_…)."}},"schemas":{"MarketCostPricesBulkResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"existingCount":{"type":"number","description":"Records already stored for the customer before the import."},"added":{"type":"number"},"updated":{"type":"number","description":"Existing rows re-written (UPSERT). Currently includes rows re-sent unchanged."},"unchanged":{"type":"number","description":"Existing rows re-sent with no change. Reserved: currently always 0 (such rows are counted under `updated`) until server-side change detection ships."},"processed":{"type":"number"},"invalidCodes":{"type":"array","items":{"type":"string"},"description":"Full codes rejected by validation."},"skippedCodes":{"type":"array","items":{"type":"string"},"description":"Full codes skipped because they already exist (CREATE mode; UPSERT updates them)."}},"required":["existingCount","added","updated","unchanged","processed","invalidCodes","skippedCodes"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"PublicError":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"details":{"description":"Optional error-specific details (e.g. per-field validation reasons)."}}},"MarketCostPricesBulkRequest":{"type":"object","properties":{"mode":{"default":"CREATE","description":"CREATE adds only (existing full codes are skipped); UPSERT updates them.","type":"string","enum":["CREATE","UPSERT"]},"items":{"minItems":1,"maxItems":5000,"type":"array","items":{"type":"object","properties":{"market":{"type":"string","minLength":1,"maxLength":255,"description":"Market the price applies to, as configured for the customer."},"code":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[./\\\\_\\-\\w]+$","description":"Product/variant code."},"quantity":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Quantity tier the price applies to (integer ≥ 0)."},"cost":{"type":"number","minimum":0,"description":"Cost price in the market currency."},"rrp":{"type":"number","minimum":0,"description":"Recommended retail price in the market currency."}},"required":["market","code","quantity","cost"],"additionalProperties":false},"description":"1–5000 items."}},"required":["items"],"additionalProperties":false}}},"paths":{"/v1/market-cost-prices:bulk":{"post":{"summary":"Bulk upsert Market Cost Prices","tags":["Market Cost Prices"],"description":"Create or upsert market cost prices in bulk (1–5000). With `mode: UPSERT` existing full codes are updated (counted under `updated`); the market must be configured for the customer, or the row is reported in `invalidCodes`. Currency is not accepted — it is derived from the market. Each item is a full replacement: omitting `rrp` clears any stored RRP.\n\nRequires the `marketCostPrices:write` scope.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketCostPricesBulkResponse"}}}},"400":{"description":"Invalid request data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"403":{"description":"The API key lacks the required scope (`scope_denied`), or the operation is not permitted for this account (`operation_not_permitted`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"409":{"description":"Conflict with the current state (e.g. the resource already exists).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketCostPricesBulkRequest"}}}}}}}}
```

## Update Market Cost Price

> Replace a market cost price by id with the supplied fields. This is a full replacement — omitting \`rrp\` clears any stored RRP. The \`market\` must be one of your configured markets (\`400 market\_not\_configured\` otherwise). Currency is derived from the market. Returns 404 if the id does not exist.\
> \
> Requires the \`marketCostPrices:write\` scope.

```json
{"openapi":"3.1.0","info":{"title":"Mimeeq External API","version":"1.0.0"},"tags":[{"name":"Market Cost Prices","description":"Cost and RRP per market, product code and quantity."}],"servers":[{"url":"https://admin.mimeeqapi.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key sent as a bearer token (mk_live_… / mk_test_…)."}},"schemas":{"MarketCostPricesMutation":{"type":"object","properties":{"data":{"type":"object","properties":{"marketCostPriceId":{"type":"string","pattern":"^MCP-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"Market cost price identifier (MCP-<uuid>)."}},"required":["marketCostPriceId"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"PublicError":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"details":{"description":"Optional error-specific details (e.g. per-field validation reasons)."}}},"MarketCostPricesCreateRequest":{"type":"object","properties":{"market":{"type":"string","minLength":1,"maxLength":255,"description":"Market the price applies to, as configured for the customer."},"code":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[./\\\\_\\-\\w]+$","description":"Product/variant code."},"quantity":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Quantity tier the price applies to (integer ≥ 0)."},"cost":{"type":"number","minimum":0,"description":"Cost price in the market currency."},"rrp":{"type":"number","minimum":0,"description":"Recommended retail price in the market currency."}},"required":["market","code","quantity","cost"],"additionalProperties":false}}},"paths":{"/v1/market-cost-prices/{marketCostPriceId}":{"put":{"summary":"Update Market Cost Price","tags":["Market Cost Prices"],"description":"Replace a market cost price by id with the supplied fields. This is a full replacement — omitting `rrp` clears any stored RRP. The `market` must be one of your configured markets (`400 market_not_configured` otherwise). Currency is derived from the market. Returns 404 if the id does not exist.\n\nRequires the `marketCostPrices:write` scope.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketCostPricesMutation"}}}},"400":{"description":"Invalid request data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"403":{"description":"The API key lacks the required scope (`scope_denied`), or the operation is not permitted for this account (`operation_not_permitted`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"404":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicError"}}}}},"parameters":[{"name":"marketCostPriceId","in":"path","required":true,"schema":{"type":"string","pattern":"^MCP-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"Market cost price identifier (MCP-<uuid>)."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketCostPricesCreateRequest"}}}}}}}}
```


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.mimeeq.com/developers/market-cost-prices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.