info:
  title: Headless Offers API - Platform Functions
  version: '1.0'
  contact:
    name: Punchh Dev Support
    url: https://developers.punchh.com
  description: 'Distribute Punchh offers through an external system of choice by configuring and scheduling
    the mass offer campaign functionality through API calls.


    For more information, see [Headless Offers Management - Distribution](/docs/dev-portal-platform-functions/4fabd3e0da881-headless-offers-management-distribution)'
paths:
  /api2/dashboard/segments:
    get:
      summary: Get Segment List
      operationId: get-api2-segment-list
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  example-1:
                    subscription_id: 1234
                    start_time: '2021-05-18 11:34:46'
                    end_time: '2021-05-28 11:34:46'
                properties:
                  segment_id:
                    type: integer
                    description: Unique ID of the segment
                  name:
                    type: string
                    description: Name of the segment
                  description:
                    type: string
                    description: Description of the segment
                  segment_type:
                    type: string
                    description: 'Type of the segment '
                  user_type:
                    type: string
                    description: Type of the user
                  membership_level:
                    type: string
                    description: Membership level of the user
              examples:
                example:
                  value:
                  - segment_id: 1306904
                    name: test 1
                    description: ''
                    segment_type: GuestProfileSegmentDefinition
                    user_type: loyalty_user
                    membership_level: null
        '400':
          description: 'Required parameter missing or the value is empty : segment_id'
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '422':
          description: Invalid segment id
          content:
            application/json:
              schema:
                type: object
                properties: {}
      parameters:
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/accept-header'
      - $ref: '#/components/parameters/authorization-header'
      description: "Pulls a list of segments available and/or defined on Punchh, allowing for browsing/selecting\
        \ of Punchh segments natively in an external platform. Segment search is on a business level,\
        \ and the request can:\n* Set search limits and order by desc search\n* Search based on name or\
        \ segment type filter\n* Filter based on name or description\n\n\n\nFor more information, see\
        \ [Headless Offers Management - Distribution](/docs/dev-portal-platform-functions/4fabd3e0da881-headless-offers-management-distribution)\n\
        \n#### Adding Users to a Segment\n\nYou can add a user to the segment using either email or user_id.\
        \ See [Add User to a Custom Segment](/docs/dev-portal-platform-functions/apis/platform-functions-api/tag/custom-segments/post/api2/dashboard/custom_segments/members).\
        \ \n\nYou can also add users in bulk to a custom segment by uploading a CSV file that contains\
        \ a list of users and their details. See [Bulk Add Users to a Custom Segment](/docs/dev-portal-platform-functions/apis/platform-functions-api/tag/custom-segments/post/api2/dashboard/custom_segments/members/bulk_add).\
        \ \n\nSee [Custom Segment APIs](https://developers.partech.com/docs/dev-portal-platform-functions/additional-topics/gettingstartedwithcustomsegment)\
        \ quickstart topic for the complete list of APIs for managing custom segments and users.\n\nThe\
        \ users you add must exist in Punchh. If a user does not exist, then the [Add User to a Custom\
        \ Segment](/docs/dev-portal-platform-functions/apis/platform-functions-api/tag/custom-segments/post/api2/dashboard/custom_segments/members)\
        \ API returns an error. When using the [Bulk Add Users to a Custom Segment](/docs/dev-portal-platform-functions/apis/platform-functions-api/tag/custom-segments/post/api2/dashboard/custom_segments/members/bulk_add)\
        \ API, the users who do not exist in Punchh are skipped. You can use the [Get User Information\
        \ API](/docs/dev-portal-platform-functions/apis/platform-functions-api/tag/users/get/api2/dashboard/users/info)\
        \ to check whether a user exists in Punchh."
      x-stoplight:
        id: 898fd4cc84237
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: Define the search string on the segment name
                page:
                  type: integer
                  description: Number of pages
                per_page:
                  type: integer
                  description: Number of records per page
            examples:
              Request:
                value:
                  user_id: 1234
                  start_time: '2021-05-18 11:34:46'
                  plan_id: 12
                  end_time: '2021-05-28 11:34:46'
                  purchase_price: 20
                  auto_renewal: false
                  migration: false
                  lifetime_debits: 30
                  lifetime_savings: 50
                  initial_debits: 10
                  initial_savings: 20
                  source_subscription_id: 'null'
  /api2/dashboard/redeemables:
    parameters: []
    get:
      summary: Get Redeemable List
      operationId: get-api2-redeemable-list
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  example-1:
                    subscription_id: 40
                    start_time: '2021-04-20T21:09:38Z'
                    end_time: '2021-04-20T21:09:38Z'
                properties:
                  redeemable_id:
                    type: integer
                    description: ID of the redeemable
                  redeemable_uuid:
                    type: string
                    description: UUID of the redeemable
                  name:
                    type: string
                    description: Name of the redeemable
                  description:
                    type: string
                    description: Description of the redeemable
                  redeemable_image_url:
                    type: string
                    description: Image URL for the redeemable
              examples:
                example:
                  value:
                  - redeemable_id: 20473
                    redeemable_uuid: test
                    name: future
                    description: free
                    redeemable_image_url: IMAGE_URL_GOES_HERE
                  - redeemable_id: 20408
                    redeemable_uuid: test
                    name: New - Free Coffee For 2 !!!
                    description: ''
                    redeemable_image_url: IMAGE_URL_GOES_HERE
        '400':
          description: 'Required parameter missing or the value is empty : redeemable_uuid'
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    x-stoplight:
                      id: tk1mlz6ykdjbi
              examples:
                Feature disabled:
                  value:
                    errors:
                      disabled _feature: Your current loyalty program configuration does not support this
                        feature. Please connect with your Customer Success representative for resolution
                        of this issue
      description: 'Pulls a list of offers available and defined on Punchh, allowing for browsing/selecting
        of Punchh offers natively in an external platform. Redeemable search is on a business level, and
        the request can:

        * Set search limits and order by desc search

        * Search based on name or segment type filter

        * Filter based on name or description

        For more information, see [Headless Offers Management - Distribution](/docs/dev-portal-platform-functions/4fabd3e0da881-headless-offers-management-distribution)


        To call this API, the option to distribute offers from an external system must be enabled for
        the business on the Punchh platform. Contact your Punchh representative to update this Punchh
        platform configuration. <!-- Cockpit > Dashboard > Miscellaneous Config --> '
      parameters:
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/accept-header'
      - $ref: '#/components/parameters/authorization-header'
      x-stoplight:
        id: b3e6608469a3e
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              type: object
              x-examples:
                example-1:
                  subscription_id: '35'
                  start_time: '2021-04-20T21:09:38Z'
                  end_time: '2021-05-20T21:09:38Z'
                  purchase_price: '23.09'
              properties:
                query:
                  type: string
                  description: Define the search string on the redeemable name and description column
                page:
                  type: integer
                  description: Number of pages
                per_page:
                  type: integer
                  description: Number of records per page
            examples:
              example:
                value:
                  query: free
                  page: '1'
                  per_page: 20
  /api2/dashboard/campaigns:
    post:
      summary: Commit Redeemable Distribution
      operationId: post-api2-redeemable-distribution
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  redeemable_id:
                    type: integer
                    description: ID of the redeemable
                  redeemable_image_url:
                    type: string
                    description: Image URL for the redeemable
                  redeemable_properties:
                    type: string
                    description: Specifies the redeemable attribute
                  campaign_id:
                    type: integer
                    description: ID of the campaign
                  external_source_id:
                    type: string
                    description: ID of third-party campaign
                  start_time:
                    type: string
                    description: Start time of the campaign
                    format: date-time
                  time_zone:
                    type: string
                    description: Time zone of the campaign
                examples:
                - redeemable_id: 20416
                  redeemable_image_url: IMAGE_URL_GOES_HERE
                  redeemable_properties: attribute
                  campaign_id: 99511494
                  external_source_id: '2'
                  start_time: 2021-09-14 06:44 PM
                  timezone: Etc/UTC
              examples:
                example:
                  value:
                    redeemable_id: 20416
                    redeemable_image_url: IMAGE_URL_GOES_HERE
                    redeemable_properties: attribute
                    campaign_id: 99511494
                    external_source_id: '2'
                    start_time: 2021-09-14 06:44 PM
                    timezone: Etc/UTC
        '400':
          description: "Required parameter missing or the value is empty: redeemable_uuid\n \nRequired\
            \ parameter missing or the value is empty: segment_id \n\nRequired parameter missing or the\
            \ value is empty: category \n\nRequired parameter missing or the value is empty: campaign_type\
            \ \n\nRequired parameter missing or the value is empty: start_time \n\nRequired parameter\
            \ missing or the value is empty: campaign_id "
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '404':
          description: Coupon campaign not found
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '422':
          description: "Coupon campaigns feature is not enabled in business\n\nCampaign start time should\
            \ be at least 15 ahead from now\n\nInvalid Start Time format\n\nStart time should be less\
            \ than or equal to redeemable effective expiry time \n\nInvalid redeemable uuid \n\nInvalid\
            \ category \n\nInvalid segment id \n\nRedeemable is scheduled \n\nRedeemable is deactivated "
          content:
            application/json:
              schema:
                type: object
                properties: {}
      description: "Triggers configuration and scheduling of a mass offer campaign on Punchh. This is\
        \ used by an external platform to request Punchh to deliver offers to a target segment of guests\
        \ using the Punchh mass offer campaign functionality. When using this endpoint to request scheduling\
        \ of a mass offer campaign on Punchh, the mass offer campaign created will not have any marketing\
        \ communication configured (email, push notification, SMS, etc.), and the mass offer campaign\
        \ will only distribute a Punchh redeemable to the guests in the targeted segment. \n\nFor more\
        \ information, see [Headless Offers Management - Distribution](/docs/dev-portal-platform-functions/4fabd3e0da881-headless-offers-management-distribution)"
      parameters:
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/accept-header'
      - $ref: '#/components/parameters/authorization-header'
      x-stoplight:
        id: 95afe32043e6b
      requestBody:
        content:
          application/json:
            schema:
              type: object
              x-examples:
                example-1:
                  subscription_id: '126'
                  cancellation_reason: Do not like your service
                  cancellation_type: hard_cancelled
              properties:
                redeemable_uuid:
                  type: string
                  description: Redeemable UUID
                segment_id:
                  type: integer
                  description: Segment ID of the group of users for mass gifting
                category:
                  type: string
                  description: 'Gift type. For example: gift_redeemable, gift_fixed_point (currently only
                    gift_redeemable is supported)'
                campaign_type:
                  type: string
                  description: 'Campaign type. For example: mass gifting campaign, coupon campaign (currently
                    only mass gifting campaign is supported)'
                name:
                  type: string
                  description: Campaign name
                start_time:
                  type: string
                  description: Start time of the campaign
                external_campaign_id:
                  type: string
                  description: ID of third-party campaign
              required:
              - redeemable_uuid
              - segment_id
              - category
              - campaign_type
              - name
              - start_time
            examples:
              example:
                value:
                  redeemable_uuid: test
                  segment_id: 1307202
                  category: gift_redeemable
                  campaign_type: mass_gifting
                  name: API 11
                  start_time: '2021-09-14T18:44:38Z'
                  external_campaign_id: '2'
  /api2/dashboard/users/support_gifting:
    post:
      summary: Asynchronous Support Gifting
      operationId: post-api2-dashboard-users-support_gifting
      responses:
        '202':
          description: OK - Request was accepted and processed successfully.
        '401':
          description: Unauthorized - Missing or invalid Bearer token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    x-stoplight:
                      id: bgezkfgnei74b
              examples:
                Unauthorized access:
                  value:
                    error: You need to sign in or sign up before continuing.
        '422':
          description: "Unprocessable Entity \n- Both `gift_count` and `redeemable_id` are missing: Please\
            \ specify any one entity for gifting.\n- Both `gift_count` and `redeemable_id` are present:\
            \ Please specify single entity for gifting."
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    x-stoplight:
                      id: w64b6t74jarxu
                    properties:
                      base:
                        type: array
                        x-stoplight:
                          id: e3p2uib3rii4o
                        items:
                          x-stoplight:
                            id: 22nsv9lihmnxy
                          type: string
              examples:
                Feature flag disabled:
                  value:
                    errors:
                      base:
                      - Your current loyalty program configuration does not support this feature. Please
                        connect with your customer success representative for resolution of the issue.
                Both `gift_count` and `redeemable_id` are missing:
                  value:
                    errors:
                      base:
                      - Please specify any one entity for gifting
                Both `gift_count` and `redeemable_id` are present:
                  value:
                    errors:
                      base:
                      - Please specify single entity for gifting.
      description: 'Allows an admin to gift a single entity (points, visits, currency or rewards) to a
        specific user. This API can handle higher volumes of support gifting requests, as it processes
        them in the background rather than immediately.


        For bulk gifting use cases (points or rewards), we recommend using this API, which supports up
        to 4,000 requests per minute (RPM) and is optimized for high-volume gifting scenarios.'
      parameters:
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/accept-header'
      - $ref: '#/components/parameters/authorization-header'
      x-stoplight:
        id: 083fc4af21d64
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: integer
                  description: Unique ID of the user who will receive the gift or message. This is a unique
                    ID assigned to the user by Punchh.
                subject:
                  type: string
                  description: Subject of the message that you want to send to the user. If no value is
                    provided, the default system value will be used.
                message:
                  type: string
                  description: Message that will be sent to the user
                gift_reason:
                  type: string
                  description: Reason these points or rewards are being gifted to the user. If no value
                    is provided, the default system value of "Support Activity" will be provided.
                gift_count:
                  type: integer
                  description: 'In a points-based business, gift_count represents the number of points
                    to be gifted to guests. In a visit-based business, it is the number of visits to be
                    gifted. Gifting is optional. You can include either `gift_count` (for points or visits)
                    or `redeemable_id` (for rewards) in the request. At least one of these parameters
                    must be provided.

                    * If both gift_count and redeemable_id are blank, the system returns: "Please specify
                    any one entity for gifting".

                    * If both gift_count and redeemable_id are present, the system returns: "Please specify
                    a single entity for gifting".

                    '
                reward_amount:
                  type: integer
                  x-stoplight:
                    id: msxx9oioxlpyl
                  description: Currency amount that will be gifted to the user.
                redeemable_id:
                  type: integer
                  description: Unique ID of the redeemable that you want to gift to the user. To send
                    a gift, include either `gift_count` (for points) or `redeemable_id` (for rewards)
                    in the request. At least one of these parameters must be provided.
                end_date:
                  type: string
                  format: date
                  description: 'Expiration date for the gifted redeemable.

                    If provided, the redeemable will expire on the earlier of this date or the default
                    configuration’s expiration date. The actual expiration will be whichever is earlier:
                    the date you provide, or the system’s default expiration for that reward.'
                  examples:
                  - YYYY-MM-DD
                location_id:
                  type: integer
                  description: Unique ID of the location associated with the gift. This is for reference
                    purposes. If no location ID is provided, the ID of the headquarters location will
                    be used.
                reset_guest_last_activity:
                  type: boolean
                  x-stoplight:
                    id: ukavl0wchvhnx
                  description: Resets the guest's last activity timestamp to the current time
              required:
              - user_id
            examples:
              Example:
                value:
                  user_id: 111111111
                  subject: Gifts from us.
                  message: Thank you for contacting us. Here are 50 extra points to make your day.
                  gift_reason: Admin Generosity
                  gift_count: 50
                  location_id: 310969
  /api2/dashboard/users/support:
    post:
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '422':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    x-stoplight:
                      id: 9bphoz90yu3rq
                    properties:
                      base:
                        type: array
                        x-stoplight:
                          id: qy6fp2gyy03gw
                        items: {}
              examples:
                default:
                  value:
                    errors:
                      base:
                      - Please specify single entity for gifting.
      summary: Support Gifting to a User
      description: 'The Support Gifting API enables administrators (such as restaurant managers, support
        staff, or corporate team members) to grant users different types of rewards (e.g., redeemables,
        points, etc.). It is particularly valuable in customer support, operational adjustments, or exception-handling
        scenarios where manual gifting is required.


        <b>Caution</b>: It must not be used for bulk or large-scale gifting and is not a substitute for
        marketing or promotional campaigns.


        <b>Maximum allowed usage</b>: The API enforces a rate limit of 1,250 requests per minute (RPM).


        <b>Recommendation</b>: For bulk gifting use cases (points or rewards), we recommend using [Asynchronous
        Support Gifting](/docs/dev-portal-platform-functions/apis/headless-offers-api/post/api2/dashboard/users/support_gifting)
        API, which supports up to 4,000 RPM and is optimized for high-volume gifting scenarios.'
      operationId: dashboard_support_gifting_to_user
      parameters:
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/accept-header'
      - $ref: '#/components/parameters/authorization-header'
      x-stoplight:
        id: b75aa83d15fa6
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: integer
                  description: Unique ID of the user to whom you want to send the message. This is a unique
                    ID assigned to the user by Punchh.
                subject:
                  type: string
                  description: Subject of the message that you want to send to the user. If no value is
                    provided, the default system value will be picked.
                message:
                  type: string
                  description: The message that will be sent to the user. Messaging is optional. You can
                    send either a message only or a gift only. However, at least one of the two should
                    be sent.
                gift_reason:
                  type: string
                  description: The reason these points, visits, or rewards are being gifted to the user.
                    If no value is provided, the default system value of "Support Activity" will be provided.
                gift_count:
                  type: integer
                  description: In a points-based business, the gift count is the number of points that
                    will be gifted to guests. In a visit-based business, it is the number of visits that
                    will be gifted. Gifting is optional. You can send either a message only or a gift
                    only. However, at least one of the two should be sent.
                reward_amount:
                  type: integer
                  description: Currency amount that will be gifted to the user. Gifting is optional. You
                    can send either a message only or a gift only. However, at least one of the two should
                    be sent.
                redeemable_id:
                  type: integer
                  description: Unique ID of the redeemable that you want to gift to the user. Gifting
                    is optional. You can send either a message only or a gift only. However, at least
                    one of the two should be sent.
                end_date:
                  type: string
                  format: date
                  description: The date on which you want the gifted redeemable to expire. If this date
                    is provided and there is an expiry configured on the redeemable, it will expire on
                    the earlier date.
                fuel_amount:
                  type: number
                  description: Fuel amount that you want to gift to the user
                location_id:
                  type: integer
                  description: Unique ID of the location associated with the gift. This is for reference
                    purposes. If no location ID is provided, the ID of the headquarters location will
                    be used.
                reset_guest_last_activity:
                  type: boolean
                  x-stoplight:
                    id: ukavl0wchvhnx
                  description: Resets the guest's last activity which is the expiry date to the current
                    time
                challenge_campaign_id:
                  type: integer
                  x-stoplight:
                    id: igylbqbmml2tf
                  description: Unique ID of the challenge in a campaign for which progress will be gifted
                progress_count:
                  type: integer
                  x-stoplight:
                    id: v6pezpd2lr2k2
                  description: Number of steps that will be gifted to the user for the challenge ID specified
                    in `challenge_campaign_id`. If the API call is successful, the progress made in the
                    challenge is shown in the <b>Challenges</b> tab on the user timeline in the Punchh
                    platform. Challenges must be enabled for the business in the Punchh platform, and
                    the bearer token for admin authorization passed in the Authorization header must have
                    the <b>Dashboard API Access</b> and <b>Gift or Force Redeem</b> permissions for the
                    API to gift the user the progress for a challenge successfully. Contact your Punchh
                    representative to update this Punchh platform configuration.
            examples:
              default:
                value:
                  user_id: 111111111
                  subject: Gifts from us.
                  message: Thank you for contacting us. Here are 50 extra points to make your day.
                  gift_reason: Admin Generosity
                  gift_count: 50
                  location_id: 310969
                  challenge_campaign_id: 48770
                  progress_count: 1
        description: ''
x-stoplight:
  id: 6a73c90b2896b
openapi: 3.1.1
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
components:
  schemas: {}
  parameters:
    content-type:
      schema:
        type: string
        default: application/json
      in: header
      name: Content-Type
      description: The media type of the request body. Must be `application/json`.
      required: true
    accept-header:
      schema:
        type: string
        default: application/json
      in: header
      name: Accept
      description: The media type the client expects in the response. Must be `application/json`.
      required: true
    authorization-header:
      schema:
        type: string
      in: header
      name: Authorization
      description: 'Bearer token for admin authorization. Send the API key in the following format: "Authorization:
        Bearer BUSINESS_ADMIN_KEY_GOES_HERE".'
      required: true
  responses:
    401-unauthorized:
      description: 'Unauthorized - A business admin key is missing or invalid. A request header in the
        following format is needed to make the request:


        Authorization: Bearer BUSINESS_ADMIN_KEY_GOES_HERE'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
          examples:
            default:
              value:
                error: You need to sign in or sign up before continuing.
  securitySchemes: {}
x-ext-urls: {}