Company Data

Company Data is the product and store master Loyal Guru uses to decide which SKUs, categories, and locations a campaign can target. If the catalog is incomplete or out of date, discounts, points campaigns, audiences, and gamified campaigns can miss eligible carts even when the checkout payload looks correct.

Product concepts and Owner App screens: Company Data (Product Docs). This page explains how to integrate that master data — what to send, in which order, and whether to use files, the Streaming API, or a mix.

Customer identity is separate: see Customer Data.

What you integrate

Master area	Entities in Loyal Guru	Why the integration needs it
Product master	Products (SKU), product taxonomies, product features (categories / classification values)	Cart lines carry product IDs/codes; rules filter by SKU, brand, category, or taxonomy
Store master	Locations (stores), location taxonomies, location features (store categories)	Carts carry location_id / store code; rules and audiences filter by store, country, format, region
Optional / legacy	Legacy POST /promotions	Old mass-promotion entity. New Engine discounts are configured in the Owner App, not as catalog sync

Typical retailer sources: PIM / product master, ERP, e-commerce catalog, store master, POS config.

Integration channels — files vs API

Loyal Guru accepts Company Data through three channels. Most projects combine them: files (or Owner App import) for the initial load, then API for ongoing create/update/delete.

Channel	Best for	How it works	Who operates it
File import	Greenfield load, large catalogs, scheduled full/delta refresh when the retailer already exports CSV/feeds	Retailer (or middleware) delivers product and store files in the format agreed during onboarding; Loyal Guru loads them into Company Data	Loyal Guru ops + retailer IT; schedule and file contract defined per project
Streaming API	Ongoing sync from PIM/ERP/POS middleware; near-real-time SKU or store changes	Middleware calls product/location/taxonomy endpoints with the same IDs the POS and e-commerce will send on carts	Retailer / integrator
Owner App	Manual corrections, pilots, small catalogs, taxonomy setup before automation	Operators create or edit products, categories, and stores in Company Data screens	Loyalty / ops team

Choosing a model

Operating model	When to use	Notes
Files only	Catalog changes rarely; retailer cannot call APIs yet	Agree file layout, frequency, and error handling with Loyal Guru. Runtime carts must still use the IDs loaded from those files.
API only	Middleware can upsert every change	Best for continuous alignment with POS/e-commerce. Still use Owner App for one-off taxonomy design if needed.
Hybrid (recommended)	Most production projects	Initial historical load via files (or Owner App import); then API for deltas. Same external IDs in both paths.

note

File layouts and SFTP/drop locations are project-specific and defined during technical onboarding. This guide focuses on what must be synced and how the API path works once automation is in place.

Product master

Products

Each sellable SKU that can appear on a cart line should exist in Loyal Guru before campaigns that target that SKU (or its category) go live.

Concept	Integration responsibility
Stable ID and/or code	Must match the identifier POS/e-commerce send on cart lines
Name, status, price (if used)	Keep status accurate so inactive SKUs are not targeted unexpectedly
Category / taxonomy membership	Attach features so category-based campaigns include the product

API path: POST /products (create/upsert), GET /products/{id}, PATCH /products/{id}, DELETE /products/{id}.

Product taxonomies and features (categories)

Taxonomies are the classification trees (for example Brand, Own Brand, Supplier). Features are the category values inside a taxonomy (for example “Dairy”, “Private label”). Campaigns usually target features, not raw SKU lists.

Step	Endpoint	Purpose
Create taxonomy	POST /taxonomies	Define a classification tree
Update / delete taxonomy	PATCH /taxonomies/{slug}, DELETE /taxonomies/{slug}	Maintain the tree
Create category value	POST /taxonomies/{taxonomy_slug}/features	Add a feature (category)
Update / delete feature	PATCH / DELETE on .../features/{id}	Maintain category values

Sync taxonomies and features before bulk-loading products that depend on them.

Store master

Locations (stores)

Every store (and digital channel location, when used as a location) that can appear on a cart should exist as a location.

Concept	Integration responsibility
Stable ID / code	Must match location_id or store code on cart payloads
Country, status, address attributes	Used by store filters, audiences, and reporting
Category / taxonomy membership	Enables “all stores in region X / format Y” campaigns

API path: POST /locations, GET /locations/{value}, PATCH /locations/{value}, DELETE /locations/{value}.

Location taxonomies and features

Same pattern as products: taxonomies group stores (region, format, franchise); features are the concrete category values.

Step	Endpoint
Create / update / delete taxonomy	POST / PATCH / DELETE /locations/taxonomies …
Create / update / delete feature	POST / PATCH / DELETE /locations/taxonomies/{taxonomy_slug}/features …

Recommended sync order

On a greenfield or full reload:

1. Product taxonomies → product features (categories).
2. Products (linked to those features).
3. Location taxonomies → location features.
4. Locations (stores).
5. Validate with POST /carts/simulate using real product and location IDs from the catalog.

For ongoing API sync, process taxonomy/feature changes before the product or location updates that reference them.

How catalog sync feeds checkout

• Promo Engine (POST /carts/simulate / POST /carts/realtime): Loyal Guru matches line products and store against the synced catalog and campaign rules.
• Coupon Server: the POS still needs the same IDs in Loyal Guru so GET /discounts helper arrays and eligibility stay consistent with local pricing logic. See New Engine Coupon Server.

Core endpoints

Implementation map only. Schemas, auth, errors, and rate limits: API Reference.

Products

Action	Endpoint
Create / upsert product	POST /products
Get product	GET /products/{id}
Update product	PATCH /products/{id}
Delete product	DELETE /products/{id}
Create product taxonomy	POST /taxonomies
Update product taxonomy	PATCH /taxonomies/{slug}
Delete product taxonomy	DELETE /taxonomies/{slug}
Create product feature	POST /taxonomies/{taxonomy_slug}/features
Update product feature	PATCH /taxonomies/{taxonomy_slug}/features/{id}
Delete product feature	DELETE /taxonomies/{taxonomy_slug}/features/{id}

Locations (stores)

Action	Endpoint
Create / upsert location	POST /locations
Get location	GET /locations/{value}
Update location	PATCH /locations/{value}
Delete location	DELETE /locations/{value}
Create location taxonomy	POST /locations/taxonomies
Update location taxonomy	PATCH /locations/taxonomies/{slug}
Delete location taxonomy	DELETE /locations/taxonomies/{slug}
Create location feature	POST /locations/taxonomies/{taxonomy_slug}/features
Update location feature	PATCH /locations/taxonomies/{taxonomy_slug}/features/{id}
Delete location feature	DELETE /locations/taxonomies/{taxonomy_slug}/features/{id}

Markdown endpoint catalog: Products · Locations · HTTP API

Checklist before campaign tests

• Cart line product IDs/codes exist in the product master (same values from files or API).
• Cart location_id / store code exists in the store master.
• Category-targeted campaigns: features exist and products/stores are assigned.
• New SKUs and stores are synced before related campaigns go live.
• File-based and API-based loads use the same external ID strategy.
• Inactive/retired products and stores are handled so historical carts still reconcile.

Troubleshooting

Symptom	What to check
Discount or points campaign never applies	Product ID on the line vs catalog; feature membership; location filter; last sync time (file job or API).
Works in one store but not another	Location external ID, country, location feature membership.
New SKU never eligible	POST /products (or file row) succeeded; features attached; IDs match the cart.
Category campaign misses products	Taxonomy slug/feature IDs; products linked after the taxonomy change; file vs API used different category keys.
File load OK but API updates fail	Auth headers, ID format, and whether middleware sends the same keys as the file contract.
Coupon Server helper arrays empty / wrong	Catalog synced for internal taxonomy expansion; see Coupon Server guide.
Reporting dimensions look wrong	Same product/store IDs at runtime vs analytics; status active/inactive.