Publish a challenge Coming soon

POST/v1/challenges/{id}/publish

Moves a draft to scheduled if its window starts in the future, or to live now. An automatic challenge enrolls its members when it goes live. Also moves a paused challenge back to live. Run a preview first.

Returns the challenge with its new status.

Permissions: Secret key with challenges:write.

Guide

Challenges

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 Challenge

idstring (uuid)
The challenge.
namestring
Shown to guests.
descriptionstring
One or two lines for guests.
image_urlstring (uri)Nullable
HTTPS image for the challenge card.
typestring
visits, streak, spend or menu_discovery.
One of visits, streak, spend, menu_discovery
goalobject
target (number to reach) and unit (visits, periods, cents or items). Streaks add period (day or week) and grace_periods. Menu discovery adds item_set: items (pos_item_id, name) or categories (pos_category_id, name). Fields that don't apply are null or empty.
Show attributesHide attributes
- targetinteger
- unitstring
  One of visits, periods, cents, items
- periodstringNullable
  One of day, week
- grace_periodsintegerNullable
- item_setarray of object
qualifyingobject
Which orders count: min_subtotal_cents, channels, location_ids, fulfillment, available_times (same shapes as reward rules; empty lists mean no limit) and max_counted_per_day (default 1).
Show attributesHide attributes
- min_subtotal_centsinteger
  Integer cents.
  Min 0
- channelsarray of string
- 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.
- max_counted_per_dayinteger
windowobject or object
{ "kind": "fixed", "starts_at", "ends_at" } for the same dates for everyone, or { "kind": "rolling", "days" } for a window per member that starts when they join.
enrollmentstring
automatic or opt_in.
One of automatic, opt_in
rewardobject or object
{ "kind": "points", "points" } for bonus points, or { "kind": "reward", "reward_id" } for a catalog reward that lands in the wallet.
max_completions_per_memberinteger
Usually 1.
budgetobject
max_completions across all members, or null for no limit.
Show attributesHide attributes
- max_completionsintegerNullable
statusstring
draft, scheduled, live, paused or ended.
One of draft, scheduled, live, paused, ended
versioninteger
Goes up each time a scheduled or live challenge is edited. Members keep the rules of the version they joined.

POST/v1/challenges/{id}/publish

1
2curl -X POST https://api.unplugdining.com/v1/challenges/d1e83b5c-7f02-4a69-9c4e-5b1a07d8e236/publish \
  -H "Authorization: Bearer $UNPLUG_KEY"

1
2
3
4
5
6
7const response = await fetch("https://api.unplugdining.com/v1/challenges/d1e83b5c-7f02-4a69-9c4e-5b1a07d8e236/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/challenges/d1e83b5c-7f02-4a69-9c4e-5b1a07d8e236/publish",
    headers={
        "Authorization": f"Bearer {os.environ['UNPLUG_KEY']}",
    },
)
data = response.json()

Error descriptions#

409Conflict

invalid_state

The challenge isn't a draft or paused, or its window has already ended.

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 challenge isn't a draft or paused, or its window has already ended."
}