--- title: Price List endpoints slug: price-list-endpoints description: "Discover comprehensive instructions on utilizing the PriceMoov API for seamless management of price lists. This guide offers an extensive list of API endpoints and methods for creating price lists, adding products, performing product extensions, and upda icon: 💵 docTags: createdAt: 2023-07-05T09:47:36.121Z --- # Quick reference | Verb | Path | Method | | ---- | ------------------------------------ | ------------------------------------------------------------------ | | POST | /api/v1/price\_list/bulk\_create/ | Create Price Lists | | POST | /api/v1/prices/bulk\_add\_products/ | Add products to a Price List | | POST | /api/v1/prices/bulk\_update\_prices/ | Update prices in a Price List | | POST | /api/v1/prices/get\_prices/ | Read prices in a Price List | | POST | /api/v1/prices/sync\_with\_catalog/ | Sync a Price List with the catalog, based on its product\_filters | # Create Price Lists ## Description Price Lists can be created via this API, in bulk. ## Parameters ::::VerticalSplit{layout="left"} :::VerticalSplitItem name description valid\_from valid\_to price\_dimensions margin\_formula product\_filters is\_calendar ::: :::VerticalSplitItem `type: string`, `Required` The name of the price list `type: string`, `default: unknown`, `Optional` The description of the price list `type: date yyyy-mm-dd`, `Required` Start date of price list's validity period `type: date yyyy-mm-dd`, `Required` End date of price list's validity period `type: [strings]`, `default: ["price"]`, `Optional` List of price column names `type: string`, `default: see below`, `Optional` Formula to compute the margin in the price list Its **default value** depends on cost columns: *"= (Price - \{Sum of Costs}}) / Price \* 100"* e.g. if we have 2 cost columns with letters J and G: * "= (Price - (J + G)) / Price \* 100"* `type: dict`, `default: {}`, `Optional` Filter on catalog products e.g. if we only want to allow certain categories and cities : *\{"category": \["Kids", "Teens"], "city": \["Paris", "Berlin"]}* The default value *\{} *means we allow all products `type: bool`, `default: False`, `Optional` Flag to know if price list should be calendar. If True; price list will have a horizon of 365 days ::: :::: ## Example ```shell curl --location --request POST 'https://api.pricemoov.com/api/v1/price_list/bulk_create/' \ --header 'Authorization: jwt ' \ --header 'Content-Type: application/json' \ --data-raw '[ { "name": "PL_0001", "description": "Prices for Amazon", "valid_from": "2023-03-10", "valid_to": "2024-03-09", "price_dimensions": ["Unit Price","1 000 units","10 000 units"], "margin_formula": "= (Price - (J) / Price * 100", "product_filters": {"category": ["Kids"], "model": ["Cap"]}, "is_calendar": true, }, ... ] ' ``` Upon success, the response is 201 OK and returns ```json [{"id": 1, "name": "PL_0001"}, ...] ``` # Add products to a Price List ## Description Once a price list has been added, or already exists, we can add products to it. Their price will be set to 0. Notes: - the products will be first added to the price list draft, then the price list will be published - this endpoint only works with price lists that were created through the above API. It does not support the price lists created through the UI ## Parameters ::::VerticalSplit{layout="left"} :::VerticalSplitItem price\_list\_name code \{extensions if any} ::: :::VerticalSplitItem `type: string`, `Required` The name of the price list `type: string`, `Required` Product code `type: Any`, `Required` Product extensions For instance if have defined 2 extensions in our catalog, *agencies* (string) and *size* (integer), we have to mention them in our payload. See example below ::: :::: ## Example ```shell curl --location --request POST 'https://api.pricemoov.com/api/v1/prices/bulk_add_products/' \ --header 'Authorization: jwt ' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "PL_0001", "payload": [ { "code": "something_really_unique", "agencies": "00_01", "size": 1 }, { "code": "something_actually_unique", "agencies": "00_02", "size": 10 }, ... ] }' ``` Upon success, the response is 201 OK and returns either the ids of the rows added to the Price List, **or** **job infos**. Indeed, if you add a lot of products (> 100), we launch an async job and the products will be added in the background: ```json [1, 2, ...] or { "status": "progress", "resource_type": "published-price-list", "progress": {"total": 110, "finished": 100, "error": 0}, } ``` # Update prices in a Price List ## Description Once products have been added to a Price List, or already were, we can update their prices. Notes: - the prices will be directly updated / set in the published version. Here, we do not alter the draft - this endpoint only works with price lists that were created through the above API. It does not support the price lists created through the UI ## Parameters ::::VerticalSplit{layout="left"} :::VerticalSplitItem price\_list\_name code \{extensions if any} price price\_dimension date ::: :::VerticalSplitItem `type: string`, `Required` The name of the price list `type: string`, `Required` Product code `type: Any`, `Required` Product extensions (see above endpoint) `type: float`, `Required` Price to set `type: string`, `Required | Optional` Price dimension for which we set the new price Required if Price List is multidimensional (e.g. \["p1, "p2"] ) `type: yyyy-mm-dd date`, `Required | Optional` Date for which we set the new price Required if Price List is calendar ::: :::: ## Example ```shell curl --location --request POST 'https://api.pricemoov.com/api/v1/prices/bulk_update_prices/' \ --header 'Authorization: jwt ' \ --header 'Content-Type: application/json' \ --data-raw '{ "price_list_name": "PL_0001", "payload": [ { "code": "something_really_unique", "agencies": "00_01", "size": 1, "price": 10.23, "price_dimension": "Unit Price" "date": "2023-01-30" }, { "code": "something_actually_unique", "agencies": "00_02", "size": 10, "price": 91.23, "price_dimension": "1 000 units" "date": "2023-12-01" }, ... ] }' ``` Upon success, the response is 201 OK and returns the ids of the updated rows : ```json [1, 2, ...] ``` # Update dynamic attributes in a Price List ## Description Use this endpoint to update dynamic attribute values for specific products in a price list ## Parameters ::::VerticalSplit{layout="left"} :::VerticalSplitItem price\_list\_name price\_list\_id code \{extensions if any} dynamic\_attribute\_value dynamic\_attribute\_name ::: :::VerticalSplitItem `type: string`, `Required (if price_list_id not provided)` The name of the price list `type: number`, `Required (if price_list_name not provided)` The id of the price list `type: string`, `Required` Product code `type: Any`, `Required` Product extensions (see above endpoint) `type: Any`, `Required` Value to set `type: string`, `Required` Name of the dynamic attribute to update. ::: :::: ## Example ```shell curl --location --request POST 'https://api.pricemoov.com/api/v1/prices/bulk_update_dynamic_attributes/' \ --header 'Authorization: jwt ' \ --header 'Content-Type: application/json' \ --data-raw '{ "price_list_id": 364, "payload": [ { "code": "SKU-000006", "color": "red", "dynamic_attribute_name": "markup", "dynamic_attribute_value": 555.1 }, { "code": "SKU-000006", "color": "green", "dynamic_attribute_name": "markup", "dynamic_attribute_value": 350 }, ... ] }' ``` Upon success, the response is 201 OK and returns the ids of the updated rows : ```json [1, 2, ...] ``` # Read prices in a Price List ## Description This endpoint lets you read prices in a Price List. Notes: - this endpoint works only with price lists that are published ## Parameters ::::VerticalSplit{layout="left"} :::VerticalSplitItem price\_list\_name price\_list\_id promotion\_date code \{attributes if any} \{extensions if any} price\_dimension date promotion ::: :::VerticalSplitItem `type: string`, `Required (if price_list_id not provided)` The name of the price list `type: number`, `Required (if price_list_name not provided)` The id of the price list `type: yyyy-mm-dd date`, `Optional`, `default: today` Date on which we'll be looking for active promotions `type: string`, `Optional` Product code Absent code will be treated as a wildcard `type: Any`, `Optional` Product attributes. Only used if code is not mentionned `type: Any`, `Optional` Product extensions. Here, absent extensions will be treated as wildcards `type: string`, `Required | Optional` Price dimension for which we want to read the price Required if Price List is multidimensional (e.g. \["p1, "p2"] ) `type: yyyy-mm-dd date`, `Required | Optional` Date for which which we want to read the price Required if Price List is calendar `type: string`, `Optional` Specific promotion to look for If no promotion is mentionned, all promotions that are valid on promotion\_date will be computed ::: :::: ## Example ```shell curl --location --request POST 'https://api.pricemoov.com/api/v1/prices/get_prices/' \ --header 'Authorization: jwt ' \ --header 'Content-Type: application/json' \ --data-raw '{ "price_list_name": "PL_0001", "promotion_date": "2023-01-30", "payload": [ { "code": "something_really_unique", "agencies": "00_01", "size": 1, "price_dimension": "Unit Price", "date": "2023-01-30", "promotion": "BLACKFRIDAY" }, { "code": "something_actually_unique", "agencies": "00_02", "size": 10, "price_dimension": "1 000 units", "date": "2023-12-01" }, ... ] }' ``` Upon success, the response is 201 OK and returns the payload rows, enriched with the active price and other potentially useful metadata : ```json [ { "code": "something_really_unique", "agencies": "00_01", "size": 1, "price_dimension": "Unit Price", "date": "2023-01-30", "price_list_name": "PL_0001", "price_list_id": 1, "extended_catalog_id": 1, "pk": 1, "active_price": 10.23, "promotions": [ {"name": "BLACKFRIDAY", "value": 9.50} ] }, { "code": "something_actually_unique", "agencies": "00_02", "size": 10, "price_dimension": "1 000 units", "date": "2023-12-01", "price_list_name": "PL_0001", "price_list_id": 1, "extended_catalog_id": 2, "pk": 2, "active_price": 91.23, "promotions": [ {"name": "BLACKFRIDAY", "value": 80.00}, {"name": "SUMMERSALES", "value": 85.00} ] }, ... ] ``` ## Example with wildcards Let's say we don't mention *agencies* in the payload below: ```shell curl --location --request POST 'https://api.pricemoov.com/api/v1/prices/get_prices/' \ --header 'Authorization: jwt ' \ --header 'Content-Type: application/json' \ --data-raw '{ "price_list_name": "PL_0001", "payload": [ { "code": "something_really_unique", "size": 1, "price_dimension": "Unit Price" "date": "2023-01-30" } ] }' ``` We then get the prices for the *code*, *size*, *price\_dimension* and *date *specified in the payload, **exploded to every *****agencies*** in the data ("00\_01", "00\_02*", ...*) : ```json [ { "code": "something_really_unique", "agencies": "00_01", "size": 1, "price_dimension": "Unit Price", "date": "2023-01-30", "price_list_name": "PL_0001", "price_list_id": 1, "extended_catalog_id": 1, "pk": 1, "active_price": 10.23, "promotions": [ {"name": "BLACKFRIDAY", "value": 9.50}, {"name": "SUMMERSALES", "value": 10.00} ] }, { "code": "something_really_unique", "agencies": "00_02", "size": 1, "price_dimension": "Unit Price", "date": "2023-01-30", "price_list_name": "PL_0001", "price_list_id": 1, "extended_catalog_id": 3, "pk": 3, "active_price": 109.09, "promotions": [ {"name": "BLACKFRIDAY", "value": 80.00}, {"name": "SUMMERSALES", "value": 85.00} ] }, ... ] ``` Remark: - you can remove as many extensions as you like from the payload - you can even remove the product code - you can also use attributes without the product code # Sync a Price List with the catalog, based on its product\_filters ## Description Once a price list has been added, or already exists, you can synchronise its content with the current catalog products, based on product\_filters. For instance, if you created the Price List with `product_filters = {"category": ["Kids", "Teens"], "city": ["Paris", "Berlin"]}` , and you execute the following three updates on the catalog, then this is what would happen if you call our sync endpoint: | **catalog update** | pk | code | category | city | **already in Price List ?** | **filtered in ?** | **consequence:** | | ---------------------------------------------- | -- | ------ | -------- | ------ | --------------------------- | ----------------- | ----------------------------------- | | **Nothing** | 1 | AZERTY | Kids | Paris | **Yes** | **Yes** | **Nothing: keep in Price List** | | **Changed "category" from "Kids" to "Adults"** | 2 | UIOP | Adults | Paris | **Yes** | **No** | **Remove from Price List** | | **Added the row** | 3 | QSDFG | Teens | Berlin | **No** | **Yes** | **Add to Price List** | | **Added the row** | 4 | HJKL | Teens | Rome | **No** | **No** | **Nothing: keep out of Price List** | The price of newly added products will be set to 0. Notes: - the products will be first added / removed to the price list draft, then the price list will be published - this endpoint currently only works with price lists that were created through the above API. It does not support the price lists created through the UI ## Parameters ::::VerticalSplit{layout="left"} :::VerticalSplitItem price\_list\_name ::: :::VerticalSplitItem `type: string`, `Required` The name of the price list ::: :::: ```shell curl --location --request POST 'https://api.pricemoov.com/api/v1/prices/sync_with_catalog/' \ --header 'Authorization: jwt ' \ --header 'Content-Type: application/json' \ --data-raw '{ "price_list_name": "PL_0001", }' ``` Upon success, the response is 201 OK and returns either the ids of the added/removed/untouched rows, **or** **job infos**. Indeed, if you add a lot of products (> 100), we launch an async job and the products will be added in the background: ```json { "added": [3], "removed": [2], "untouched": [1] } or { "status": "progress", "resource_type": "published-price-list", "progress": {"total": 110, "finished": 100, "error": 0}, } ```