unPLUGDevelopers
/

Management API · Challenges

List challenges Coming soon

GET/v1/challenges

Returns all your challenges in any status, newest first, including drafts. Paginated with limit and cursor. To show challenges to a guest, use List challenges in the App API instead.

Permissions: Secret key with challenges:write.

Guide

Challenges

Query parameters#

  • statusstring
    Only challenges in this status.
    One of draft, scheduled, live, paused, ended
  • limitinteger
    1 to 100. Default 25.
    Min 1Max 100Default 25
  • cursorstring
    next_cursor from the previous page.

Response fields#

Returns 200 with list of Challenge

  • dataarray of Challenge
    Show attributesChallenge
    • 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.
  • has_moreboolean
    True when another page exists.
  • next_cursorstringNullable
    Pass as cursor to get the next page.

Error descriptions#

403Forbidden
missing_scope

The secret key doesn't have challenges:write.

Any endpoint can also return the common errors.