Punchh Collectibles API

openapi: 3.2.0
info:
  title: Mobile Collectibles API
  version: '1.0'
  contact:
    name: Punchh Dev Support
    url: https://developers.punchh.com
  description: Punchh provides a robust platform for offering loyalty programs to customers.
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
tags:
- name: Collectibles
paths:
  /api2/mobile/collectibles:
    get:
      summary: List Collectibles
      operationId: get-api2-mobile-collectibles
      description: 'Returns the list of collectibles configured for a business. Supports pagination and optional filtering by collectible category.


        Note: The Digital Collectibles feature must be enabled for the business in the Punchh platform. Contact your Punchh representative to update this Punchh platform configuration.

        Dashboard > Miscellaneous Config > Enable Digital Collectibles-->'
      tags:
      - Collectibles
      parameters:
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/User-Agent'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        collectible_id:
                          type: integer
                          description: Unique ID of the collectible
                        collectible_name:
                          type: string
                          description: Name of the collectible
                        image:
                          type: string
                          description: URL of the collectible image
                        description:
                          type: string
                          description: Description of the collectible
                        sequence:
                          type: integer
                          description: Display order of the collectible. Null if no ordering is configured.
                        collectible_category_name:
                          type: string
                          description: Name of the category the collectible belongs to. Null if not mapped to any category.
                        collectible_category_id:
                          type: integer
                          description: ID of the category the collectible belongs to. Null if not mapped to any category.
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        description: Current page number
                      next_page:
                        type: integer
                        description: Next page number. Null if there is no next page.
                      prev_page:
                        type: integer
                        description: Previous page number. Null if there is no previous page.
                      total_pages:
                        type: integer
                        description: Total number of pages
                      total_count:
                        type: integer
                        description: Total number of collectibles
              examples:
                Collectible without category:
                  value:
                    data:
                    - collectible_name: Immortal
                      collectible_id: 123
                      image: IMAGE_URL_GOES_HERE
                      description: DESCRIPTION_GOES_HERE
                      sequence: null
                      collectible_category_name: null
                      collectible_category_id: null
                    meta:
                      current_page: 1
                      next_page: 2
                      prev_page: null
                      total_pages: 4
                      total_count: 33
                Collectible with category:
                  value:
                    data:
                    - collectible_name: Test
                      collectible_id: 123
                      image: IMAGE_URL_GOES_HERE
                      description: DESCRIPTION_GOES_HERE
                      sequence: null
                      collectible_category_name: AutoCat_1770282575250
                      collectible_category_id: 67
                    meta:
                      current_page: 1
                      next_page: null
                      prev_page: null
                      total_pages: 1
                      total_count: 1
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      client:
                        type: string
              examples:
                Missing client parameter:
                  value:
                    errors:
                      client: Required parameter missing or the value is empty.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      unauthorized:
                        type: array
                        items:
                          type: string
                  error:
                    type: string
                  message:
                    type: string
              examples:
                Invalid or missing access token:
                  value:
                    errors:
                      unauthorized:
                      - An active access token must be used to query information about the current user.
                Invalid client ID:
                  value:
                    error: INVALID_CLIENT
                    message: Client ID is incorrect. Please verify client param or contact support.
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: string
              examples:
                Feature disabled:
                  value:
                    errors: Your current loyalty program configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: Unique client identifier
                page:
                  type: integer
                  description: Page number for pagination
                per_page:
                  type: integer
                  description: Number of records to return per page
                collectible_category_id:
                  type: string
                  description: Comma-separated collectible category IDs to filter by (e.g., "67,69,75"). Multiple category IDs must be comma-separated.
              required:
              - client
            examples:
              Request Example:
                value:
                  client: CLIENT_GOES_HERE
                  page: 1
                  per_page: 33
                  collectible_category_id: 67,69,75
  /api2/mobile/collectibles/{collectible_id}:
    get:
      summary: Fetch Collectible Details
      operationId: get-api2-mobile-collectibles-collectible_id
      description: 'Returns the details of a specific collectible by its ID, including the active campaigns associated with it.

        The API enforces the following validations and business rules:

        * Only one collectible_id is allowed per request.

        * Responses are limited to collectibles associated with the requesting business.

        * Only active campaigns are included in the response.

        * Campaigns are sorted by start date in ascending order, with the earliest starting campaign displayed first.


        Note: The Digital Collectibles feature must be enabled for the business in the Punchh platform. Contact your Punchh representative to update this Punchh platform configuration.

        Dashboard > Miscellaneous Config > Enable Digital Collectibles-->'
      tags:
      - Collectibles
      parameters:
      - schema:
          type: integer
        in: path
        name: collectible_id
        required: true
        description: The unique identifier of the collectible to fetch details for.
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/Accept-Language'
      - $ref: '#/components/parameters/punchh-app-device-id'
      - $ref: '#/components/parameters/User-Agent'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  collectible_id:
                    type: integer
                    description: Unique ID of the collectible
                  collectible_name:
                    type: string
                    description: Name of the collectible
                  image:
                    type: string
                    description: URL of the collectible image
                  description:
                    type: string
                    description: Description of the collectible
                  sequence:
                    type: integer
                    description: Display order of the collectible. Null if no ordering is configured.
                  collectible_category_name:
                    type: string
                    description: Name of the category the collectible belongs to. Null if not mapped to any category.
                  collectible_category_id:
                    type: integer
                    description: ID of the category the collectible belongs to. Null if not mapped to any category.
                  disappear_date:
                    type: string
                    format: date-time
                    description: Date and time when the collectible disappears. Null if it does not disappear.
                  timezone:
                    type: string
                    description: Timezone associated with the collectible disappearance date
                  status:
                    type: string
                    description: Current status of the collectible (e.g., Active)
                  share_message:
                    type: string
                    description: Message displayed when the collectible is shared
                  campaign_details:
                    type: array
                    description: List of campaigns associated with this collectible
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: Name of the campaign
                        description:
                          type: string
                          description: Description of the campaign
                        type:
                          type: string
                          description: Type of campaign (e.g., ChallengeCampaign)
                        start_date:
                          type: string
                          description: Start date of the campaign. Null if not set.
                        end_date:
                          type: string
                          description: End date of the campaign. Null if not set.
                        timezone:
                          type: string
                          description: Timezone associated with the campaign start and end dates
              examples:
                Response Example:
                  value:
                    collectible_id: 123
                    collectible_name: Test Collectible
                    image: IMAGE_URL_GOES_HERE
                    description: Test Collectible
                    sequence: 6
                    collectible_category_name: Easter 2026
                    collectible_category_id: 7
                    disappear_date: '2027-03-19T18:29:59Z'
                    timezone: Asia/Kolkata
                    status: Active
                    share_message: Test Collectible
                    campaign_details:
                    - name: Every X universal new2
                      description: ''
                      type: ChallengeCampaign
                      start_date: null
                      end_date: null
                      timezone: Asia/Kolkata
                    - name: segment auto enrolled
                      description: ''
                      type: ChallengeCampaign
                      start_date: '2026-04-04'
                      end_date: '2026-04-30'
                      timezone: Asia/Kolkata
                    - name: With Collectible
                      description: With Collectible
                      type: ChallengeCampaign
                      start_date: '2026-04-18'
                      end_date: '2026-05-30'
                      timezone: America/Los_Angeles
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      unauthorized:
                        type: array
                        items:
                          type: string
              examples:
                Invalid or missing access token:
                  value:
                    errors:
                      unauthorized:
                      - An active access token must be used to query information about the current user.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: string
              examples:
                Collectible not found:
                  value:
                    errors: Collectible not found.
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: string
              examples:
                Feature disabled:
                  value:
                    errors: Your current configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: OAuth client ID provided by the business
              required:
              - client
            examples:
              Request Example:
                value:
                  client: CLIENT_GOES_HERE
  /api2/mobile/users_collectibles:
    get:
      summary: Fetch User Collectibles
      operationId: get-api2-mobile-users_collectibles
      description: 'Returns the list of collectibles earned by a user. Supports pagination and optional filtering by collectible category.


        Note: The Digital Collectibles feature must be enabled for the business in the Punchh platform. Contact your Punchh representative to update this Punchh platform configuration.

        Dashboard > Miscellaneous Config > Enable Digital Collectibles-->'
      tags:
      - Collectibles
      parameters:
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept-Language'
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/User-Agent'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        collectible_id:
                          type: integer
                          description: Unique ID of the collectible
                        collectible_name:
                          type: string
                          description: Name of the collectible
                        image:
                          type: string
                          description: URL of the collectible image
                        count:
                          type: integer
                          description: Number of times the user has earned this collectible
                        disappear_at:
                          type: string
                          description: Date and time when the collectible disappears. Null if it does not disappear.
                        sequence:
                          type: integer
                          description: Display order of the collectible. Null if no ordering is configured.
                        collectible_category_id:
                          type: integer
                          description: ID of the category the collectible belongs to. Null if not mapped to any category.
                        collectible_category_name:
                          type: string
                          description: Name of the category the collectible belongs to. Null if not mapped to any category.
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        description: Current page number
                      next_page:
                        type: integer
                        description: Next page number. Null if there is no next page.
                      prev_page:
                        type: integer
                        description: Previous page number. Null if there is no previous page.
                      total_pages:
                        type: integer
                        description: Total number of pages
                      total_count:
                        type: integer
                        description: Total number of collectibles
              examples:
                With collectibles:
                  value:
                    data:
                    - collectible_id: 116
                      collectible_name: easter 7
                      image: IMAGE_URL_GOES_HERE
                      count: 1
                      disappear_at: null
                      sequence: 1
                      collectible_category_id: 7
                      collectible_category_name: Easter 2026
                    - collectible_id: 103
                      collectible_name: without category3
                      image: IMAGE_URL_GOES_HERE
                      count: 1
                      disappear_at: '2026-03-28T09:00:00Z'
                      sequence: 4
                      collectible_category_id: null
                      collectible_category_name: null
                    meta:
                      current_page: 1
                      next_page: 2
                      prev_page: null
                      total_pages: 2
                      total_count: 22
                No collectibles:
                  value:
                    data: []
                    meta:
                      current_page: 1
                      next_page: null
                      prev_page: null
                      total_pages: 0
                      total_count: 0
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      unauthorized:
                        type: array
                        items:
                          type: string
              examples:
                Invalid or missing access token:
                  value:
                    errors:
                      unauthorized:
                      - An active access token must be used to query information about the current user.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                  error:
                    type: string
              examples:
                Incorrect endpoint:
                  value:
                    status: 404
                    error: Not Found
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: string
              examples:
                Feature disabled:
                  value:
                    errors: Your current configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue.
      x-stoplight:
        id: collectibles-users-get
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: OAuth client ID provided by the business
                page:
                  type: integer
                  default: 1
                  description: Page number for pagination. If not specified, returns the first page by default.
                per_page:
                  type: integer
                  default: 20
                  description: Number of records to return per page. Defaults to 20 if not specified.
                include_disappeared_collectibles:
                  type: boolean
                  default: false
                  description: Whether to include collectibles that have disappeared. Defaults to false.
                collectible_category_id:
                  type: string
                  description: 'Filters collectibles by category. Accepts a single ID or multiple comma-separated IDs.


                    - NULL (not provided) → Returns all categories, including collectibles with no category.

                    - 0 → Returns only collectibles with no category.

                    - Single or multiple IDs (e.g., "0,1,2,3") → Returns collectibles matching those category IDs.'
              required:
              - client
            examples:
              Request Example:
                value:
                  client: CLIENT_GOES_HERE
components:
  parameters:
    User-Agent:
      schema:
        type: string
        default: AppName/AppVersion/BuildNumber (OS; Model; MANUFACTURER; MODEL; OS Version)
      in: header
      name: User-Agent
      description: Used to identify the software, device, and application initiating the request, providing information about the client to the server. For details, see [User Agent](/docs/dev-portal-mobile/additional-topics/user-agent).
      required: true
    punchh-app-device-id:
      schema:
        type: string
        default: APP_DEVICE_ID_GOES_HERE
      name: punchh-app-device-id
      in: header
      required: true
      description: The app device ID helps Punchh identify each device so that certain rewards can be awarded individually to each device instead of per user. For example, the sign-up reward is given to each device ID to prevent fraudulent sign-ups so that a user cannot do repeated sign-ups from a single device to get rewards. It should not change even if the user resets a device. See the [sample code](/docs/dev-portal-mobile/56657769b1422-headers-and-caching#generating-the-punchh-app-device-id-header) to generate the punchh-app-device-id header.
    Authorization:
      schema:
        type: string
        default: Bearer ACCESS_TOKEN_GOES_HERE
      name: Authorization
      in: header
      description: Used to authorize the request with access_token. It should be supplied as `Bearer ACCESS_TOKEN_GOES_HERE`.
      required: true
    Content-Type:
      schema:
        type: string
        default: application/json
      name: Content-Type
      in: header
      description: Set this header to <b>application/json</b>.
      required: true
    Accept:
      schema:
        type: string
        default: application/json
      name: Accept
      in: header
      description: Advertises which content types the client is able to understand
      required: true
    signature:
      schema:
        type: string
        default: '{{$$.env.signature}}'
      name: x-pch-digest
      in: header
      description: The [signature](/docs/dev-portal-mobile/additional-topics/signature-sha256) for the API call
      required: true
    Accept-Language:
      schema:
        type: string
        default: en
      name: Accept-Language
      in: header
      description: Preferred language
x-stoplight:
  id: bf6eddb435209
x-ext-urls: {}