Punchh Platform Functions API

info:
  title: Platform Functions API
  version: '1.0'
  description: This API documentation is intended to provide comprehensive information for admin users
    of the Punchh platform. Many of the settings and available actions depend on an appropriate level
    of access to Platform Functions APIs.
  contact:
    name: Punchh DevSupport
    url: https://developers.punchh.com
paths:
  /api2/dashboard/locations:
    get:
      responses:
        '200':
          $ref: '#/components/responses/locations-object'
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      client:
                        type: string
              examples:
                default:
                  value:
                    errors:
                      client: Required parameter missing or the value is empty.
        '401':
          $ref: '#/components/responses/401-unauthorized'
      summary: Get Locations List
      description: Returns a list of locations and their details. The `page` and `per` request parameters
        determine the page(s) returned and the number of locations returned per page.
      operationId: dashboard_get_location_list
      tags:
      - Locations
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - schema:
          type: string
          default: '306082'
        in: query
        name: location_id
        required: true
        description: Unique ID of a particular location. This is generated by Punchh. If both `location_id`
          and `store_number` are provided, `location_id` will be given priority.
      - schema:
          type: string
        in: query
        name: store_number
        description: Unique store number provided by the business. If both `location_id` and `store_number`
          are provided, `location_id` will be given priority.
      - schema:
          type: integer
          default: 1
        in: query
        name: page
        description: Page number. If this parameter is not provided with the request, the default is to
          return all. If `page` is specified, only that page will be returned using the value of `per`
          as the number of locations returned on that page.
      - schema:
          type: integer
          default: 25
        in: query
        name: per
        description: Number of locations per page. If `per` is not specified, the default is 25.
      x-stoplight:
        id: 8b8d1f327d630
    post:
      responses:
        '200':
          $ref: '#/components/responses/locations-object'
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  status:
                    type: string
                    x-stoplight:
                      id: p1u7l5eyuc9k0
              examples:
                A null value passed in the url parameter in the additional_url array object:
                  value:
                    error: 'Required parameter missing or the value is empty: additional_url_3'
                Required parameter missing:
                  value:
                    error: 'Required parameter missing or the value is empty: location'
                Invalid JSON:
                  value:
                    status: 400
                    error: data was not valid JSON
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    x-stoplight:
                      id: 52wiu7ve9pe4h
              examples:
                Additional URL label not configured in Punchh platform:
                  value:
                    errors:
                      additional_url: Given additional URL label is not present in the business configuration.
                An invalid URL is passed in additional_url array object:
                  value:
                    base:
                    - Reservation URL is an invalid URL
      summary: Create Location
      description: "Creates a location in the database\n\n### Permissions Requirement\nAn admin account\
        \ with Business Manager permission is required. Accounts without required permission will receive\
        \ a 302 error response.\n\n#### Need help with permissions? \nReach out to your Punchh representative.\
        \ \n\n#### Need a Punchh admin account? \nYour business will already have an admin with the necessary\
        \ permissions to create an additional account if needed. If additional help is needed, your Punchh\
        \ representative can assist."
      operationId: dashboard_create_location
      tags:
      - Locations
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/accept'
      x-stoplight:
        id: 8613cc1d7011c
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                location:
                  type: object
                  properties:
                    address:
                      type: string
                      description: Full address of a particular business location
                    city:
                      type: string
                      description: City of a particular business location
                    country:
                      type: string
                      description: Country of a particular business location
                    external_store_id:
                      type: string
                      description: External POS identifier configured in the Punchh platform under location
                        attributes via Store Locations > All Store Locations > [choose location] > POS
                        > External POS Store Identifier
                    latitude:
                      type: number
                      description: Latitude coordinate of a particular business location
                      format: float
                    longitude:
                      type: number
                      description: Longitude coordinate of a particular business location
                      format: float
                    name:
                      type: string
                      description: Name of a particular business location
                    phone_number:
                      type: string
                      description: Phone number of a particular business location
                    loc_email:
                      type: string
                      description: Email address of a particular business location
                    post_code:
                      type: string
                      description: Zip code of a particular business location
                    state:
                      type: string
                      description: State where a particular business is located
                    store_number:
                      type: string
                      description: Unique store number of a particular location, as provided by the business
                    location_groups:
                      type: array
                      description: Contains the ID and name of all location groups to which a location
                        belongs. A location in business can belong to multiple location groups.
                      items:
                        type: object
                        properties:
                          location_group_id:
                            type: string
                            description: Unique ID that identifies a location group for the business.
                              This ID is assigned to the location group at the time of creation.
                    store_tags:
                      type: string
                      description: Tags that provide additional details about a particular business location
                    location_extra_attributes:
                      type: object
                      description: Additional information about the location
                      properties:
                        brand:
                          type: string
                          description: Brand name of a subcategory of a business. A parent business may
                            own multiple brands under one umbrella company. For example, Yum! Brands,
                            Inc. owns KFC, Pizza Hut, and Taco Bell.
                        store_times:
                          type: array
                          description: Business hours of a particular location
                          items:
                            type: object
                            properties:
                              day:
                                type: string
                                description: Day of week when a store is open for business
                              start_time:
                                type: string
                                description: Time of day when a store opens
                              end_time:
                                type: string
                                description: Time of day when a store closes
                        additional_url:
                          type: array
                          x-stoplight:
                            id: 8n46yip7lir3e
                          items:
                            x-stoplight:
                              id: r7lxikgkqc8xn
                            type: object
                            properties:
                              label:
                                type: string
                                x-stoplight:
                                  id: suynyomesoxdc
                                description: Label for the additional URL. This additional URL label must
                                  be configured for the business in the Punchh platform; otherwise, the
                                  API will return an error. Contact your Punchh representative for more
                                  information about this Punchh platform configuration.
                              url:
                                type: string
                                x-stoplight:
                                  id: 1v2oirhxsjofv
                                description: 'Custom URL configured for the additional URL. This URL can
                                  link to a location-specific brand webpage, such as catering information,
                                  discounts, private events, reservations, or other custom content beyond
                                  the standard call, order, and directions links. Note: The API returns
                                  an error if you pass a null value in the parameter. This information
                                  is added to the Punchh platform under Store Locations > All Store Locations
                                  > [choose location] > Mobile App.'
                        alternate_store_number:
                          type: string
                          x-stoplight:
                            id: kirpq5cyfae1s
                          description: Alphanumeric alternate store identifier for a specific location,
                            as provided by the business. Punchh does not validate that they are unique
                            across each location. This information is added to the Punchh platform under
                            Store Locations > All Store Locations > [choose location] > Location > Alternate
                            Store Number/Identifier.
                        enable_multiple_redemptions:
                          type: boolean
                          x-stoplight:
                            id: oke04os31yo1b
                          description: 'Enables processing of multiple redemptions for a location. Possible
                            values: true, false. A value of true means multiple redemptions are allowed.
                            This setting is configured in the Punchh platform under Store Locations >
                            All Store Locations > [Choose a location] > Location > Allow Location for
                            Multiple Redemption.'
                    time_zone:
                      type: string
                      description: Time zone in which the business is located
                    validation_type:
                      type: string
                      description: The method of check-in used by a user (e.g., barcode, qr_code, receipt_image,
                        etc.). A blank string indicates the default value of the business.
                    franchisee_id:
                      type: integer
                      description: Unique ID of the franchisee who owns the location. This ID is generated
                        by Punchh.
                    ncr_store_id:
                      type: string
                      x-stoplight:
                        id: vc07yjtvsfqed
                      description: This is required only for businesses that use NCR Silver. This value
                        can be mapped against the location ID or store number of the location.
                    enable_weekly_redemption_report:
                      type: boolean
                      x-stoplight:
                        id: 86tmm12ampuxf
                      description: Enables sharing the weekly redemption report to the location email
                        (applicable only for the franchisee model)
            examples:
              location:
                value:
                  address: ADDRESS_GOES_HERE
                  city: Mountain View
                  country: United States
                  external_store_id: 46ede9b5-287c-4ac5-84f4-86cb0927c96d
                  latitude: 37.406658
                  longitude: -122.109061
                  name: Headquarter
                  phone_number: '1111111111'
                  loc_email: test@example.com
                  post_code: '94040'
                  state: California
                  store_number: ABCDXYZ
                  location_groups:
                  - location_group_id: '2051'
                  - location_group_id: '2052'
                  - location_group_id: '2053'
                  store_tags: WiFi,DriveThru,GiftCard
                  location_extra_attributes:
                    brand: Punchh
                    alternate_store_number: UK@8907
                    enable_multiple_redemptions: true
                    additional_url:
                    - label: reservation
                      url: URL_GOES_HERE
                    store_times:
                    - day: Mon
                      start_time: 5:30 AM
                      end_time: 7:00 PM
                    - day: Tue
                      start_time: 5:30 AM
                      end_time: 8:00 PM
                    - day: Wed
                      start_time: 5:30 AM
                      end_time: 8:00 PM
                    - day: Thu
                      start_time: 5:30 AM
                      end_time: 8:00 PM
                    - day: Fri
                      start_time: 5:30 AM
                      end_time: 8:00 PM
                    - day: Sat
                      start_time: 6:30 AM
                      end_time: 8:00 PM
                    - day: Sun
                      start_time: 6:30 AM
                      end_time: 6:00 PM
                  time_zone: America/Los_Angeles
                  validation_type: qrcode
                  franchisee_id: 1234
                  enable_weekly_redemption_report: false
        description: ''
    patch:
      responses:
        '200':
          $ref: '#/components/responses/locations-object'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    x-stoplight:
                      id: hvz641m9mar4x
              examples:
                Invalid JSON:
                  value:
                    status: 400
                    error: data was not valid JSON
                Required parameter missing:
                  value:
                    error: 'Required parameter missing or the value is empty: location'
                A null value passed in the url parameter in the additional_url array object:
                  value:
                    error: 'Required parameter missing or the value is empty: additional_url_(array number)'
        '401':
          $ref: '#/components/responses/401-unauthorized'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    x-stoplight:
                      id: wphk9ft06qxyg
              examples:
                An invalid URL is passed in additional_url array:
                  value:
                    base:
                    - Reservation URL is an invalid URL
                Additional URL label not configured in Punchh platform:
                  value:
                    errors:
                      additional_url: Given additional URL label is not present in the business configuration.
      summary: Update Location
      description: Edits a location in the database
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/content-type'
      operationId: dashboard_update_location
      tags:
      - Locations
      x-stoplight:
        id: 74736d5611d92
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                location_id:
                  type: integer
                  description: Unique of a particular location. Either `location_id` or `store_number`
                    should be provided. If both are provided, `store_number` will be given priority.
                store_number:
                  type: string
                  description: Unique store number provided by the business. Either `location_id` or `store_number`
                    should be provided. If both are provided, `store_number` will be given priority.
                location:
                  type: object
                  properties:
                    address:
                      type: string
                      description: Full address of a particular business location
                    city:
                      type: string
                      description: City of a particular business location
                    country:
                      type: string
                      description: Country of a particular business location
                    external_store_id:
                      type: string
                      description: External POS identifier configured in the Punchh platform under location
                        attributes via Store Locations > All Store Locations > [choose location] > POS
                        > External POS Store Identifier.
                    latitude:
                      type: number
                      description: Latitude coordinate of a particular business location
                      format: float
                    longitude:
                      type: number
                      description: Longitude coordinate of a particular business location
                      format: float
                    name:
                      type: string
                      description: Name of a particular business location
                    phone_number:
                      type: string
                      description: Phone number of a particular business location
                    location_groups:
                      type: array
                      description: Contains the ID and name of all location groups to which a location
                        belongs. A location in business can belong to multiple location groups.
                      items:
                        type: object
                        properties:
                          location_group_id:
                            type: string
                            description: Unique ID that identifies a location group for the business.
                              This ID is assigned to the location group at the time of creation.
                    store_tags:
                      type: string
                      description: Tags that provide additional details about a particular business location
                    location_extra_attributes:
                      type: object
                      description: Additional information about the location
                      properties:
                        brand:
                          type: string
                          description: Brand name of a subcategory of a business. A parent business may
                            own multiple brands under one umbrella company. For example, Yum! Brands,
                            Inc. owns KFC, Pizza Hut, and Taco Bell.
                        store_times:
                          type: array
                          description: Business hours of a particular location
                          items:
                            type: object
                            properties:
                              day:
                                type: string
                                description: Day of week when a store is open for business
                              start_time:
                                type: string
                                description: Time of day when a store opens
                              end_time:
                                type: string
                                description: Time of day when a store closes
                        online_order_url:
                          type: string
                          description: Online ordering URL of a particular business location
                        ' additional_url':
                          type: array
                          x-stoplight:
                            id: yotebzzvgcolv
                          items:
                            x-stoplight:
                              id: fsga27oktsddh
                            type: object
                            properties:
                              label:
                                type: string
                                x-stoplight:
                                  id: ue6vv7t7w1o4t
                                description: Label for the additional URL. This additional URL label must
                                  be configured for the business in the Punchh platform; otherwise, the
                                  API will return an error. Contact your Punchh representative for more
                                  information about this Punchh platform configuration.
                              url:
                                type: string
                                x-stoplight:
                                  id: dxs424weyvhyv
                                description: Custom URL configured for the additional URL. This URL can
                                  link to a location-specific brand webpage, such as catering information,
                                  discounts, private events, reservations, or other custom content beyond
                                  the standard call, order, and directions links. This information is
                                  added to the Punchh platform under Store Locations > All Store Locations
                                  > [choose location] > Mobile App.
                        alternate_store_number:
                          type: string
                          x-stoplight:
                            id: km7yd9xrz15dz
                          description: Alphanumeric alternate store identifier for a specific location,
                            as provided by the business. Punchh does not validate that they are unique
                            across each location. This information is added to the Punchh platform under
                            Store Locations > All Store Locations > [choose location] > Location > Alternate
                            Store Number/Identifier.
                        enable_multiple_redemptions:
                          type: boolean
                          x-stoplight:
                            id: hm8mjc8uqse8v
                          description: 'Enables processing of multiple redemptions for a location. Possible
                            values: true, false. A value of true means multiple redemptions are allowed.
                            This setting is configured in the Punchh platform under Store Locations >
                            All Store Locations > [Choose a location] > Location > Allow Location for
                            Multiple Redemption.'
                    time_zone:
                      type: string
                      description: Time zone in which the business is located
                    generate_barcodes:
                      type: boolean
                      description: Whether barcodes are generated on the receipt or not
                    loc_email:
                      type: string
                      description: Email address of a particular business location
                    post_code:
                      type: string
                      description: Zip code of a particular business location
                    state:
                      type: string
                      description: State where a particular business is located
                    status:
                      type: string
                      description: 'Whether the location is enabled for check-ins or not. `approved`:
                        Enabled for check-ins. `disapproved`: Disabled for check-ins.'
                    franchise_id:
                      type: integer
                      description: Unique ID of the franchisee who owns the location. This ID is generated
                        by Punchh.
                    ncr_store_id:
                      type: string
                      description: This is required only for businesses that use NCR Silver. This value
                        can be mapped against the location ID or store number of the location.
                enable_weekly_redemption_report:
                  description: Enables sharing the weekly redemption report to the location email (applicable
                    only for the franchisee model)
                  type: boolean
            examples:
              default:
                value:
                  location_id: 306248
                  store_number: ABCDXYZ
                  location:
                    address: ADDRESS_GOES_HERE
                    city: Mountain View
                    country: United States
                    external_store_id: 46ede9b5-287c-4ac5-84f4-86cb0927c96d
                    latitude: 37.406658
                    longitude: -122.109061
                    name: Headquarter7
                    phone_number: '1111111111'
                    location_groups:
                    - location_group_id: '2051'
                    - location_group_id: '2052'
                    - location_group_id: '2053'
                    loc_email: test@example.com
                    post_code: '94040'
                    state: California
                    store_tags: WiFi,DriveThru,GiftCard
                    location_extra_attributes:
                      brand: Punchh
                      online_order_url: https://example.com
                      alternate_store_number: UK@8907
                      enable_multiple_redemptions: true
                      additional_url:
                      - label: reservation
                        url: https://example1.com
                      store_times:
                      - day: Mon
                        start_time: 5:30 AM
                        end_time: 7:00 PM
                      - day: Tue
                        start_time: 5:30 AM
                        end_time: 8:00 PM
                      - day: Wed
                        start_time: 5:30 AM
                        end_time: 8:00 PM
                      - day: Thu
                        start_time: 5:30 AM
                        end_time: 8:00 PM
                      - day: Fri
                        start_time: 5:30 AM
                        end_time: 8:00 PM
                      - day: Sat
                        start_time: 6:30 AM
                        end_time: 8:00 PM
                      - day: Sun
                        start_time: 6:30 AM
                        end_time: 6:00 PM
                    time_zone: America/Los_Angeles
                    generate_barcodes: true
    delete:
      responses:
        '204':
          description: A successful response is a blank response with HTTP status code 204.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/401-unauthorized'
      summary: Delete Location
      description: Deletes a business location from the database
      operationId: dashboard_delete_location
      tags:
      - Locations
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      x-stoplight:
        id: f3dd8a2ae9d4e
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                location_id:
                  type: integer
                  description: Unique ID of a particular location. This is generated by Punchh.
                store_number:
                  type: string
                  description: Unique store number provided by the business
            examples:
              default:
                value:
                  location_id: 306248
                  store_number: ABCDXYZ
  /api2/dashboard/location_groups:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    location_group_id:
                      type: integer
                      description: Unique ID that identifies a location group for the business. This ID
                        is assigned to the location group at the time of creation.
                    name:
                      type: string
                      description: Name of the location group that is assigned by the admin who created
                        it
                    locations:
                      type: array
                      items:
                        type: object
                        properties:
                          location_id:
                            type: integer
                            description: Unique ID of a particular location. This is generated by Punchh.
                          store_number:
                            type: string
                            description: Unique store number provided by the business
              examples:
                default:
                  value:
                  - location_group_id: 1234
                    name: Group 1
                    locations:
                    - location_id: 312301
                      store_number: 005806
                    -

# --- truncated at 32 KB (414 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/punchh/refs/heads/main/openapi/punchh-platform-functions-api-openapi.yml