Grant an offer Coming soon

POST/v1/offers/{id}/grants

Puts a granted offer in up to 500 members' wallets. Each grant becomes a wallet item with source: "offer" and fires reward.issued. The same grant_ref and member never grant twice, so you can safely resume a job that stopped halfway.

Permissions: Secret key with offers:write.

Guide

Run offers from your server

Request headers#

Idempotency-KeystringRequired
Required on this endpoint. Any string up to 255 characters; use a UUID v4. Missing returns 400 idempotency_key_required.
Max Length 255

Path parameters#

idstring (uuid)Required

Request body#

grant_refstringRequired
Your name for this send, up to 128 characters. Reuse it for every batch of the same send.
member_idsarray of string (uuid)Required
1 to 500 member ids.
Max Items 500

Members are skipped, not failed, so one bad id doesn't stop the batch. reason is already_granted, member_not_found, member_deleted, per_member_limit_reached or budget_exhausted.

Response fields#

Returns 200 with GrantResult

grantedinteger
skippedarray of Skipped
Show attributesSkipped
- member_idstring (uuid)
- reasonstring

POST/v1/offers/{id}/grants

1
2
3
4
5
6
7
8
9
10
11curl -X POST https://api.unplugdining.com/v1/offers/71c3e8a5-4b2d-4f60-a9e1-58d7b0c2f346/grants \
  -H "Authorization: Bearer $UNPLUG_KEY" \
  -H "Idempotency-Key: a1f5c9e3-2d7b-4086-9e4a-6b3c8d0f1e25" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_ref": "nov-winback-1",
    "member_ids": [
      "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
      "9a4d2f6b-1c8e-4b73-a0d5-e7f3c19b6284"
    ]
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16const response = await fetch("https://api.unplugdining.com/v1/offers/71c3e8a5-4b2d-4f60-a9e1-58d7b0c2f346/grants", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNPLUG_KEY}`,
    "Idempotency-Key": "a1f5c9e3-2d7b-4086-9e4a-6b3c8d0f1e25",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    grant_ref: "nov-winback-1",
    member_ids: [
      "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
      "9a4d2f6b-1c8e-4b73-a0d5-e7f3c19b6284",
    ],
  }),
});
const data = await response.json();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import os
import requests

response = requests.post(
    "https://api.unplugdining.com/v1/offers/71c3e8a5-4b2d-4f60-a9e1-58d7b0c2f346/grants",
    headers={
        "Authorization": f"Bearer {os.environ['UNPLUG_KEY']}",
        "Idempotency-Key": "a1f5c9e3-2d7b-4086-9e4a-6b3c8d0f1e25",
    },
    json={
        "grant_ref": "nov-winback-1",
        "member_ids": [
            "3f2b8c1e-6d0a-4e7b-9f3c-2a1d5e8b7c40",
            "9a4d2f6b-1c8e-4b73-a0d5-e7f3c19b6284",
        ],
    },
)
data = response.json()

Response JSON200

1
2
3
4
5
6{
  "granted": 1,
  "skipped": [
    { "member_id": "9a4d2f6b-1c8e-4b73-a0d5-e7f3c19b6284", "reason": "already_granted" }
  ]
}

Error descriptions#

400Bad request

idempotency_key_required

The header is missing.

400Bad request

invalid_param

More than 500 member_ids.

400Bad request

invalid_request

The offer's distribution isn't granted.

409Conflict

invalid_state

The offer isn't live.

422Unprocessable

idempotency_key_reused

Same key, different body.

Any endpoint can also return the common errors.

400 Bad request

1
2
3
4
5
6
7{
  "type": "https://docs.unplugdining.com/reference/errors#idempotency_key_required",
  "title": "Bad request",
  "status": 400,
  "code": "idempotency_key_required",
  "detail": "The header is missing."
}