unPLUGDevelopers
/

Management API · Challenges

Update a challenge Coming soon

PATCH/v1/challenges/{id}

Changes the fields you send. A draft is edited in place. Editing a scheduled or live challenge creates a new version: members already enrolled keep the rules they joined under, and new members get the new version. You can't change type, and an ended challenge can't be edited.

Returns the challenge object.

Permissions: Secret key with challenges:write.

Guide

Challenges

Path parameters#

  • idstring (uuid)Required

Request body#

  • namestring
  • descriptionstring
  • image_urlstring (uri)Nullable
  • typestring
    One of visits, streak, spend, menu_discovery
  • goalobject
    Show attributesHide attributes
    • targetinteger
    • unitstring
      One of visits, periods, cents, items
    • periodstringNullable
      One of day, week
    • grace_periodsintegerNullable
    • item_setarray of object
  • qualifyingobject
    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
  • enrollmentstring
    One of automatic, opt_in
  • rewardobject or object
  • max_completions_per_memberinteger
  • budgetobject
    Show attributesHide attributes
    • max_completionsintegerNullable

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.

Error descriptions#

400Bad request
invalid_param

A bad value, or an attempt to change type.

409Conflict
invalid_state

The challenge has ended.

Any endpoint can also return the common errors.