> ## Documentation Index > Fetch the complete documentation index at: https://docs.scrip.dev/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Before planning an integration, read https://docs.scrip.dev/which-endpoints-you-need.md. It lists the calls an app makes as users earn and redeem, such as sending and reversing events, reading balances, and redeeming rewards. Every other endpoint creates or changes the program itself, and the dashboard at https://app.scrip.dev is the usual place for that work. > Gift cards are rewards in the program's rewards catalog, next to custom rewards. Redeem one with `POST /v1/participants/{id}/redemptions/items` and a `fulfillment` object. When the order succeeds, show the participant the claim link from `fulfillment.claim_url` in the redemption response or from `POST /v1/redemptions/{id}/claim-link`. An order can finish after the request returns, so handle the `redemption.fulfillment_succeeded` and `redemption.fulfillment_failed` webhooks. See https://docs.scrip.dev/guides/gift-cards.md. > Give every event, redemption, and transfer an `idempotency_key` built from your own data, such as an order ID, so retries are safe. Keep API keys on your server. > Request and response schemas are in https://docs.scrip.dev/openapi.json. Add `.md` to any docs URL to get the page as Markdown. # Reward sources > Add gift cards to your program's catalog and choose what participants pay A reward source connects a fulfillment account to a program's rewards catalog. It defines which products you offer and what they cost in your asset. Scrip uses those settings to create and maintain the rewards in the catalog. For example, you can offer gift cards priced at one star per US dollar. A USD 100.00 card then costs 100 stars. Your application reads that card from the same catalog as your other rewards. This guide configures a source through the API. You can also choose cards and prices in the Scrip dashboard. Once your catalog is ready, follow [Gift cards](/guides/gift-cards) to build the participant's redemption flow. | What you want to do | Where to start | | --------------------------------------- | ----------------------------------------------- | | Connect the account that pays for cards | [Gift-card setup](/guides/gift-cards#set-up) | | Add cards to a program through the API | [Create a source](#create-a-source) | | Set the asset price | [Pricing](#pricing) | | Change one card's price or value | [Set product overrides](#set-product-overrides) | ## Find your fulfillment account After connecting and funding your account in the dashboard, retrieve it: ```bash theme={null} GET /v1/fulfillment-accounts ``` Use its `id` as `fulfillment_account_id` when you create the source. The account pays for every card ordered through that source. [Gift-card setup](/guides/gift-cards#set-up) explains how account funding and participant balances work together. ## Pricing Choose any [asset linked to the program](/guides/programs#linking-assets), then decide how much of that asset buys a given card value. The asset could represent points, stars, credits, or another unit you define. Its name does not give it a monetary value; you set the price on the source. The API expresses this price as `default_rate`: asset units per currency minor unit. For USD, a minor unit is one cent. To charge one star per dollar, divide one star by 100 cents and use `"0.01"`. | Your pricing | `default_rate` | | ----------------------------- | -------------- | | 1 star per USD 1.00 | `"0.01"` | | 1,000,000 points per USD 1.00 | `"10000"` | | 1 credit per USD 100.00 | `"0.0001"` | Send rates as decimal strings to preserve precision. You can set a different `rate` for individual products later. A source applies the same numeric rate to every supported currency. Scrip does not convert currencies. If you want to offer only USD cards, [set `currency` to `USD`](#set-product-overrides) for each product. Filtering products by country does not restrict their currencies. ## Create a source Create a source with the account ID, your asset ID, and your chosen rate. This example uses the stars asset and prices cards at one star per US dollar: ```bash theme={null} POST /v1/programs/{programId}/reward-sources ``` ```json theme={null} { "fulfillment_account_id": "71f2a9d4-3b6e-4c8a-9f1d-5e2b8c7a0091", "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02", "policy": "MANUAL", "default_rate": "0.01" } ``` Keep the returned source `id` for the next requests. With `MANUAL`, the default policy, the source starts with no rewards. You choose which products to add. A product is a card you can order from the account, with its own supported countries, currencies, and values. One merchant brand can have several products, such as cards for different regions. Browse the account's products to find the ones you want: ```bash theme={null} GET /v1/fulfillment-accounts/{id}/products?category=GIFT_CARD&country=US¤cy=USD ``` Use the product's Scrip `id` as `{productId}` to include it: ```bash theme={null} PUT /v1/programs/{programId}/reward-sources/{sourceId}/product-settings/{productId} ``` ```json theme={null} { "included": true } ``` Scrip adds a reward for that product to the program's catalog. It uses the source's rate and lets the participant choose from the product's supported values and currencies. Read the catalog to see the result: ```bash theme={null} GET /v1/programs/{programId}/rewards?status=ACTIVE ``` The returned reward has its own `id`, which you use when redeeming. Product IDs are for configuration; reward IDs are for redemption. See [Gift cards](/guides/gift-cards#list-active-rewards) for the catalog response and the next steps. ## Include matching products automatically Use the `ALL` policy when you want the source to include every product matching your filters. Matching products added to the account later will also appear in your catalog. To include gift cards available in the US, update the source: ```bash theme={null} PATCH /v1/programs/{programId}/reward-sources/{sourceId} ``` ```json theme={null} { "policy": "ALL", "category_filter": ["GIFT_CARD"], "country_filter": ["US"] } ``` The source keeps its existing rate. You can use product settings to exclude individual cards or give them different prices. If you omit a category filter, other supported categories, such as prepaid cards and charity products, can also be included. ## Set product overrides Product settings let you change one product without changing the rest of the source. For example, offer a fixed USD 100.00 card for 80 stars instead of the default 100 stars: ```bash theme={null} PUT /v1/programs/{programId}/reward-sources/{sourceId}/product-settings/{productId} ``` ```json theme={null} { "included": true, "rate": "0.008", "face_value_minor": 10000, "currency": "USD" } ``` `face_value_minor` is the card value in currency minor units. Setting it with `currency` fixes the reward to that supported value and currency. Scrip creates a `UNIT_BASED` reward whose `unit_cost` is `80`. Without a fixed value, the reward is `AMOUNT_BASED` and lets the participant choose a supported value. Set `currency` without `face_value_minor` to let participants choose a card value in one currency. For example, `{"included": true, "currency": "USD"}` offers the product's supported values in USD. The catalog lists only USD in `fulfillment.currencies`. `PUT` replaces the product's settings, so include every override you want to keep. Sending only `{"included": true}` restores the source's default rate and all of the product's supported values and currencies. | Setting | Effect on the catalog | | ------------------ | -------------------------------------------------------------------- | | `included: true` | Include the product, even if it does not match the source's filters. | | `included: false` | Exclude the product under either policy. | | Delete the setting | Return to the source's policy, filters, and default rate. | To remove all overrides for a product: ```bash theme={null} DELETE /v1/programs/{programId}/reward-sources/{sourceId}/product-settings/{productId} ``` Under `MANUAL`, deleting the setting removes the reward from active listings. Under `ALL`, it remains available if the product matches the source's filters. ## Price fractional assets Scrip rounds the calculated price up to the smallest unit your asset supports. The asset's [scale](/guides/asset-configuration) sets that precision: `0` allows whole units, `2` allows hundredths, and `3` allows thousandths. For example, use a credit asset with scale `2` and a rate of `"0.0001"`, so one credit buys USD 100.00. A USD 25.00 card costs `0.25` credits. A USD 25.01 card calculates to `0.2501` credits and rounds up to `0.26`. With a whole-unit asset, both cards would cost `1` credit. For a fixed-value reward, display the `unit_cost` returned by the catalog. For a variable-value reward, use `fulfillment.rate` and `fulfillment.asset_scale` to calculate the price: ```text theme={null} cost = ceil(face_value_minor × rate × 10^asset_scale) / 10^asset_scale ``` Here, `ceil` rounds a fractional result up to a whole number; whole numbers stay unchanged. Use decimal arithmetic to match Scrip's calculation. Scrip calculates the charge again when the participant redeems, and the redemption's `amount` records that charge. ## Change prices or remove cards Update `default_rate` on the source to change prices for products using that default. Products with their own `rate` keep their override. Price changes apply to future redemptions; an existing redemption keeps its authorized amount. Change cards through their source or product settings. Scrip maintains these rewards for you, so direct reward edits return `409 auto_managed_item`. Excluding a product or deleting its source archives the corresponding rewards. Scrip also archives a reward if its product is removed from the fulfillment account. Past redemptions remain available. A program can have several sources, including sources priced in different assets. All their rewards appear together in the program's catalog. Keep the reward's `id` and `asset_id` when building your selection screen, since different sources can offer cards with similar names. Show your catalog, order a card, and deliver its claim link. Look up account, source, and product-setting operations.