Stores

Stores are curated subsets of the catalog. You can create multiple stores with different audiences, time-limited items, and price overrides.

Store features

• Segment targeting — show stores to specific user segments
• Price overrides — sale prices for specific store listings
• Scheduling — time-limited items with available_from and available_until
• Purchase limits — cap how many times each user can buy an item

MCP tools

Example: Holiday sale

Agent: "Create a holiday store with discounted items"

amba_stores_create({
  project_id: "proj_xxx",
  name: "Holiday Sale",
  description: "Limited time holiday deals!"
})

amba_stores_add_listing({
  project_id: "proj_xxx",
  store_id: "store_xxx",
  catalog_item_id: "item_premium_theme",
  override_prices: { "gold": 100 },
  available_from: "2025-12-20T00:00:00Z",
  available_until: "2025-12-31T23:59:59Z",
  max_purchases_per_user: 1
})

Segment targeting

A store created with a segment_id is open only to that segment's members. Membership is what the segment's last evaluation recorded, so a user the segment has not evaluated yet (a new user, or a segment created or changed since its last run) does not see the store until the next evaluation adds them, within 15 minutes of a change to your users' data. To refresh a segment now, call POST /v1/admin/projects/:projectId/segments/:id/evaluate (amba_segments_evaluate).

For a user outside the segment the store is absent from Amba.stores.list(), and reading it, its purchase options, and buying from it (including POST /v1/client/inventory/purchase with its store_id) answer 404 NOT_FOUND, the same as for a store that does not exist.

An item that only segment-targeted stores list is exclusive to those segments. Buying it straight from the catalog (POST /v1/client/inventory/purchase without store_id) answers 403 STORE_ACCESS_REQUIRED for a user outside all of them. To also sell the item to everyone at its catalog price, list it in a store without a segment.

A segment a store targets can't be deleted: DELETE on the segment answers 409 SEGMENT_IN_USE and names the stores. Detach the segment first (amba_stores_patch with segment_id: null, or another segment), or delete the store.

Price overrides

override_prices maps a currency code to the price the store charges in that currency, a whole number. Amba.stores.getPurchaseOptions() returns each option's price_cents with the override applied, and Amba.stores.purchase() charges exactly that amount; currencies without an override keep the catalog price. Purchase options cover the currencies the item has a catalog price in. An override in a currency the item has no catalog price in is sold through POST /v1/client/inventory/purchase with the store's store_id, and the store read lists it in the listing's prices.

Purchase limits

max_purchases_per_user is a whole number from 1 up, or null for no limit. It counts each user's purchases of the item through that store, plus purchases of the item straight from the catalog. While an active store limits an item this way, the item is sold through a store only: POST /v1/client/inventory/purchase without store_id answers 409 STORE_PURCHASE_REQUIRED, so the app buys it with store_id (Amba.inventory.purchase({ sku, currency_key, store_id })) or through POST /v1/client/stores/:storeKey/purchase (Amba.stores.purchase). The limit holds while the listing's window is closed, so a finished limited offer can't be bought again from the catalog. Deactivating the store lifts it. A limited item in a segment-targeted store is sold to that segment's members only.

Client API reference

See the Stores API reference for request and response shapes.