# Shared prices (/docs/shared-prices)



A shared price is a named definition with an ordered set of pricing rules. Many items can link to the same definition. Updating it updates every linked item, including selections at child locations. Item VAT remains configured on each item.

Individual item pricing still works: use it when an item should have its own amount and modifiers instead of a shared definition.

## Access and units [#access-and-units]

Use the Common API base URL for your environment and an `X-API-Key` with access to the location. Listing requires `inventory.read`, creation requires `inventory.create`, and editing or assigning requires `inventory.update`. The location needs `grouped_pricing`, available on Connected/Growth and Intelligence.

Send `X-Location-Id` for the location whose inventory you are editing, and the same `locationId` in pricing requests. The examples use placeholders; replace them with actual IDs. All pricing rule amounts are **currency units**, not cents: `25` means 25 SEK for a SEK location.

## Create a definition [#create-a-definition]

```bash
curl "$COMMON_API/api/v1/prices?locationId=$PARENT_LOCATION_ID" \
  -H "X-API-Key: $KARMA_API_KEY" \
  -H "X-Location-Id: $PARENT_LOCATION_ID" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Soda pricing","inheritToChildren":true,"pricings":[{"name":"BASE","price":25,"order":0}]}'
```

The response is HTTP 201 with the standard envelope:

```json
{"status":"success","data":{"id":"<price UUID>","version":1},"meta":{}}
```

The first rule must be an unconditional `BASE`. A definition may contain up to 100 rules. Other rules can carry `scheduleId`, `channelTypes`, `validFrom`, `validTo` and `metadata`. Schedule IDs must be accessible to the owner; create schedules through the Schedules API before referencing them. An example second rule for a 10% takeaway discount is:

```json
{"name":"PERCENT","price":0,"order":1,"channelTypes":["TAKEAWAY"],"metadata":{"percentage":-10}}
```

Create “Soda prices East” and “Soda prices West” as separate definitions. They are independent prices, not overrides of the base definition.

## Discover existing prices [#discover-existing-prices]

`GET /api/v1/prices?locationId=<location ID>&limit=50&offset=0&search=Soda` returns `data.items` and `data.hasMore`. Increase offset by the requested limit until `hasMore` is false. Limit is at most 100. Each definition includes its owner, `inherited`, rules, and current `version`.

A child sees its local prices and ancestor prices with `inheritToChildren: true`. Parent prices are read-only there. Children can create their own local definitions.

## Assign to owned items [#assign-to-owned-items]

Find exact IDs with `GET /api/v1/inventory?locationId=<location ID>&search=Soda&page=1&limit=50`. Follow the returned pagination. Assign each owned item with:

Inventory also supports `titleFilter` and `pricingName` (with `titleMatch` or `pricingMatch` set to `contains` or `eq`), `source=local|inherited`, and `minPrice`/`maxPrice` in currency units. Use `sort=title|calculatedPrice|pricing|source` with `order=asc|desc`. Price filtering and sorting use the effective current price for the requested `channel`, including inherited selections and active rules, before pagination.

```bash
curl -X PUT "$COMMON_API/api/v1/inventory/$ITEM_ID" \
  -H "X-API-Key: $KARMA_API_KEY" \
  -H "X-Location-Id: $LOCATION_ID" \
  -H 'Content-Type: application/json' \
  -d '{"pricingGroupId":"<price UUID>"}'
```

`POST /api/v1/inventory` also accepts `pricingGroupId` alongside the required item creation fields. Do not send an individual `pricings` array when linking a shared price.

## Assign at a child location [#assign-at-a-child-location]

For an inherited item (or POS-managed item), use the override endpoint and the **child** location:

```bash
curl -X PUT "$COMMON_API/api/v1/inventory/$ITEM_ID/overrides?locationId=$CHILD_LOCATION_ID" \
  -H "X-API-Key: $KARMA_API_KEY" \
  -H "X-Location-Id: $CHILD_LOCATION_ID" \
  -H 'Content-Type: application/json' \
  -d '{"pricingGroupId":"<West price UUID>"}'
```

The parent must permit pricing overrides on the item. Another child can select East without changing either definition or the parent item. The chosen definition stays linked, including future rule and schedule changes.

## Update a definition [#update-a-definition]

`PUT /api/v1/prices/<price UUID>?locationId=<owner location ID>` accepts the complete `name`, `inheritToChildren`, `pricings` and current `version`. Read the definition first and preserve rules you do not intend to change. A successful update returns a new version. HTTP 409 means the definition changed: read it again and reconcile before retrying. A child cannot edit an ancestor's definition.

Omitting `pricingGroupId` from an item update preserves its selection. To detach an owned item, explicitly send `pricingGroupId: null` and its individual `pricings` in the same request. See the Inventory API override contract when clearing child overrides.

Inaccessible prices return 404; feature or ownership restrictions return 403. Bulk client workflows should record successes and retry only failed item assignments. Creating a price is not idempotent: after an uncertain response, inspect the list before creating again.

## Kaia [#kaia]

From Overview, ask Kaia to create a named price and apply it to specific items. She lists definitions and effective inventory, proposes writes for confirmation, and uses the same Common API rules. Pricing tools are `list_shared_prices`, `list_pricing_items`, `create_shared_price`, `update_shared_price`, and `assign_shared_price`. Assignments report per-item successes and failures. Automatic undo is not available for these operations.