Building the integration
Catalog sync
Push your item list so merchants build stamp rules against a real menu instead of typing item names.
Merchants build rewards like “buy 5 coffees, get one free” by naming items. Without a catalog they type those names as free text, which breaks the moment someone renames a menu item. If you push your catalog, they pick from a real list and match on SKU.
This is a Generic-tier convenience. Featured vendors do not build it — Perx pulls from your catalog API on a schedule instead.
Request
POST /v1/catalog/sync
{
"store": { "id": "12345" },
"items": [
{ "externalId": "prod-8891", "name": "Flat White", "sku": "SKU-COFFEE-001", "category": "Beverages", "price": 5.50, "isActive": true },
{ "externalId": "prod-2210", "name": "Chicken Sandwich", "sku": "SKU-FOOD-014", "category": "Food", "price": 34.00, "isActive": true }
]
}| Field | Req | Notes |
|---|---|---|
externalId | yes | Item id on your side — the stable key across syncs. Do not reuse it for a different product. |
name | yes | What the merchant will see when picking items. |
sku | no | Strongly recommended — SKU is what makes stamp rules match reliably in items[] on sale events. |
category | no | Groups the picker. Merchants with large menus will thank you. |
price | no | Display only. |
isActive | yes | Send false for items you keep but no longer sell. |
Full-snapshot semantics
Send your entire active catalog on every call. Items previously known but absent from the payload are marked inactive, never hard-deleted — a merchant’s existing reward rules keep working even if you drop an item by mistake.
A nightly push is plenty. There is no need to sync on every product edit, and doing so mostly generates load without changing what merchants can build.
A snapshot containing only your changed items will deactivate everything else. If you cannot produce a full list cheaply, sync less often rather than sending deltas.
How merchants use it
Once synced, the Perx dashboard offers a picker instead of a text field when a merchant builds a stamp reward. Perx then matches your sale events’ items[] against the selection — exact match on name or SKU, plus case-insensitive keyword matching on the item name.
That is why sending sku on both the catalog and each sale matters: it is the only matching path that survives a menu rename.