Incentives & Offers

Overview

The incentives domain turns a checkout_session into decisions: which offers a customer qualifies for, why, and what they are worth. You resolve a feed, present it, then record what the customer did with each offer, including the offers they did not take. Those non-selections are counterfactuals, and they are how the Brain learns.

One rule frames the whole domain: the richest offer feed is the session-anchored one, because it resolves against both the basket and the identity on the session. The customer-only feed resolves on identity alone and scores lower.

The session-anchored offer feed (Planned)

GET /v1/partner/checkout/sessions/{id}/offers is the primary offer surface. It resolves offers eligible for the basket lines and the identity attached to the session, so its feed is materially richer than the identity-only feed. Call it after identity attaches and before tender, so the cashier can present offers and the exposure is captured.

The feed returns an OfferFeed. Each Offer carries a shape, a value, the redemption methods it supports, an expiry, and a reasoning card. The response meta.decision_trace_id is the attribution carrier: one opaque, replay-stable string per intelligence-bearing response. Persist it. It is the thread that ties an exposure to a later redemption to an attribution report.

curl https://api.feddi.io/v1/partner/checkout/sessions/9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f/offers \
  -H "Authorization: Bearer <terminal-jwt>"

{
  "ok": true,
  "data": {
    "session_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "offers": [
      {
        "offer_id": "off_3a9c1e44",
        "campaign_id": "camp_77b21a09",
        "title": "20% off your next coffee",
        "offer_shape": "PERCENT_DISCOUNT",
        "value": { "amount_minor": 0, "currency": "QAR", "percent_bps": 2000 },
        "min_basket_minor": 2000,
        "redemption_methods": ["qr", "otp", "short_code"],
        "target_branches": ["br_doha_01"],
        "expires_at": "2026-06-30T20:59:59Z",
        "reasoning": {
          "source": "rule",
          "confidence": 0.82,
          "merchant_attribution": "Summer espresso push",
          "rationale": "Basket contains an eligible espresso SKU and customer is a returning weekday visitor.",
          "expected_value_minor": null
        },
        "trace_id": null
      }
    ],
    "next_cursor": null,
    "has_more": false
  },
  "error": null,
  "meta": {
    "request_id": "req_0b9d3f21",
    "idempotency_replayed": false,
    "api_version": "2026-06-01",
    "data_completeness_score": 88,
    "decision_trace_id": "dt_4f2a8c10"
  }
}

Capture both selection and non-selection (Planned)

After you resolve the feed, you record what happens to each offer against the customer. These four operations are the counterfactual surface. Selection is one data point. Non-selection is the more valuable one, because most systems never record it.

The three non-selection states the Brain learns from are eligible_not_shown, shown_not_chosen, and chosen_not_redeemed. Resolving the session feed attaches the exposure automatically when the session closes; apply, redeem, dismiss, and release make the per-offer outcome explicit. Read Data Maximization for the full reciprocity contract.

Reasoning, audit, and proposals (Planned)

Every offer is explainable, and offers that need approval go through a queue.

• GET /offers/{offerId}/reasoning returns the per-offer reasoning card on its own (source, confidence, merchant_attribution, rationale).
• GET /offers/{offerId}/audit-trail returns the full proposal audit log: reasoning, consent version, and approver.
• GET /proposals lists incentive proposals by status (the approval queue). POST /proposals/{id}/approve fires the offer; POST /proposals/{id}/reject means it does not fire.
• GET /branches/{branchId}/offers is the merchant dashboard list of active offers at a branch.

Budget envelopes: the merchant's incentive control (Planned)

A budget envelope is how a merchant caps incentive spend. It tracks total_budget_minor, spent_minor, reserved_minor, and remaining_minor, plus the channels, offer shapes, and segments it allows.

Updates are compare-and-set guarded. You supply the version you last read, and the update applies only if the envelope is still at that version.

• POST /budget-envelopes creates an envelope (the merchant's primary incentive control).
• GET /budget-envelopes/{id} reads remaining, version, and expiry.
• PATCH /budget-envelopes/{id} updates mutable fields under the CAS guard above.

Promotions, points, templates, and what-if (Planned)

• POST /customers/{customerId}/promotions/apply applies a promo code, tier benefit, or reload bonus to a customer.
• GET /customers/{customerId}/points reads the loyalty points balance, broken out per campaign. POST /customers/{customerId}/points/redeem redeems points for a discount or item (FIFO, atomic).
• GET /offers/eligible pre-renders eligible offer templates with no customer attached. Public and cacheable.
• POST /incentives/evaluate is a read-only basket what-if. It evaluates a transient basket against the rule engine without moving money or persisting anything, and returns the offers that would be eligible plus near-eligible offers with the precise gap ("add 5 QAR more for a free pastry") so the cashier can suggestive-sell. It uses POST because the basket is a body, but it is side-effect-free, and it carries a decision_trace_id.

The PromoGrant ledger (Beta)

GET /v1/partner/customers/{customerId}/grants is callable today. It returns the customer's promotional-money grants and the state-machine state of each. Promotional money is a separate class from actual cash: it expires, it is never cashable, and it is spent first. See Money: Actual vs Promotional.

Filter by state with the state query parameter. The feed is read-only, tenant-scoped, and cursor-paginated.

curl "https://api.feddi.io/v1/partner/customers/wu_4421/grants?state=LOCKED" \
  -H "Authorization: Bearer <terminal-jwt>"

{
  "ok": true,
  "data": {
    "customer_id": "wu_4421",
    "grants": [
      {
        "grant_id": "pg_7781",
        "source": "CASHBACK",
        "state": "LOCKED",
        "amount": { "amount_minor": 1000, "currency": "QAR" },
        "remaining": { "amount_minor": 1000, "currency": "QAR" },
        "accrued_at": "2026-06-01T12:00:00Z",
        "expires_at": "2026-09-01T12:00:00Z",
        "source_event_ref": "odoo:pos.order:5512"
      }
    ],
    "next_cursor": null,
    "has_more": false
  },
  "error": null,
  "meta": {
    "request_id": "req_bb11cc22",
    "idempotency_replayed": false,
    "api_version": "2026-06-01",
    "data_completeness_score": 80,
    "decision_trace_id": null
  }
}

Clawback a grant (Beta, operator-gated)

POST /v1/partner/grants/{id}/clawback reverses a PromoGrant when the source event that funded it is voided or refunded, or for fraud. It is RBAC-gated to ops or admin keys (ApiKeyAuth, not a terminal JWT), and idempotent on the Idempotency-Key header.

A LOCKED grant claws back its full amount. A RELEASED grant claws back the unspent remainder. Any already-spent portion is logged as a merchant marketing loss; it is never pulled back from the customer's actual cash balance, because promotional money never converts to cash.

curl -X POST https://api.feddi.io/v1/partner/grants/pg_7781/clawback \
  -H "x-api-key: <ops-api-key>" \
  -H "Idempotency-Key: 2b3c4d5e-6f70-8192-0314-253647586a7b" \
  -H "Content-Type: application/json" \
  -d '{
    "meta": { "partner_request_id": "2b3c4d5e-6f70-8192-0314-253647586a7b", "occurred_at": "2026-06-05T11:10:00Z", "sent_at": "2026-06-05T11:10:01Z", "api_version": "2026-06-01" },
    "reason": "SOURCE_ORDER_VOIDED",
    "note": "Odoo pos.order 5512 refunded"
  }'

{
  "ok": true,
  "data": {
    "grant_id": "pg_7781",
    "state": "CLAWED_BACK",
    "clawed_back": { "amount_minor": 600, "currency": "QAR" },
    "spent_loss_logged": { "amount_minor": 400, "currency": "QAR" },
    "clawed_at": "2026-06-05T11:10:02Z"
  },
  "error": null,
  "meta": { "request_id": "req_cc22dd33", "idempotency_replayed": false, "api_version": "2026-06-01" }
}

Operations and availability

Where to go next