unPLUGDevelopers
/

Management API · Offers

Update an offer Coming soon

PATCH/v1/offers/{id}

Changes the fields you send. A draft is edited in place. Editing a scheduled or live offer creates a new version: new grants and code uses get the new version, and members who already have the offer keep the old one. An ended offer can't be edited.

Permissions: Secret key with offers:write.

Guide

Run offers from your server

Path parameters#

  • idstring (uuid)Required

Request body#

  • namestring
  • descriptionstring
  • discountDiscount
    Show attributesDiscount
    • typestringRequired
      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
    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
    One of granted, shared_code, unique_codes
  • shared_codestring
  • per_member_limitinteger
  • budgetobject
    Show attributesHide attributes
    • max_redemptionsinteger
    • max_discount_centsinteger
  • starts_atstring (date-time)
  • ends_atstring (date-time)
  • wallet_expiry_daysinteger

Any field from Create an offer except distribution.

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

Error descriptions#

400Bad request
invalid_param

A bad value, or an attempt to change distribution.

409Conflict
invalid_state

The offer has ended.

404Not found
not_found

No such offer.

Any endpoint can also return the common errors.