Publish an offer Coming soon

POST/v1/offers/{id}/publish

Moves a draft to scheduled if starts_at is in the future, or to live now. Run a preview first.

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

Path parameters#

idstring (uuid)Required

Response fields#

Returns 200 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/{id}/publish

1
2curl -X POST https://api.unplugdining.com/v1/offers/71c3e8a5-4b2d-4f60-a9e1-58d7b0c2f346/publish \
  -H "Authorization: Bearer $UNPLUG_KEY"

1
2
3
4
5
6
7const response = await fetch("https://api.unplugdining.com/v1/offers/71c3e8a5-4b2d-4f60-a9e1-58d7b0c2f346/publish", {
  method: "POST",
  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.post(
    "https://api.unplugdining.com/v1/offers/71c3e8a5-4b2d-4f60-a9e1-58d7b0c2f346/publish",
    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{
  "id": "71c3e8a5-4b2d-4f60-a9e1-58d7b0c2f346",
  "name": "$3 off your next order",
  "description": "Any order of $8 or more.",
  "status": "live",
  "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#

409Conflict

invalid_state

The offer isn't a draft, or its ends_at has already passed. detail says which.

Any endpoint can also return the common errors.

409 Conflict

1
2
3
4
5
6
7{
  "type": "https://docs.unplugdining.com/reference/errors#invalid_state",
  "title": "Conflict",
  "status": 409,
  "code": "invalid_state",
  "detail": "The offer isn't a draft, or its ends_at has already passed. detail says which."
}