Create an offer Coming soon

POST/v1/offers

Creates a draft. Nobody can see or use it until you publish it.

Permissions: Secret key with offers:write.

Guide

Run offers from your server

Request headers#

Idempotency-Keystring
Any string up to 255 characters; use a UUID v4. Kept 24 hours per key (or member) and endpoint. Same key and body replays the first response with Idempotent-Replayed: true.
Max Length 255

Request body#

namestring
Guest-facing name.
descriptionstring
Guest-facing text.
discountDiscount
What it takes off.
Show attributesDiscount
- typestringRequired
  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
Which carts it works on. Defaults to no limits.
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, shared_code or unique_codes.
One of granted, shared_code, unique_codes
shared_codestring
Required for shared_code. Letters and digits.
per_member_limitinteger
Uses per member.
budgetobject
max_redemptions, max_discount_cents.
Show attributesHide attributes
- max_redemptionsinteger
- max_discount_centsinteger
starts_atstring (date-time)
Dates.
ends_atstring (date-time)
Dates.
wallet_expiry_daysinteger
Required for granted.

Response fields#

Returns 201 with Offer

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

POST/v1/offers

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15curl -X POST https://api.unplugdining.com/v1/offers \
  -H "Authorization: Bearer $UNPLUG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "$3 off your next order",
    "description": "Any order of $8 or more.",
    "discount": { "type": "amount", "amount_cents": 300 },
    "rules": { "min_subtotal_cents": 800, "channels": ["app", "web"] },
    "distribution": "granted",
    "per_member_limit": 1,
    "budget": { "max_redemptions": 300, "max_discount_cents": 90000 },
    "starts_at": "2026-11-02T06:00:00Z",
    "ends_at": "2026-11-30T06:00:00Z",
    "wallet_expiry_days": 14
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20const response = await fetch("https://api.unplugdining.com/v1/offers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNPLUG_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "$3 off your next order",
    description: "Any order of $8 or more.",
    discount: { type: "amount", amount_cents: 300 },
    rules: { min_subtotal_cents: 800, channels: ["app", "web"] },
    distribution: "granted",
    per_member_limit: 1,
    budget: { max_redemptions: 300, max_discount_cents: 90000 },
    starts_at: "2026-11-02T06:00:00Z",
    ends_at: "2026-11-30T06:00:00Z",
    wallet_expiry_days: 14,
  }),
});
const data = await response.json();

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

response = requests.post(
    "https://api.unplugdining.com/v1/offers",
    headers={
        "Authorization": f"Bearer {os.environ['UNPLUG_KEY']}",
    },
    json={
        "name": "$3 off your next order",
        "description": "Any order of $8 or more.",
        "discount": {"type": "amount", "amount_cents": 300},
        "rules": {"min_subtotal_cents": 800, "channels": ["app", "web"]},
        "distribution": "granted",
        "per_member_limit": 1,
        "budget": {"max_redemptions": 300, "max_discount_cents": 90000},
        "starts_at": "2026-11-02T06:00:00Z",
        "ends_at": "2026-11-30T06:00:00Z",
        "wallet_expiry_days": 14,
    },
)
data = response.json()

Response JSON201

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17{
  "id": "71c3e8a5-4b2d-4f60-a9e1-58d7b0c2f346",
  "name": "$3 off your next order",
  "description": "Any order of $8 or more.",
  "status": "draft",
  "version": 1,
  "discount": { "type": "amount", "amount_cents": 300 },
  "rules": { "min_subtotal_cents": 800, "channels": ["app", "web"], "location_ids": [], "fulfillment": [], "available_times": [], "tier_ids": [] },
  "distribution": "granted",
  "shared_code": null,
  "per_member_limit": 1,
  "budget": { "max_redemptions": 300, "max_discount_cents": 90000, "used_redemptions": 0, "used_discount_cents": 0 },
  "starts_at": "2026-11-02T06:00:00Z",
  "ends_at": "2026-11-30T06:00:00Z",
  "wallet_expiry_days": 14,
  "created_by": "api"
}

Error descriptions#

400Bad request

missing_param

A required field is missing, including shared_code for a shared_code offer.

400Bad request

invalid_param

For example a percent over 100, or ends_at before starts_at.

403Forbidden

missing_scope

The key doesn't have offers:write.

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#missing_param",
  "title": "Bad request",
  "status": 400,
  "code": "missing_param",
  "detail": "A required field is missing, including shared_code for a shared_code offer."
}