Karma Developers

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

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

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:

{"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:

{"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

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

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.

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

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

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

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

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.

Shared prices