Programs

A program is your cashback: rates by category, tier multipliers, campaigns, caps, a monthly budget and a holding period. It pays from your vault, in one asset, for spend in the matching currency: USDC for USD, EURe for EUR.

A program is published version by version. A published version never changes: to change a program, publish a new version, which applies to purchases from its effectiveFrom. Each reward records the version that computed it.

Publish a version

You number your versions, so the same request again is safe:

curl -X PUT https://api.sandbox.gave.sh/v1/programs/everyday/versions/1 \
  -H "x-api-key: $GAVE_API_KEY" \
  -H "content-type: application/json" \
  -d @program-version.json

1% on everything, 3% on travel, capped at 50 USDC a month per user, cash withdrawals excluded:

{
  "asset": "USDC",
  "effectiveFrom": "2026-10-12T00:00:00.000Z",
  "categories": [{ "id": "travel", "mccs": ["3000", "4511", "4722", "7011"] }],
  "baseRate": 100,
  "categoryRates": [{ "categoryId": "travel", "rate": 300 }],
  "merchantRates": [],
  "tiers": [],
  "campaigns": [],
  "caps": { "perMonth": "50000000", "categories": [] },
  "exclusions": { "mccs": ["6010", "6011"], "merchants": [] },
  "holdingPeriodDays": 30
}

Rates are in basis points (100 is 1%), amounts in the asset's smallest unit (50000000 is 50 USDC), as strings.

{
  "programId": "everyday",
  "version": 1,
  "effectiveFrom": "2026-10-12T00:00:00.000Z",
  "publishedAt": "2026-10-11T09:00:00.000Z",
  "duplicate": false
}

The same version again answers duplicate: true; other content under its number is a 409: publish a new number.

Rules

• A version comes into force at least 5 minutes after you publish it, so every purchase from then on is evaluated with it, never back-dated.
• A program pays one asset from one vault: every version uses the same asset.
• Eligibility: "eligibility": { "countries": ["FR", "DE"], "segments": ["premium"] } limits a version to users in those countries and segments, as they stood when the purchase was made (see Users). A user without a country or segment is in no list.
• Merchant rates and exclusions need purchases matched to merchants, which comes later: a version that uses them is refused for now, as are referral bonuses.
• At most 50 programs, and 100 versions per program.
• To stop a program, publish a version that pays nothing.

A version that breaks a rule is refused with every reason at once:

{
  "_tag": "ProgramRefused",
  "programId": "everyday",
  "problems": [
    "everyday@v2 pays EURe, not USDC",
    "it comes into force at 2026-10-11T09:01:00.000Z: no sooner than 2026-10-11T09:05:00.000Z, 5 minutes after it's published"
  ]
}

Read your programs

GET /v1/programs lists your programs with their versions, and GET /v1/programs/{programId} reads one.