Set up
Connect a fulfillment account in the Scrip dashboard. This is the account you use to buy the gift cards. Complete the account’s setup and funding steps, then choose which cards to add to your program and how much they cost in your asset. There are two balances involved in a redemption. The participant spends their asset balance in Scrip, while your fulfillment account pays for the card. For our example, the participant spends 100 stars and your account funds a USD 100.00 card. Scrip records the asset charge in the ledger; it never holds or transfers the money that pays for the card. Your fulfillment account must beACTIVE and have enough funds to cover orders. The participant must also have enough available asset balance. To configure the cards and prices through the API, follow Reward sources.
List active rewards
Fetch your program’s catalog to show participants what they can redeem:fulfillment, plus any available images and descriptions in display. You can build the selection screen from this response without fetching each product separately.
This excerpt shows a card that lets the participant choose a value between USD 5.00 and USD 100.00:
id for the redemption request. Follow pagination.next_cursor if the catalog has more pages. When rendering content from display, handle missing fields and sanitize HTML.
An active reward can still be unavailable to a particular participant, for example because they have too little balance or have reached a redemption limit. Scrip checks those conditions when they redeem.
Choose a value and show the price
The card’s face value is the amount the participant can spend with the merchant. The API expresses it in currency minor units, such as cents for USD. A USD 100.00 card has aface_value_minor of 10000.
For an AMOUNT_BASED gift card, let the participant choose a supported value and a currency from fulfillment.currencies. A product can offer a list of values in denominations_minor, an inclusive minimum-to-maximum range, or both. A value is valid if it appears in the list or falls within the range.
Multiply the chosen face value by fulfillment.rate to show the asset price. In this example, 10000 × 0.01 = 100 stars. Round up to the decimal precision in fulfillment.asset_scale using decimal arithmetic. See Pricing to set the rate and Price fractional assets for rounding examples.
For a UNIT_BASED gift card, you have already chosen a fixed value and currency during setup. Show that value and use unit_cost as the asset price. The participant does not need to choose a value.
Redeem
When the participant confirms their choice, submit the reward ID and card value:fulfillment; omit the custom-reward amount field. Each redemption orders one card, so omit quantity or set it to 1.
Send the price the participant reviewed as expected_amount, in asset units. If the current cost differs, Scrip returns 409 reward_price_changed without creating an order or reserving assets. Fetch the catalog again and ask the participant to confirm the updated price. This field is optional, but recommended whenever you show a price before redeeming.
For fixed-value cards, also send the value and currency the participant reviewed. Scrip rejects the request if either has changed. You can omit them with fulfillment: {} when you want to use the card’s current settings without this check.
Use a unique idempotency_key for each purchase. If a request times out, retry the same request with the same key to retrieve the existing redemption. Its original charge is preserved even if the catalog price changes later.
Scrip first reserves the cost in the participant’s HELD balance, then orders the card. Once the order succeeds, it captures that balance to the program’s redemption target (SYSTEM_REDEMPTION by default). If fulfillment fails, it releases the remaining reserved balance. Scrip handles completion automatically; omit capture from the request.
The request waits up to about 30 seconds for the result. A successful response can include the claim link immediately. Relevant fields are shown below:
status to decide what to show:
A new redemption returns HTTP
201, including when it is still pending. A retry with the same idempotency key returns the existing redemption with 200.
Deliver the claim link
A claim link opens the page where the participant accesses their gift card. Showfulfillment.claim_url from the redemption response when it is present.
To retrieve a link after the order finishes, or when the participant returns later, use the same redemption ID:
expires_at appears only when a link expiry is available. The endpoint can return the same URL on later requests. Reading a redemption or receiving a webhook does not return a claim link.
A missing link does not mean the purchase failed. Retrieve it for the existing redemption so the participant is not charged for another card. See Create a claim link for error handling.
Handle a pending order
Subscribe toredemption.fulfillment_succeeded and redemption.fulfillment_failed to receive the outcome. On success, retrieve the claim link for that redemption. You can also check its status with GET /v1/redemptions/{id}. To return immediately when creating a redemption, send the Prefer: respond-async header.
If fulfillment.status is AWAITING_FUNDS, add funds to your fulfillment account in the dashboard. Scrip retries the order automatically and sends fulfillment_account.funds_low once for that fulfillment.
The participant’s reserved balance stays held while the order waits. If the funding window expires, the order fails and the remaining reserved balance is released. The default window is 24 hours; the redemption’s reservation deadline can end the wait sooner.
Scrip controls the order’s completion. Cancellation is available only before an order is placed, and a delivered gift card cannot be reversed through Scrip. See Get redemption for status and failure details, and Redemption lifecycle for reservation deadlines and ledger entries.
Set redemption limits
You can limit each card’s value and how many cards a participant redeems over a rolling period. For example, allow cards worth up to USD 100.00 each, with at most three cards totaling USD 250.00 per participant over 24 hours. Configure these limits on the program; Scrip checks them before reserving any balance. See Update a program for the fields and validation rules. To stop new gift-card redemptions for an account, disable it in the dashboard.Choose cards and prices
Configure the gift cards in your program’s catalog.
Receive order updates
Handle completed orders, failures, and low account balances.
Track gift-card costs
Review orders by program, status, and currency.