# Storelayer

> Build loyalty programs, wallets, promotions, and referrals through HTTP.

Install the agent skill: https://github.com/storelayer/skills/blob/main/skills/storelayer/SKILL.md
Read relevant concepts and guides here; endpoint contracts live in the existing API reference.
API reference: https://api.storelayer.io/docs
OpenAPI contract: https://api.storelayer.io/openapi.json

## Documentation

- [Using Catalog Data](https://docs.storelayer.io/api/catalog.md): Storelayer catalog products and categories (fields, generated prod_/cat_ ids, bulk import of up to 1000 products, PUT semantics) and why promotion evaluation never reads the catalog, so your cart must carry the labels promotions match.
- [Working with Customer Data](https://docs.storelayer.io/api/customers.md): Register, upsert, bulk-import (max 1000), search and delete external users; error codes; metadata merge semantics; listing a customer's workflows.
- [Sending Business Events](https://docs.storelayer.io/api/events.md): How to call POST /ingest/events. Payload design in cents, the 201 response and 400 validation body, the lack of an idempotency key and how to deduplicate, refunds, and following the event to its workflow.
- [API Overview](https://docs.storelayer.io/api/overview.md): Storelayer API conventions — base URL, auth, success/error envelopes, error codes, validation errors, pagination (limit/offset and page/pageSize), money units, IDs, timestamps, and which reference tag covers what.
- [Integrating Checkout Promotions](https://docs.storelayer.io/api/promotions.md): Checkout integration with POST /promotions/evaluate, covering the full cart input (required camelCase fields, item id vs productId, shipping, redemptions), what the engine derives, preview vs record, transactionId retry and conflict semantics, error codes and usage records.
- [Integrating Referrals](https://docs.storelayer.io/api/referrals.md): Request bodies for creating referral codes, validating and applying them at signup, looking up a customer's code, listing referrals, and deactivating codes, plus the order of calls in a typical app.
- [Using Store and Facility Data](https://docs.storelayer.io/api/stores.md): Store and facility fields, bulk import (skips existing IDs), update semantics, and how a storeId reaches promotions ($('cart').storeId) and rules (event payload plus the stores.get_store resource).
- [Working with Wallets](https://docs.storelayer.io/api/wallets.md): Request bodies for wallet earn, spend and modify, expiry and reference fields, paginating transactions and asset entries, error codes, and how to verify or safely retry a wallet change.
- [Customers](https://docs.storelayer.io/concepts/customers.md): External users are your end customers, identified by your own userId. Covers profile fields, how a userId keys wallets, events, referrals and workflows, and what deleting a profile does and does not remove.
- [Loyalty Events](https://docs.storelayer.io/concepts/loyalty-events.md): Event shape for POST /ingest/events, how rules bind to event types, rule anatomy (conditions, resources, actions, priority, validity), and the asynchronous processing model.
- [Projects](https://docs.storelayer.io/concepts/projects.md): Storelayer projects — the isolation boundary, project config (currency, timezone, settings), using separate projects as environments, cloning rules between projects, and team roles.
- [Promotions](https://docs.storelayer.io/concepts/promotions.md): How a Storelayer promotion is built (conditions, applicationMethod, constraints), its status lifecycle, priority, compounding and stacking rules, and what $('cart') and $('item') expose.
- [Referrals](https://docs.storelayer.io/concepts/referrals.md): Referral codes (user-owned or system), validate vs apply, the referral record, project referral config, limits and validation errors. Rewards are not built in; rules pay them.
- [Wallets and Points](https://docs.storelayer.io/concepts/wallets.md): Per-customer wallets with free-form asset types, expiring asset entries spent first-expiring-first-out, and an append-only transaction ledger. Explains earn vs spend vs modify.
- [Getting Started with Agents](https://docs.storelayer.io/getting-started/agents.md): Give a coding agent Storelayer access — install the skill, read docs via llms.txt and .md pages, use OpenAPI for contracts, or run the @storelayer/mcp-server MCP server with an API key.
- [Authentication and Project Access](https://docs.storelayer.io/getting-started/authentication.md): Storelayer auth — project API keys (Bearer or X-API-Key), dashboard JWTs, project scoping, key management and rotation, public routes, and 401/403 error codes.
- [Introduction](https://docs.storelayer.io/getting-started/introduction.md): The Storelayer mental model — projects, customers, events, rules, wallets, promotions, and referrals — and how they connect.
- [Quick Start](https://docs.storelayer.io/getting-started/quick-start.md): First Storelayer calls with curl — API key, read project config, register a customer, earn points, read the wallet, and send an event.
- [Conditions and Resources](https://docs.storelayer.io/guides/conditions.md): Expression syntax ({{ $('key').path }}), the flat condition group shape, all 25 operators and rightType coercion, and every resource type (event, internal wallet/user/history, http, database, payload, custom_table, code) with the exact data each one resolves to.
- [Creating Promotions](https://docs.storelayer.io/guides/creating-promotions.md): Worked example of a 10%-off-over-$50 promotion, from create body to draft preview with includeInactiveIds and reading applied/notApplied, plus coupons, recording checkout, cancelling usage, and recipes for free shipping, BOGO, category, fixed-amount and coupon-only offers.
- [Custom Tables](https://docs.storelayer.io/guides/custom-storage.md): Typed per-project tables for tier thresholds, eligibility lists and other loyalty configuration. Covers column types, id rules, limits, the query filter language, the admin SQL endpoint, and binding a table to rules and promotions as a custom_table resource, with a worked tier example.
- [Debugging Rules](https://docs.storelayer.io/guides/debugging.md): Symptom-to-check playbook for missing or wrong rewards. Covers ingest 400s and silently dropped fields, rules that never ran or did not match, missing resources, failed actions, wrong units, and duplicates, using workflow records and /rules/test.
- [Discount Scripts](https://docs.storelayer.io/guides/discount-scripts.md): Writing custom_script promotions: the normalised per-unit items a script sees, sandbox globals and limits, the required { items: [{ id, amount, redemption? }], suggestion? } return, error reasons, testing with execute-script, and a wallet points-redemption example.
- [Setting Up a Loyalty Program](https://docs.storelayer.io/guides/loyalty-program.md): End-to-end recipe for 100 points per purchase of $50+ (5000 cents). Register the event resource, create the rule, test conditions, ingest, follow the workflow, check the wallet. Also covers welcome bonus, tier multiplier, points per dollar, stamp card, expiring points, and an action config reference.
- [Referral Programs](https://docs.storelayer.io/guides/referral-programs.md): Worked example where referrer and referee each get 500 points on the referee's first purchase. Includes the resource and rule request bodies, the one-time-reward guard, and how to verify attribution and both wallet credits.
- [HTTP Integrations](https://docs.storelayer.io/guides/webhooks.md): Call external systems from rule actions. Covers integration types (http, slack, telegram, postgres, aws-ses) and their config, the integration action's payloadTemplate/sql/to/subject/body, templating rules, auth options, and failure and retry behavior.
- [Workflows](https://docs.storelayer.io/guides/workflows.md): The record each processed event leaves. Workflow id equals event id. Covers completed vs failed, what GET /workflows, /workflows/{id}, /full and /users/{userId}/events return, and how to poll until processing finishes.
- [Storelayer Documentation](https://docs.storelayer.io/index.md): Storelayer is a loyalty engine API — events, rules, per-customer wallets, cart promotions, and referrals. Start here to find the right guide.
- [JavaScript Integration](https://docs.storelayer.io/sdks/javascript.md): Call Storelayer from a Node/Bun/Workers backend with a small typed fetch client that handles the success envelope, error codes, and validation errors; or generate types from OpenAPI.
- [HTTP Integration](https://docs.storelayer.io/sdks/rest.md): Integrate Storelayer from any language over plain HTTP — request template, envelope and error parsing, timeouts, safe retries for non-idempotent wallet writes, async events, and client generation from OpenAPI.