Skip to main content
Use these resources when asking AI coding tools to help integrate Scrip. Start with how Scrip works and which endpoints your app calls. Then add the guides for the task, and the OpenAPI spec when the tool needs request and response schemas.

​
Context files

  • Scrip overview: Start here if the tool only knows the product website.
  • Docs index: Use this to choose relevant docs pages.
  • Full docs: Load this when the tool supports large context files.
  • OpenAPI spec: Use this for endpoint paths, request schemas, response schemas, and error codes.
Every docs page is also available as Markdown. Add .md to the page URL, for example https://docs.scrip.dev/which-endpoints-you-need.md. To let an AI client work with authorized account data instead of static context, connect the MCP server. It exposes Scrip as a curated set of tools and serves these docs as resources the model can pull on demand. Give the tool Which endpoints you need before it plans an integration. It separates the calls your app makes from the work of setting up the program. Events are the input that drives rule evaluation, balance changes, ledger entries, webhooks, and downstream reporting. Load event context before asking an AI tool to design rules, balances, or automations. For most integration work, load these pages in order:
  1. Introduction
  2. Core concepts
  3. Which endpoints you need
  4. Quickstart
  5. Authentication
  6. Event processing
  7. API introduction
  8. OpenAPI spec
Add the Glossary so the tool uses Scrip’s terms, such as participant and asset.

​
Workflow context

For programs and assets, load Core concepts, Programs, and Asset configuration. For participants and groups, load Core concepts, Participants, State management, and Groups. For rules and events, load Event processing, Writing rules, CEL expressions, Rule actions, Rule sets, and Managing rule configuration. Add Campaigns for limited-time promotions, such as double points for a month. For balances and ledger behavior, load Ledger, Balance operations, and Lots and expiration. For redemptions and rewards catalog work, load Ledger, Balance operations, Rewards catalog, Redemptions, and Redemption lifecycle. The lifecycle guide defines reservation, redemption status, expires_at, capture_journal_entry_id, and release_journal_entry_id. For gift cards, load Rewards catalog, Gift cards, Reward sources, and the gift-card events in the webhooks guide. A gift card is a reward in the same catalog as your custom rewards, and your app redeems it with POST /v1/participants/{id}/redemptions/items. Include the webhook events because some orders finish after the redemption request returns. For transfers, load Ledger, Balance operations, and Transfers. For reporting, load Ledger, Event processing, and Reporting. For automations, load Event processing, Writing rules, and Automations. For webhooks, load Event processing and Webhooks. For testing, load Quickstart, Event processing, and Testing.

​
Complete rule configuration context

When changing several rules or sets, load Managing rule configuration and follow the sequence there. Load the multi-set example for placement, stop_after_match, and event-start snapshot behavior.

​
Integration path

An integration has two parts: setting up the program, and the calls your app makes as users earn and redeem. Tell the tool which part it is working on.

​
Set up a program

The dashboard is the usual place to set up a program, and it uses the same API your app does. To do it through the API, follow the Quickstart. It sets up a program and sends a first event:
  1. Set up server-side authentication.
  2. Create a program.
  3. Create and link an asset.
  4. Use the automatic default rule set, or create named sets to group rules and control the order they run in.
  5. Define a rule with a CEL condition and one or more actions.
  6. Ingest an event with an idempotency_key.
  7. Verify the event trace (rule_evaluations), participant balance, and ledger entries.
To offer gift cards, connect and fund a fulfillment account in the dashboard. This is the account that pays for the cards. Then choose cards and prices in the dashboard or through Reward sources.

​
Connect your app

Your app sends POST /v1/events for each user action your rules care about, such as a purchase. Give each event an idempotency_key built from your own data, such as an order ID. With the program’s on_unknown_participant left at CREATE (the default), the first event for a new user creates their participant, so your app does not create participants first. Which endpoints you need lists the other calls, including event reversals for refunds, balances, redemptions, and webhooks.

​
Security constraints

Keep production credentials server-side. Do not expose them in browser code, mobile apps, public repositories, or AI prompts. Use deterministic idempotency_key values for event retries. Reusing the same key returns the same event identity without reprocessing, even if the payload differs. To correct or replace an event, send a new event with a new idempotency key.