Stores

A store is a curated view onto the catalog — optionally segment-scoped. Listings pin catalog items into a store with sort order, per-store price overrides, availability windows, and per-user purchase caps.

Endpoints

POST /admin/projects/:projectId/stores

Request

segment_id targets the store at a segment: only users the segment's last evaluation recorded as members see the store or buy from it. A user the segment has not evaluated yet does not see it until the next evaluation adds them.

Response 201

{ "data": { "id": "…", "name": "…", "segment_id": null, "is_active": true } }

Errors

• 400 INVALID_JSON — the body is not a JSON object.
• 400 INVALID_NAME — name is missing or empty.
• 400 INVALID_DESCRIPTION — description is neither a string nor null.
• 400 INVALID_SEGMENT_ID — segment_id is not a uuid.
• 400 SEGMENT_NOT_FOUND — no segment in this project has that id.
• 409 STORE_EXISTS — a store with this name exists.
• 500 CREATE_FAILED.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/stores' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Main store"
}'

Curl:

curl -X POST "${BASE_URL}/admin/projects/${PROJECT_ID}/stores" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Main store"}'

GET /admin/projects/:projectId/stores

{ "data": [{ "id": "…", "name": "…", "is_active": true }] }

Try it:

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/stores'

Curl:

curl -X GET "${BASE_URL}/admin/projects/${PROJECT_ID}/stores" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

PATCH /admin/projects/:projectId/stores/:storeId

Allowed fields: name, description, is_active, segment_id. segment_id: null opens the store to every user.

Errors

• 400 INVALID_JSON, 400 INVALID_NAME, 400 INVALID_DESCRIPTION, 400 INVALID_SEGMENT_ID, 400 SEGMENT_NOT_FOUND — as on create.
• 400 INVALID_IS_ACTIVE — is_active is not a boolean.
• 404 NOT_FOUND.
• 409 STORE_EXISTS.

Try it:

curl -X PATCH 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/stores/%7B%7BstoreId%7D%7D'

Curl:

curl -X PATCH "${BASE_URL}/admin/projects/${PROJECT_ID}/stores/{storeId}" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE /admin/projects/:projectId/stores/:storeId

{ "data": { "deleted": true } }

Try it:

curl -X DELETE 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/stores/%7B%7BstoreId%7D%7D'

Curl:

curl -X DELETE "${BASE_URL}/admin/projects/${PROJECT_ID}/stores/{storeId}" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

POST /admin/projects/:projectId/stores/:storeId/listings

Request (AddStoreListingInput)

• override_prices maps currency codes to the price the store charges in that currency: a whole number from 0 to 2147483647 (a JSON number or a digit string), or null for the catalog price. The client store routes show and charge this price.
• max_purchases_per_user is a whole number from 1 to 2147483647, or null for no limit.

Response 201

{ "data": { "id": "…", "store_id": "…", "catalog_item_id": "…", "sort_order": 0 } }

Errors

• 400 INVALID_JSON — the body is not a JSON object.
• 400 INVALID_CATALOG_ITEM_ID — catalog_item_id is missing or not a uuid.
• 400 INVALID_OVERRIDE_PRICES — override_prices is not an object of whole-number prices.
• 400 INVALID_MAX_PURCHASES_PER_USER — max_purchases_per_user is not a whole number from 1, or null.
• 400 INVALID_SORT_ORDER — sort_order is not a whole number.
• 400 INVALID_AVAILABLE_FROM / 400 INVALID_AVAILABLE_UNTIL — the value is not an ISO 8601 timestamp or null.
• 404 NOT_FOUND — the store or the catalog item does not exist.
• 409 LISTING_EXISTS — the store already lists this item.
• 500 ADD_LISTING_FAILED.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/stores/%7B%7BstoreId%7D%7D/listings' \
  -H 'Content-Type: application/json' \
  -d '{
  "catalog_item_id": "<catalog_item_id>"
}'

Curl:

curl -X POST "${BASE_URL}/admin/projects/${PROJECT_ID}/stores/{storeId}/listings" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"catalog_item_id":"<catalog_item_id>"}'

GET /admin/projects/:projectId/stores/:storeId/listings

Listings with each row carrying inlined catalog-item display info, ordered by sort_order.

Response 200

{
  "data": [
    {
      "id": "…",
      "store_id": "…",
      "catalog_item_id": "…",
      "sort_order": 0,
      "override_prices": null,
      "catalog_items": {
        "key": "gems_100",
        "name": "100 Gems",
        "icon_url": "…",
        "item_type": "consumable"
      }
    }
  ]
}

Try it:

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/stores/%7B%7BstoreId%7D%7D/listings'

Curl:

curl -X GET "${BASE_URL}/admin/projects/${PROJECT_ID}/stores/{storeId}/listings" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

PATCH /admin/projects/:projectId/stores/:storeId/listings/:listingId

Allowed fields: override_prices, sort_order, available_from, available_until, max_purchases_per_user. Scoped by both listingId and storeId so a listing from another store can't be mutated through the wrong URL. override_prices and max_purchases_per_user follow the rules above; null clears either.

Errors

• 400 INVALID_JSON, 400 INVALID_OVERRIDE_PRICES, 400 INVALID_MAX_PURCHASES_PER_USER, 400 INVALID_SORT_ORDER, 400 INVALID_AVAILABLE_FROM, 400 INVALID_AVAILABLE_UNTIL — as on create.
• 404 NOT_FOUND.

Try it:

curl -X PATCH 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/stores/%7B%7BstoreId%7D%7D/listings/%7B%7BlistingId%7D%7D'

Curl:

curl -X PATCH "${BASE_URL}/admin/projects/${PROJECT_ID}/stores/{storeId}/listings/{listingId}" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE /admin/projects/:projectId/stores/:storeId/listings/:listingId

{ "data": { "deleted": true } }

Try it:

curl -X DELETE 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/stores/%7B%7BstoreId%7D%7D/listings/%7B%7BlistingId%7D%7D'

Curl:

curl -X DELETE "${BASE_URL}/admin/projects/${PROJECT_ID}/stores/{storeId}/listings/{listingId}" \
  -H "Authorization: Bearer ${DEV_TOKEN}"