Incentives

Worked incentives samples

The endpoint list below documents every operation’s parameters; this overlay walks an incentive the way a promotions API actually uses it: browse the provider catalog → issue an incentive → list the issued ledger → handle a redeem or void. Success envelopes are { data, meta }, error envelopes { error, meta } — see How to read a worked sample. The standalone promotions engine is state-projected over the tenant cdp_events ledger (the same append-only store the loyalty layer uses), so issuance is migration-free and a read always converges. For the console-side accounting treatment, see the incentives ledger guide. Every response carries meta.request_id. Quote the request id when you report a credit that landed on the wrong ledger — a support trace needs both the row id and the request id.

1. Browse the provider catalog

GET /api/v1/incentives/providers returns every incentive fulfillment provider the engine can call: the internal Orbit reward-code minter and manual-fulfillment recorder, plus external gift-card networks (Tremendous, Tango) that stay descriptors until you connect credentials. Use this to drive the reward-source picker or to decide which provider_id to pin on the issue call. Each row carries configured — true when the engine can dispatch right now, false for an external network awaiting credentials.

curl -X GET "https://api.orbit.devotel.io/api/v1/incentives/providers" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/incentives/providers",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": [
    {
      "id": "orbit_code",
      "name": "Orbit reward code",
      "kind": "internal",
      "rewardTypes": ["discount_code"],
      "currencies": ["*"],
      "configured": true,
      "description": "Mints a unique, redeemable discount / coupon code the recipient can apply. Fulfilled instantly inside Orbit — no third-party account."
    },
    {
      "id": "orbit_manual",
      "name": "Manual fulfillment",
      "kind": "internal",
      "rewardTypes": ["custom"],
      "currencies": ["*"],
      "configured": true,
      "description": "Records a structured payout the tenant fulfils through its own webhook or operations workflow. Tracks status without dispatching."
    },
    {
      "id": "tremendous",
      "name": "Tremendous",
      "kind": "external",
      "rewardTypes": ["gift_card"],
      "currencies": ["USD", "EUR", "GBP", "CAD", "AUD"],
      "configured": false,
      "description": "Global gift-card + prepaid rewards network. Available once your Tremendous API credentials are connected."
    }
  ],
  "meta": {
    "request_id": "req_inc_providers",
    "timestamp": "2026-10-09T12:00:00.000Z"
  }
}

2. Get a single provider

GET /api/v1/incentives/providers/{id} returns one provider descriptor — the same shape each catalog row carries. Use it to render the detail behind a reward-source picker, or to confirm a provider_id you pinned on issue is still configured. An unknown id returns 404 NOT_FOUND.

curl -X GET "https://api.orbit.devotel.io/api/v1/incentives/providers/orbit_code" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/incentives/providers/orbit_code",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "id": "orbit_code",
    "name": "Orbit reward code",
    "kind": "internal",
    "rewardTypes": ["discount_code"],
    "currencies": ["*"],
    "configured": true,
    "description": "Mints a unique, redeemable discount / coupon code the recipient can apply. Fulfilled instantly inside Orbit — no third-party account."
  },
  "meta": {
    "request_id": "req_inc_provider",
    "timestamp": "2026-10-09T12:00:30.000Z"
  }
}

3. Issue an incentive

POST /api/v1/incentives/issue creates one incentive — a credit, a discount code, a gift card, or a custom payout — and records the outcome on the tenant cdp_events ledger. The body takes reward_type (one of credit, discount_code, gift_card, custom), optional amount / currency, an optional provider_id (when omitted the engine picks a default per reward type), a recipient (contact_id and/or email), and freeform metadata. A write of this kind is gated to owner, admin, or developer roles — the same guard the referral reward-payout surface uses. Send an Idempotency-Key header (or idempotency_key field) to replay the original result on retry; a replay returns 200 with replayed: true rather than minting again.

curl -X POST "https://api.orbit.devotel.io/api/v1/incentives/issue" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reward_type": "discount_code",
  "amount": 25,
  "source_ref": "aug-winback",
  "recipient": { "contact_id": "ct_3k9m2a8f1e4b6c7d" },
  "metadata": { "campaign": "aug-winback" }
}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/incentives/issue",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      reward_type: "discount_code",
      amount: 25,
      source_ref: "aug-winback",
      recipient: { contact_id: "ct_3k9m2a8f1e4b6c7d" },
      metadata: { campaign: "aug-winback" },
    }),
  },
);
console.log(await res.json());

201

{
  "data": {
    "id": "ipo_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f",
    "status": "issued",
    "fulfillment_status": "issued",
    "source": "api",
    "source_ref": "aug-winback",
    "provider_id": "orbit_code",
    "reward_type": "discount_code",
    "recipient_contact_id": "ct_3k9m2a8f1e4b6c7d",
    "recipient_email": null,
    "amount": 25,
    "currency": null,
    "code": "ORBIT-WINBACK-4KQJ",
    "reference": null,
    "reason": null,
    "idempotency_key": null,
    "issued_at": "2026-10-09T12:01:00.000Z",
    "redeemed_at": null,
    "voided_at": null,
    "metadata": { "campaign": "aug-winback" },
    "replayed": false
  },
  "meta": {
    "request_id": "req_inc_issue",
    "timestamp": "2026-10-09T12:01:00.000Z"
  }
}

4. List the issued ledger

GET /api/v1/incentives/issued returns every incentive the tenant has issued, newest first, each row folded to its current lifecycle status (issued, redeemed, or voided). Filter by status, source, reward_type, or contact_id; page with limit (1–200, default 50) and offset. Use this to drive a win-back report or the org’s own incentive audit before you call redeem or void.

curl -X GET "https://api.orbit.devotel.io/api/v1/incentives/issued?limit=50&offset=0" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/incentives/issued?limit=50&offset=0",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": [
    {
      "id": "ipo_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f",
      "status": "issued",
      "fulfillment_status": "issued",
      "source": "api",
      "source_ref": "aug-winback",
      "provider_id": "orbit_code",
      "reward_type": "discount_code",
      "recipient_contact_id": "ct_3k9m2a8f1e4b6c7d",
      "recipient_email": null,
      "amount": 25,
      "currency": null,
      "code": "ORBIT-WINBACK-4KQJ",
      "reference": null,
      "reason": null,
      "idempotency_key": null,
      "issued_at": "2026-10-09T12:01:00.000Z",
      "redeemed_at": null,
      "voided_at": null,
      "metadata": { "campaign": "aug-winback" }
    },
    {
      "id": "ipo_a3c7e9d2b1f5480a9e7d6c5b4a3210f",
      "status": "redeemed",
      "fulfillment_status": "issued",
      "source": "api",
      "source_ref": "support-ticket-4891",
      "provider_id": "orbit_manual",
      "reward_type": "gift_card",
      "recipient_contact_id": null,
      "recipient_email": "customer@example.com",
      "amount": 2500,
      "currency": "USD",
      "code": null,
      "reference": "order-99821",
      "reason": null,
      "idempotency_key": "ticket-4891-gc-001",
      "issued_at": "2026-10-09T11:45:00.000Z",
      "redeemed_at": "2026-10-09T12:00:00.000Z",
      "voided_at": null,
      "metadata": { "channel": "web" }
    },
    {
      "id": "ipo_d5b1a7c3e9f240b8a7c6d5e4b3210a9f",
      "status": "voided",
      "fulfillment_status": "issued",
      "source": "api",
      "source_ref": "promo-week-41",
      "provider_id": "orbit_code",
      "reward_type": "discount_code",
      "recipient_contact_id": "ct_7e5b3a1c9d4f6e8b",
      "recipient_email": null,
      "amount": 10,
      "currency": null,
      "code": "ORBIT-PROMO-9X2M",
      "reference": null,
      "reason": "customer-requested-cancel",
      "idempotency_key": null,
      "issued_at": "2026-10-09T11:30:00.000Z",
      "redeemed_at": null,
      "voided_at": "2026-10-09T11:35:00.000Z",
      "metadata": {}
    }
  ],
  "meta": {
    "request_id": "req_inc_ledger",
    "timestamp": "2026-10-09T12:02:00.000Z",
    "pagination": { "cursor": null, "has_more": false }
  }
}

5. Redeem an issued incentive

POST /api/v1/incentives/{id}/redeem marks an issued incentive as redeemed — the recipient applied the code, the gift card was spent, the custom payout was fulfilled. The call appends an incentive.redeemed event under a per-incentive advisory lock, so two concurrent redemptions cannot both consume the same incentive. Only an issued incentive can be redeemed; a terminal one (already redeemed or voided) returns 409. Pass an optional reference (the order or ticket that consumed it) and freeform metadata; the response returns the row in its post-redeem state with status: "redeemed" and redeemed_at set.

curl -X POST "https://api.orbit.devotel.io/api/v1/incentives/ipo_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f/redeem" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reference": "ord_9z4t7q2"
}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/incentives/ipo_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f/redeem",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ reference: "ord_9z4t7q2" }),
  },
);
console.log(await res.json());

200

{
  "data": {
    "id": "ipo_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f",
    "status": "redeemed",
    "fulfillment_status": "issued",
    "source": "api",
    "source_ref": "aug-winback",
    "provider_id": "orbit_code",
    "reward_type": "discount_code",
    "recipient_contact_id": "ct_3k9m2a8f1e4b6c7d",
    "recipient_email": null,
    "amount": 25,
    "currency": null,
    "code": "ORBIT-WINBACK-4KQJ",
    "reference": "ord_9z4t7q2",
    "reason": null,
    "idempotency_key": null,
    "issued_at": "2026-10-09T12:01:00.000Z",
    "redeemed_at": "2026-10-09T12:03:00.000Z",
    "voided_at": null,
    "metadata": {}
  },
  "meta": {
    "request_id": "req_inc_redeem",
    "timestamp": "2026-10-09T12:03:00.000Z"
  }
}

A second redeem (or a void after redeem) returns 409 CONFLICT with the current lifecycle in error.details so your client can branch instead of retrying:

409

{
  "error": {
    "code": "CONFLICT",
    "message": "Incentive ipo_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f is redeemed and cannot be redeemed.",
    "status": 409,
    "details": { "reason": "already_redeemed", "status": "redeemed" }
  },
  "meta": {
    "request_id": "req_inc_redeem_err",
    "timestamp": "2026-10-09T12:03:30.000Z"
  }
}

6. Void an issued incentive

POST /api/v1/incentives/{id}/void cancels an issued incentive — the code was returned unused, the recipient opted out, the payout was reversed. The call appends an incentive.voided event under the same per-incentive advisory lock; only an issued incentive can be voided, and a terminal one returns 409. Pass an optional reason; the response returns the row in its voided state with status: "voided" and voided_at set.

curl -X POST "https://api.orbit.devotel.io/api/v1/incentives/ipo_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f/void" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "customer-requested-cancel"
}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/incentives/ipo_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f/void",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ reason: "customer-requested-cancel" }),
  },
);
console.log(await res.json());

200

{
  "data": {
    "id": "ipo_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f",
    "status": "voided",
    "fulfillment_status": "issued",
    "source": "api",
    "source_ref": "aug-winback",
    "provider_id": "orbit_code",
    "reward_type": "discount_code",
    "recipient_contact_id": "ct_3k9m2a8f1e4b6c7d",
    "recipient_email": null,
    "amount": 25,
    "currency": null,
    "code": "ORBIT-WINBACK-4KQJ",
    "reference": null,
    "reason": "customer-requested-cancel",
    "idempotency_key": null,
    "issued_at": "2026-10-09T12:01:00.000Z",
    "redeemed_at": null,
    "voided_at": "2026-10-09T12:04:00.000Z",
    "metadata": {}
  },
  "meta": {
    "request_id": "req_inc_void",
    "timestamp": "2026-10-09T12:04:00.000Z"
  }
}

7. Errors

Errors follow the { error, meta } envelope. Two failures every promotions integrator hits: 403 — role too low for a write.

403

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "This action requires one of: owner, admin, developer",
    "status": 403
  },
  "meta": {
    "request_id": "req_inc_err",
    "timestamp": "2026-10-09T12:05:00.000Z"
  }
}

422 — unknown provider or wrong reward semantics. An override that names a provider the catalog cannot resolve, or an amount that picks a negative debit:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Unknown provider id; check /incentives/providers for allowed values.",
    "status": 422
  },
  "meta": {
    "request_id": "req_inc_err2",
    "timestamp": "2026-10-09T12:05:30.000Z"
  }
}

409 — already terminal. A redeem or void against an incentive that is already redeemed or voided:

409

{
  "error": {
    "code": "CONFLICT",
    "message": "Incentive ipo_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f is redeemed and cannot be voided.",
    "status": 409,
    "details": { "reason": "already_redeemed", "status": "redeemed" }
  },
  "meta": {
    "request_id": "req_inc_err3",
    "timestamp": "2026-10-09T12:06:00.000Z"
  }
}

API Reference

All Endpoints

Worked incentives samples

1. Browse the provider catalog

2. Get a single provider

3. Issue an incentive

4. List the issued ledger

5. Redeem an issued incentive

6. Void an issued incentive

7. Errors

​Worked incentives samples

​1. Browse the provider catalog

​2. Get a single provider

​3. Issue an incentive

​4. List the issued ledger

​5. Redeem an issued incentive

​6. Void an issued incentive

​7. Errors

Worked incentives samples

1. Browse the provider catalog

2. Get a single provider

3. Issue an incentive

4. List the issued ledger

5. Redeem an issued incentive

6. Void an issued incentive

7. Errors