Gift Cards & Rewards API #

Programmatic read + reporting access to your gift card / reward program: orders, analytics, available products, manual-pool inventory, spend limits, and account settings.

Auth & scope. All endpoints are under https://app.ecardwidget.com/v2/api/gift-card/… and use your Bearer API key (Authorization: Bearer <YOUR_API_KEY>). The key must have the gift_cards feature scope. Every request is tenant-scoped to the account that owns the key.

What the API does not do. There is no "send a gift card" endpoint. Rewards are attached to a send on another surface — your widget, a campaign, or an automation — and fulfilled from there. And every state-changing gift card action (cancel, rescind, reveal a code, change a spend limit, connect a provider key) is OTP-gated in the dashboard and cannot be driven by an API key. The API is therefore read / reporting only. Use it to sync order status, reconcile spend, and monitor limits from your own systems.

The reward model (concepts) #

Rewards run in one of two provider modes (byok_provider on your account):

Mode byok_provider Source of value Order status after send
Giftbit (BYOK) giftbit Your own connected Giftbit wallet/API key byok_prepaid → fulfilled
Manual rewards manual A pool of codes you upload (pre-purchased) fulfilled (assigned a pooled code)
  • BYOK = Bring Your Own Key. You connect your Giftbit account; ECW never holds the funds. Enterprise.
  • Manual pools = you upload batches of your own reward codes (gift cards, store credit, custom). A send assigns the next available code; an empty pool blocks new sends.
  • Recipients claim via an emailed link (OTP-verified). Giftbit "embedded" rewards are often auto-redeemed on the provider side, so a fulfilled order can read claim_status: unclaimed in ECW while the provider already shows it redeemed.
  • Spend guardrails: every card is bounded by an account per-card min/max, and optional velocity limits (per-hour/day/month amount + per-day/month card counts). Velocity enforcement is a master toggle — limits can exist while enforcement is off, in which case nothing is capped.

Currency is USD only for the reward subsystem.

Account settings — GET /v2/api/gift-card/getSettings #

Returns your reward configuration.

curl https://app.ecardwidget.com/v2/api/gift-card/getSettings \
  -H "Authorization: Bearer $ECW_API_KEY"

Response data #

{
  "approved": true,
  "per_card_min": 5.00,
  "per_card_max": 100.00,
  "byok_enabled": true,
  "byok_provider": "giftbit",
  "byok_sandbox": false,
  "stripe_connected": true,
  "velocity_limits_enabled": false
}

velocity_limits_enabled: false means limits are not enforced even if rules exist (see below).

Available products — GET /v2/api/gift-card/listProducts #

The reward brands/products available to your account. For Giftbit this is your provider catalog; for manual mode it's the brands present in your pool.

Query param Notes
country optional ISO country filter (e.g. US) 
curl "https://app.ecardwidget.com/v2/api/gift-card/listProducts?country=US" \
  -H "Authorization: Bearer $ECW_API_KEY"

data is an array of products: { "id": "amazonus", "name": "Amazon.com", "min": 1, "max": 2000, … } (manual mode returns brand-label–keyed entries with the specific denominations your pool holds).

List orders — GET /v2/api/gift-card/listOrders #

Paginated reward orders across all send surfaces (widget, campaign, automation).

Query param Notes
page, perPage pagination (perPage default 20)
payment_status pending, byok_prepaid, paid, cancelled, refunded, …
fulfillment_status pending, processing, fulfilled, failed, paused, rescinded, cancelled, cancellation_pending_manual_review, cancellation_reviewed, expired
claim_status unclaimed, claimed
scope widget, campaign, automation
campaign_id, automation_id filter to one campaign/automation
dateFrom, dateTo ISO dates

Do not send ownerid/user_id — the account is derived from your key; passing them returns an empty result (tamper guard).

curl "https://app.ecardwidget.com/v2/api/gift-card/listOrders?fulfillment_status=fulfilled&perPage=50" \
  -H "Authorization: Bearer $ECW_API_KEY"

Response #

{
  "success": true,
  "data": [
    {
      "id": 18,
      "scope": "automation",
      "provider": "giftbit",
      "denomination": 50.00,
      "currency_code": "USD",
      "payment_status": "byok_prepaid",
      "fulfillment_status": "fulfilled",
      "claim_status": "unclaimed",
      "product_name": "Nintendo eShop",
      "recipient_email": "[email protected]",
      "recipient_name": "Jordan",
      "campaign_id": null,
      "automation_id": 42,
      "has_reveal": true,
      "createdat": "2026-07-02 23:15:03"
    }
  ],
  "meta": { "total_count": 1, "per_page": 50, "page_count": 1, "page": 1 }
}

Reward codes/links are masked in list responses (anti-scrape). Revealing a full code is an OTP-gated dashboard action.

Analytics — GET /v2/api/gift-card/analytics #

Aggregate reward metrics for the account (counts and totals by status, claim rate, spend). Returns a summary object in data. Pair with listOrders for line-item detail.

curl https://app.ecardwidget.com/v2/api/gift-card/analytics \
  -H "Authorization: Bearer $ECW_API_KEY"

Manual-pool inventory — GET /v2/api/gift-card/rewardInventory, GET /rewardBatches #

For manual mode: how many codes remain, by brand/denomination.

curl https://app.ecardwidget.com/v2/api/gift-card/rewardInventory \
  -H "Authorization: Bearer $ECW_API_KEY"

rewardInventory → array of { "face_value": 25.00, "currency_code": "USD", "brand_label": "Amazon", "reward_type": "gift_card", "status": "available", "count": 140 }. rewardBatches → the upload batches those codes came from. Use inventory to alert before a pool runs dry.

Velocity / spend limits — GET /v2/api/gift-card/getRules #

The configured spend guardrails and current usage. Read-only via API — raising or disabling a limit, or toggling enforcement, is owner-only and OTP-gated in the dashboard.

curl https://app.ecardwidget.com/v2/api/gift-card/getRules \
  -H "Authorization: Bearer $ECW_API_KEY"

Response data #

[
  { "id": 3, "rule_type": "max_amount_per_day", "scope": "all", "max_value": 50000.00, "enabled": true, "current_usage": 1250.00, "percentage": 3 },
  { "id": 7, "rule_type": "max_cards_per_day",  "scope": "all", "max_value": 500,      "enabled": true, "current_usage": 12,      "percentage": 2 }
]

Rule types: max_amount_per_hour|day|month, max_cards_per_day|month. Remember: usage is tracked regardless of enforcement — check getSettings.velocity_limits_enabled to know whether these are actually being applied.

Reconciliation & audit #

  • GET /v2/api/gift-card/exportOrders — CSV export of orders (same filters as listOrders).
  • GET /v2/api/gift-card/getAuditLog — the reward audit trail (order created/fulfilled, claims, limit changes, cancellations, etc.), with actor and (for cooperator actions) origin.

Where sending happens #

To actually issue rewards, enable gift cards on the surface that sends the eCard:

  • Widget — turn on gift cards in the widget builder; the sender adds a reward at checkout (sender-paid via Stripe for widget sends).
  • Campaign — attach a reward to a campaign; charged/funded per your provider mode.
  • Automation — enable rewards on a birthday/anniversary/etc. automation (see automations.md); rewards are attached automatically when the automation fires.

Once sent, track and reconcile every resulting order through the endpoints above.

← PreviousAutomationsNext →Webhooks
Documentation
Getting Started