Skip to main content
GET
/
product-values
List product values (pricing)
curl --request GET \
  --url https://api.simcel.io/master/v1/product-values \
  --header 'Authorization: Bearer <token>'
{
  "total": 1240,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "productId": "SKU-001",
      "customerRef": "CUST-FR-001",
      "name": "GrossSalesValue",
      "value": 24.5,
      "startDate": "2025-01-01",
      "endDate": "2025-12-31"
    },
    {
      "productId": "SKU-001",
      "customerRef": "CUST-FR-001",
      "name": "ListedPrice",
      "value": 21,
      "startDate": "2025-01-01",
      "endDate": "2025-12-31"
    }
  ]
}

​
What is a Product Value?

A Product Value is a pricing record that defines what a product is worth for a specific customer, over a specific date range. SIMCEL uses product values to compute revenue KPIs like Gross FIE Sales and Net FIE Sales in simulations. Each record has five key fields:
FieldDescription
productIdThe product this price applies to
customerRefThe customer this price is for
nameThe pricing type (see below)
valueThe price amount in plan currency
startDate / endDateEffective date range

​
Pricing types (name)

ValueDescription
GrossSalesValueGross selling price per unit (carton) to the customer
GrossSalesValuePerKgGSV expressed per kilogram
ListedPriceThe official listed/catalogue price before trade deductions
ListedPricePerKgListed price per kilogram
The simulation engine uses GrossSalesValue as the primary revenue driver. ListedPrice is used to compute trade expense deductions.

​
Query pricing for a product

resp = requests.get(
    "https://api.simcel.io/master/v1/product-values",
    headers={"Authorization": f"Bearer {token}"},
    params={
        "workspaceId": "ws_abc123",
        "productId": "SKU-001",
        "name": "GrossSalesValue",
        "asOf": "2025-06-01",   # only prices valid on this date
    }
)

for record in resp.json()["data"]:
    print(f"{record['customerRef']}: €{record['value']:.2f} "
          f"({record['startDate']} → {record['endDate']})")

​
Override pricing for a planning cycle

Use POST /product-values to inject a price override for a specific plan. This is the programmatic equivalent of a price event in SIMCEL — useful for automating annual price list updates or testing pricing scenarios. 
# Apply a 5% price increase for a customer from July 2025
current_price = 24.50

resp = requests.post(
    "https://api.simcel.io/master/v1/product-values",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    },
    json={
        "workspaceId": "ws_abc123",
        "planId": "plan_9xKz2",
        "productId": "SKU-001",
        "customerRef": "CUST-FR-001",
        "name": "GrossSalesValue",
        "value": round(current_price * 1.05, 2),
        "startDate": "2025-07-01",
        "endDate": "2025-12-31",
    }
)
print(resp.json())
# { "success": true, "overrideId": "ovr_pv_abc", "appliedAt": "..." }

​
Bulk pricing update pattern

price_updates = [
    {"customerRef": "CUST-FR-001", "productId": "SKU-001", "value": 25.70},
    {"customerRef": "CUST-FR-001", "productId": "SKU-002", "value": 18.40},
    {"customerRef": "CUST-UK-005", "productId": "SKU-001", "value": 22.00},
]

results = []
for update in price_updates:
    resp = requests.post(
        "https://api.simcel.io/master/v1/product-values",
        headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
        json={
            "workspaceId": "ws_abc123",
            "planId": "plan_9xKz2",
            "name": "GrossSalesValue",
            "startDate": "2025-07-01",
            "endDate": "2025-12-31",
            **update,
        }
    )
    results.append({"input": update, "result": resp.json()})

success = sum(1 for r in results if r["result"]["success"])
print(f"Updated {success}/{len(results)} prices successfully")
Pricing overrides are scoped to a plan via planId. The same product–customer pair can have different prices across plans, allowing you to test the financial impact of price changes scenario-by-scenario.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
workspaceId
string
required

The workspace ID to query master data from

​
productId
string

Filter by product ID

​
customerRef
string

Filter by customer reference

​
name
enum<string>

Filter by pricing type

Available options:
GrossSalesValue,
ListedPrice,
GrossSalesValuePerKg,
ListedPricePerKg
​
asOf
string<date>

Filter to prices valid on a specific date (ISO 8601). Returns records where startDate ≤ asOf ≤ endDate.

​
limit
integer
default:50

Maximum number of records to return (max 500)

Required range: x <= 500
​
skip
integer
default:0

Number of records to skip (for pagination)

Response

Paginated list of product pricing records

​
total
integer
​
limit
integer
​
skip
integer
​
data
object[]