List offers Coming soon

GET/v1/offers

Lists offers, newest first, with cursor pagination.

Permissions: Secret key with offers:write.

Guide

Run offers from your server

Query parameters#

limitinteger
1 to 100. Default 25.
Min 1Max 100Default 25
cursorstring
next_cursor from the previous page.

Response fields#

Returns 200 with list of Offer

dataarray of Offer
Show attributesOffer
- idstring (uuid)
  The offer.
- namestring
  Shown to guests on wallet items and in checkout.
- descriptionstring
  One or two lines for guests.
- statusstring
  draft, scheduled, live, paused or ended.
  One of draft, scheduled, live, paused, ended
- versioninteger
  Starts at 1. Goes up each time a scheduled or live offer is edited. Members keep the version they got.
- discountDiscount
  Same shape as a reward's discount: type is amount (amount_cents), percent (percent), free_item (items or categories, max_items) or bogo.
  Show attributesDiscount
  - typestring
    One of amount, percent, free_item, bogo
  - amount_centsinteger
    For amount.
  - percentnumber
    For percent.
  - itemsarray of object
    Item scope, by Square variation id.
    Show attributesHide attributes
    pos_item_idstring
    namestring
  - categoriesarray of object
    Category scope.
    Show attributesHide attributes
    pos_category_idstring
    namestring
  - max_itemsinteger
- rulesRules
  Same shape as a reward's rules: min_subtotal_cents, channels, location_ids, fulfillment, available_times, tier_ids. Empty lists mean no limit.
  Show attributesRules
  - min_subtotal_centsinteger
    Integer cents.
    Min 0
  - channelsarray of string
    One of app, web
  - location_idsarray of string (uuid)
  - fulfillmentarray of string
    One of pickup, delivery, curbside, dine_in
  - available_timesarray of AvailableTime
    Show attributesAvailableTime
    daysarray of string
    Show valuesHide values
    mon
    tue
    wed
    thu
    fri
    sat
    sun
    startstring
    Local time, HH:MM.
    endstring
    Local time, HH:MM.
  - tier_idsarray of string (uuid)
- distributionstring
  granted (lands in the wallet), shared_code (one code for everyone) or unique_codes (single-use codes from batches).
  One of granted, shared_code, unique_codes
- shared_codestringNullable
  The code, for shared_code offers. Otherwise null.
- per_member_limitintegerNullable
  How many times one member can use the offer. null for no limit.
- budgetBudget
  max_redemptions and max_discount_cents (either can be null), and the running totals used_redemptions and used_discount_cents. Enforced at checkout.
  Show attributesBudget
  - max_redemptionsintegerNullable
  - max_discount_centsintegerNullable
  - used_redemptionsinteger
  - used_discount_centsinteger
- starts_atstring (date-time)Nullable
  When it goes live. null to go live on publish.
- ends_atstring (date-time)Nullable
  When it ends. null for no end date.
- wallet_expiry_daysintegerNullable
  For granted offers: days a wallet item lasts after it's granted.
- created_bystring
  api, dashboard or campaign.
  One of api, dashboard, campaign
has_moreboolean
True when another page exists.
next_cursorstringNullable
Pass as cursor to get the next page.

GET/v1/offers

1
2curl "https://api.unplugdining.com/v1/offers?status=live&limit=2" \
  -H "Authorization: Bearer $UNPLUG_KEY"

1
2
3
4
5
6const response = await fetch("https://api.unplugdining.com/v1/offers?status=live&limit=2", {
  headers: {
    Authorization: `Bearer ${process.env.UNPLUG_KEY}`,
  },
});
const data = await response.json();

1
2
3
4
5
6
7
8
9
10import os
import requests

response = requests.get(
    "https://api.unplugdining.com/v1/offers?status=live&limit=2",
    headers={
        "Authorization": f"Bearer {os.environ['UNPLUG_KEY']}",
    },
)
data = response.json()

Response JSON200

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40{
  "data": [
    {
      "id": "a8f2d6b4-3e9c-4a7f-8d1e-6c5b2a0f9e37",
      "name": "Fall pastry on us",
      "description": "Any pastry, one per order.",
      "status": "live",
      "version": 1,
      "discount": {"type": "free_item", "categories": [{"pos_category_id": "P9MT2XQ6KZR4WLN8HCB3J7VD", "name": "Pastries"}], "max_items": 1},
      "rules": {"min_subtotal_cents": 0, "channels": ["app", "web"], "location_ids": [], "fulfillment": [], "available_times": [], "tier_ids": []},
      "distribution": "granted",
      "shared_code": null,
      "per_member_limit": 1,
      "budget": {"max_redemptions": 500, "max_discount_cents": null, "used_redemptions": 37, "used_discount_cents": 13025},
      "starts_at": "2026-10-30T05:00:00Z",
      "ends_at": "2026-11-13T05:59:59Z",
      "wallet_expiry_days": 14,
      "created_by": "campaign"
    },
    {
      "id": "c90b4e21-3f7a-4d58-8b16-a2e5d97f0c34",
      "name": "10% off your order",
      "description": "One order, once per member.",
      "status": "live",
      "version": 1,
      "discount": {"type": "percent", "percent": 10},
      "rules": {"min_subtotal_cents": 0, "channels": ["app", "web"], "location_ids": [], "fulfillment": [], "available_times": [], "tier_ids": []},
      "distribution": "shared_code",
      "shared_code": "WELCOME10",
      "per_member_limit": 1,
      "budget": {"max_redemptions": null, "max_discount_cents": null, "used_redemptions": 1284, "used_discount_cents": 151920},
      "starts_at": null,
      "ends_at": null,
      "wallet_expiry_days": null,
      "created_by": "dashboard"
    }
  ],
  "has_more": true,
  "next_cursor": "b2ZmZXJfMjAyNi0xMC0yOA"
}