Partner Grant API

Overview

The Partner Grant API lets you gate a Nibble reward behind logic that lives in your own systems — “registered in the app”, “uploaded a valid receipt” — while Nibble remains the single issuer of the redeemable reward.

You call one endpoint to say “this person qualified — issue their reward”. Nibble checks the per-person cap, dedups, mints the claim, and returns a hosted redemption URL. Everything downstream — venue redemption, fraud control, PO settlement, reporting — is handled by Nibble.

Try it in Postman

Run the whole contract before writing any code: a grant, both status reads, and every documented error — each with assertions, so the Runner reports pass or fail per rule.

Scope

Responsibility is split along one clean seam. You own qualification; Nibble owns entitlement, dedup and issuance — because Nibble owns the redemption (the redeemable claim and the PO-funded payout pool).

Nibble never validates receipts or app registrations, and never receives receipt contents. It stores only an opaque reference for audit. With the Nibble Partner Grant API, you decide when to issue a reward.

Base URL & versioning

All requests are JSON over HTTPS. The API is versioned in the path; v1 is current.

A campaign must have its entry point set to api in the Campaign Manager to accept grants. Campaigns which are not set up as API-eligible reject API calls with 403 not_api_campaign.

Authentication

Authenticate with a bearer token you generate in the Nibble Campaign Manager — under Settings → API keys, available once a campaign uses the API handoff. Each key is an opaque secret behind an environment prefix — nib_live_ or nib_test_ — so you can tell at a glance which one you are holding. It is shown once at creation and cannot be retrieved afterwards — by you or by Nibble — so store it somewhere safe. Lost a key? Issue a replacement and revoke the old one.

Authorization: Bearer nib_live_<your key>
# test keys use the nib_test_ prefix

• Scope. Prefer one key per campaign. A key scoped to another campaign or org is rejected with 403 campaign_not_authorized.
• Environments. live and test keys are distinct; test keys never touch real settlement.
• Rotation. Revoke a key and issue a replacement from the Campaign Manager; both can be live briefly for zero-downtime rotation.
• Rate limits. Per key: at least 10 requests per second sustained, and short bursts above that. Over the limit returns 429 with a Retry-After header in seconds — wait it out and retry. A retry cannot double-issue: the same person and eligibilityRef replays the original claim.
• Transport. HTTPS only.

Create a grant

Call this once a person has qualified in your system. The response is a hosted redemption URL you display in your app or send to the consumer.

POST /api/v1/campaigns/cmp_summer_free_pour/grants
Authorization: Bearer nib_live_xxxxxxxxxxxxxxxxxxxx
Idempotency-Key: 5f3c…            # optional; see Cap & idempotency
Content-Type: application/json

{
  "externalUserId": "hk_8f2a91",              # REQUIRED — the per-person cap counts on this
  "email": "[email protected]",         # REQUIRED — stored + used if Nibble delivers
  "eligibilityRef": "receipt_20260602_4471", # the qualifying-event id; REQUIRED when perUserLimit > 1
  "venueId": "ven_…",                      # optional — pre-bind to a venue
  "delivery": "url"                        # optional — "url" (default) | "email"
}

Request body

Responses

201 Created — fresh grant

{
  "claimId": "rid_a1b2c3d4e5f6",
  "redemptionUrl": "https://claim.nibble-app.io/c/cmp_summer_free_pour?claim=rid_a1b2c3d4e5f6",
  "state": "valid",
  "expiresAt": "2026-06-02T12:10:00Z",
  "alreadyGranted": false
}

201 Created — when Nibble sends the email

With "delivery": "email" the same body carries one extra object. A failed send never fails the grant — you still get the redemptionUrl and can deliver it yourself.

{
  … same fields as above …
  "delivery": { "method": "email", "sent": true, "detail": "sent" }
}

200 OK — idempotent replay

The same (person, grant_ref) already issued a claim. You get the same body as the 201 with "alreadyGranted": true — safe to re-call and re-show the reward.

In your backend

The same call as it lives in your own qualification path. There is no SDK — it is one HTTPS request.

// After your own logic decides this person qualified:
const res = await fetch(
  `https://api.nibble-app.io/api/v1/campaigns/${CAMPAIGN_ID}/grants`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NIBBLE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      externalUserId: user.id,     // your stable user id
      email: user.email,
      eligibilityRef: receipt.id,  // one per qualifying event — makes retries safe
    }),
  },
);
const grant = await res.json();

if (res.ok) {
  // 201 fresh or 200 replay — same shape either way.
  showInApp(grant.redemptionUrl);
} else if (grant.error === "limit_reached") {
  // Person already has their reward(s); grant.claimId points at the existing one.
} else {
  // Branch on grant.error — see the error reference below.
}

import os, requests

res = requests.post(
    f"https://api.nibble-app.io/api/v1/campaigns/{CAMPAIGN_ID}/grants",
    headers={"Authorization": f"Bearer {os.environ['NIBBLE_API_KEY']}"},
    json={
        "externalUserId": user.id,
        "email": user.email,
        "eligibilityRef": receipt.id,
    },
    timeout=10,
)
grant = res.json()

if res.ok:
    show_in_app(grant["redemptionUrl"])  # 201 fresh or 200 replay
elif grant["error"] == "limit_reached":
    ...  # person already has their reward(s)

Prefer to run it first? The Postman collection exercises every call on this page, with assertions.

Error reference

Every error shares the shape { "error": "<code>", "message": "<text>" }, sometimes with extra fields (state, claimId, reason, retryAfter). Branch on the code, not the prose — messages are English (you map them to consumer copy in your own language).

Every response also carries a requestId, repeated in the X-Request-Id header. Log it. Quoting one lets us find the exact call in seconds instead of asking you to reproduce it.

{
  "error": "limit_reached",
  "message": "This person has already received the maximum number of rewards for this campaign.",
  "claimId": "rid_a1b2c3d4e5f6",
  "state": "used"
}

Cap & idempotency

The design keeps two counters separate. The cap counts people, so a perUserLimit = 3 campaign can issue three rewards; idempotency counts events, so a retry of one event never issues a second. Nibble applies both on every call.

• perUserLimit = 1 (~90% of campaigns): eligibilityRef is optional. One claim per person; a second call replays or hits limit_reached.
• perUserLimit > 1: send a distinct eligibilityRef per qualifying event — it’s the only way to tell “a second receipt → a second reward” from “the server retried”. Missing it → 400 grant_ref_required.

Redemption handoff

The API returns a hosted redemptionUrl — not raw reward data. You embed or open that URL in your app, or email it to the consumer. The page renders Nibble’s branded confirmation and QR, and drives venue redemption + PO accounting, so your codebase never forks reward logic.

• Return-only — "delivery": "url", the default: Nibble returns the URL; you display or send it. Cleanest for in-app embedding.
• Nibble-emailed — "delivery": "email": Nibble also emails the reward to email using its templates, and still returns the URL.

Security & audit

• Single issuer. Only Nibble mints redeemable claims — you never hold reward inventory.
• Keys cannot be read back. A key is shown once at creation and is never recoverable from Nibble afterwards. Revocation takes effect on the next call.
• Rate limiting. Every key is throttled independently, so one integration's burst cannot slow another's.
• Auditable. Every grant and rejection writes an org-scoped audit row keyed to the partner key, storing a hash of the person key plus the opaque eligibilityRef — never receipt contents.
• No PII overreach. Nibble stores email (as for consumer claims) and opaque refs; it never receives or stores receipt images, or other PII data.

Status endpoints

Companion read endpoints let you check state without issuing. Same bearer auth and rate limits as the grants endpoint.

A person’s standing on the campaign — no claim is issued. Zero grants is a normal 200 with granted: 0. Use it to re-deliver a lost link (redemptionUrl) or to skip the grant call for someone already at the limit.

{
  "externalUserId": "hk_8f2a91",
  "perUserLimit": 2,
  "granted": 2,
  "remaining": 0,
  "atLimit": true,
  "claims": [
    { "claimId": "rid_a1b2c3d4e5f6", "state": "used", "grantRef": "receipt_20260602_4471",
      "redemptionUrl": "https://claim.nibble-app.io/c/cmp_summer/?claim=rid_a1b2c3d4e5f6",
      "createdAt": "2026-06-02T18:11:04.000Z", "usedAt": "2026-06-02T19:40:12.000Z",
      "expiresAt": "2026-07-28T00:00:00.000Z" }
  ]
}

The campaign's current state and what the consumer wins. Poll it to stop granting before you hit funds_depleted, and to render the reward in your own UI.

{
  "id": "cmp_summer",
  "name": "Summer Rewards",
  "rewardLabel": "Heineken 0.0",
  "rewardImageUrl": "https://…/reward-images/cmp_summer/reward.jpg",
  "status": "live",
  "acceptingGrants": true,
  "perUserLimit": 2,
  "startsAt": "2026-06-01T00:00:00.000Z",
  "endsAt": "2026-07-28T00:00:00.000Z",
  "rewardsRemaining": 218
}