Programs

Create a program

Create a new program.

post/v1/programs

Request

  • Base URL: https://api.scrip.dev
  • URL: https://api.scrip.dev/v1/programs
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

A key you choose to make this request safe to retry: 1 to 255 printable ASCII characters. Send the same key with the same request to get the first response again, marked Idempotent-Replayed: true. Routes that return a secret once, and claim links, do not replay a response. Event ingest uses the key as the event's identity.

Request body

descriptionstring

Optional program description

fulfillment_max_face_value_minorinteger

Maximum face value of one gift-card redemption, in fiat minor units. The cap is compared as a bare minor-unit number against a redemption in whatever currency the reward uses, because the program has no currency. Omit for no limit.

fulfillment_mode'INSTANT' | 'ASYNC'

Default redemption behavior when capture is omitted. Defaults to INSTANT.

fulfillment_participant_max_amount_minorinteger

Maximum total face value per participant in the rolling period, in fiat minor units. The cap is compared as a bare minor-unit number against a redemption in whatever currency the reward uses, because the program has no currency. Counts the same order statuses as fulfillment_participant_max_count. Omit for no limit.

fulfillment_participant_max_countinteger

Maximum gift-card redemptions per participant in the rolling period. Counts PENDING, PROCESSING, AWAITING_FUNDS, and SUCCEEDED orders. Omit for no limit.

fulfillment_participant_window_secondsinteger

Rolling period, in seconds, used for each participant's gift-card limits. Required when either limit is set.

namestring required

The name of the rewards program. It must be unique in your organization.

on_unknown_participant'CREATE' | 'REJECT'

How to handle events for unregistered participants. Defaults to CREATE when absent or null; an explicit "" or any non-enum value is rejected.

pending_redemption_ttlstring nullable

Optional program-specific bound between 60 seconds and one year, such as 90d or 720h. Without a request or program bound, pending redemptions default to 90 days.

Example request

{
  "description": "Quarterly sales incentive program for the sales team",
  "fulfillment_max_face_value_minor": 10000,
  "fulfillment_mode": "ASYNC",
  "fulfillment_participant_max_amount_minor": 25000,
  "fulfillment_participant_max_count": 3,
  "fulfillment_participant_window_seconds": 86400,
  "name": "Acme Rewards",
  "on_unknown_participant": "CREATE",
  "pending_redemption_ttl": "24h"
}

Response

Program created

created_atstring date-time

When the program was created

deleted_atstring date-time

Set when the program is archived

descriptionstring

Optional program description

fulfillment_max_face_value_minorinteger

Maximum face value of one gift-card redemption, in fiat minor units. The cap is compared as a bare minor-unit number against a redemption in whatever currency the reward uses, because the program has no currency. Absent means unlimited.

fulfillment_mode'INSTANT' | 'ASYNC'

Default redemption behavior when capture is omitted

fulfillment_participant_max_amount_minorinteger

Maximum total face value per participant in the rolling period, in fiat minor units. The cap is compared as a bare minor-unit number against a redemption in whatever currency the reward uses, because the program has no currency. Counts the same order statuses as fulfillment_participant_max_count. Absent means unlimited.

fulfillment_participant_max_countinteger

Maximum gift-card redemptions per participant in the rolling period. Counts PENDING, PROCESSING, AWAITING_FUNDS, and SUCCEEDED orders. Absent means unlimited.

fulfillment_participant_window_secondsinteger

Rolling period, in seconds, used for each participant's gift-card limits. Present only when at least one limit is set.

idstring uuid

The id of the program. Use it in program_id fields and paths.

namestring

The name of the rewards program.

on_unknown_participantstring

How events for unregistered participants are handled

pending_redemption_ttlstring

Optional program-specific bound between 60 seconds and one year. Without a request or program bound, pending redemptions default to 90 days.

redemption_target_entity_idstring uuid

Ledger entity id of the group or program wallet that receives redeemed value. Present only when redemption_target_type is LEDGER_ENTITY.

redemption_target_type'SYSTEM_REDEMPTION' | 'SYSTEM_BREAKAGE' | 'LEDGER_ENTITY'

Where redeemed value is posted.

status'ACTIVE' | 'SUSPENDED' | 'ARCHIVED'

The rewards program's lifecycle state.

updated_atstring date-time

When the program was last modified

Example response

{
  "created_at": "2027-01-15T10:30:00Z",
  "deleted_at": "2027-01-15T10:30:00Z",
  "description": "Quarterly sales incentive program",
  "fulfillment_max_face_value_minor": 10000,
  "fulfillment_mode": "INSTANT",
  "fulfillment_participant_max_amount_minor": 25000,
  "fulfillment_participant_max_count": 3,
  "fulfillment_participant_window_seconds": 86400,
  "id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01",
  "name": "Acme Rewards",
  "on_unknown_participant": "CREATE",
  "pending_redemption_ttl": "24h",
  "redemption_target_entity_id": "5e7a9c13-2d4f-4b68-9a0c-e1b3d5f7a920",
  "redemption_target_type": "SYSTEM_REDEMPTION",
  "status": "ACTIVE",
  "updated_at": "2027-01-15T10:30:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.