Management API · Challenges

Create a challenge Coming soon

POST/v1/challenges

Permissions: Secret key with challenges:write.

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.
• image_urlstring (uri)Nullable
  HTTPS image.
• typestring
  Challenge type.
  One of visits, streak, spend, menu_discovery
• goalobject
  Target and unit. The unit must match the type.
  Show attributesHide attributes

  • targetinteger
  • unitstring
    One of visits, periods, cents, items
  • periodstringNullable
    One of day, week
  • grace_periodsintegerNullable
  • item_setarray of object
• qualifyingobject
  Defaults: no minimum, no limits, max_counted_per_day: 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
  Fixed or rolling.
• enrollmentstring
  automatic or opt_in.
  One of automatic, opt_in
• rewardobject or object
  Points or a catalog reward.
• max_completions_per_memberinteger
  Default 1.
• budgetobject
  max_completions.
  Show attributesHide attributes

  • max_completionsintegerNullable

Response fields#

Returns 201 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.