Punchh Subscription API - Online Ordering

info:
  title: Subscription API - Online Ordering
  version: '1.0'
  description: 'Subscriptions is an add-on Punchh loyalty product that allows businesses to create subscription
    plans to generate up-front revenue and offers benefits in addition to the standard benefits that unsubscribed
    members of the loyalty program receive. The Subscription APIs are designed in a way that businesses
    can programatically achieve the benefits of the subscription for their guest in a mobile app or website.
    Also, there are aspects that require calling the API without any guest authentication (e.g., to control
    the auto-renewal of the subscription on behalf of the guest). '
  contact:
    name: Punchh Dev Support
    url: https://developers.punchh.com
paths:
  /api/auth/subscriptions:
    parameters: []
    get:
      summary: Fetch Active Purchasable Subscription Plans
      operationId: post-api-auth-subscriptions
      responses:
        '200':
          description: Success response if the business supports subscriptions
          headers: {}
          content:
            application/json:
              schema:
                type: array
                minItems: 1
                uniqueItems: true
                x-examples:
                  example-1:
                  - name: test v1
                    description: ''
                    miscellaneous: ''
                    validity: 30
                    start_time: '2021-04-28T13:59:47+05:30'
                    end_time: '2021-05-28T13:59:47+05:30'
                    signup_end_date: '2021-05-18T13:59:47+05:30'
                    plan_id: 4
                    purchase_price: 12
                    image: test-image.png
                  - name: Test3
                    description: hello test 3
                    miscellaneous: null
                    validity: null
                    start_time: '2021-04-28T13:59:47+05:30'
                    end_time: '2021-05-28T13:59:47+05:30'
                    signup_end_date: '2021-05-18T13:59:47+05:30'
                    plan_id: 3
                    purchase_price: 12
                    image: null
                  - name: Test2
                    description: hello test 2
                    miscellaneous: null
                    validity: null
                    start_time: '2021-04-28T13:59:47+05:30'
                    end_time: '2021-05-28T13:59:47+05:30'
                    signup_end_date: '2021-05-18T13:59:47+05:30'
                    plan_id: 2
                    purchase_price: 12
                    image: null
                  - name: Test1
                    description: hello test
                    miscellaneous: null
                    validity: null
                    start_time: '2021-04-28T13:59:47+05:30'
                    end_time: '2021-05-28T13:59:47+05:30'
                    signup_end_date: '2021-05-18T13:59:47+05:30'
                    plan_id: 1
                    purchase_price: 12
                    image: null
                description: Array of the active subscription plans
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      minLength: 1
                      description: 'Name of the subscription plan as provided by an admin at the time
                        of subscription plan creation


                        Note: The subscription `name` is returned in the language specified in the Accept-Language
                        request header, provided the name has been translated into the relevant language
                        in the Punchh platform. If the translation is not available, then no value is
                        returned for this parameter in the API response. For example, if the header specifies
                        “fr” (French), the subscription name is returned in French only if a French translation
                        for the name is configured in the Punchh platform.'
                    description:
                      type: string
                      description: 'Text description of the subscription plan as configured by an admin
                        on the subscription plan. This is used to explain the offerings of the subscription
                        plan to guests.


                        Note: The subscription `description` is returned in the language specified in
                        the Accept-Language request header, provided the description has been translated
                        into the relevant language in the Punchh platform. If the translation is not available,
                        then no value is returned for this parameter in the API response. For example,
                        if the header specifies “fr” (French), the subscription description is returned
                        in French only if a French translation for the description is configured in the
                        Punchh platform.'
                    miscellaneous:
                      type: string
                      description: 'Free-form text field that can be used by businesses to enter additional
                        information or a JSON code snippet for greater customization in the mobile app


                        Note: The subscription `miscellaneous` information is returned in the language
                        specified in the Accept-Language request header, provided it has been translated
                        into the relevant language in the Punchh platform. If the translation is not available,
                        then no value is returned for this parameter in the API response. For example,
                        if the header specifies “fr” (French), the subscription miscellaneous information
                        is returned in French only if a French translation for the miscellaneous is configured
                        in the Punchh platform.'
                    validity:
                      type: integer
                      format: int32
                      description: Number of days for which one unit of the subscription plan remains
                        valid after purchase
                      examples:
                      - 30
                    start_time:
                      type: string
                      minLength: 1
                      format: date-time
                      description: Date and time (in ISO 8601 format) from which the subscription plan
                        can be purchased by guests
                      examples:
                      - '2023-04-28T13:59:47+05:30'
                    end_time:
                      type: string
                      minLength: 1
                      format: date-time
                      description: Date and time (in ISO 8601 format) until which the subscription plan
                        can be purchased by guests
                      examples:
                      - '2023-04-28T13:59:47+05:30'
                    signup_start_date:
                      type: string
                      description: Date and time (in ISO 8601 format) after which the subscription plan
                        can be purchased by guests in advance. This can be used by businesses to make
                        a plan available for purchase before it actually starts. Any subscriptions bought
                        after this date and before the start date of the subscription plan will start
                        from the `start_time` of the Subscription Plan.
                      format: date-time
                      examples:
                      - '2023-04-28T13:59:47+05:30'
                    signup_end_date:
                      type: string
                      minLength: 1
                      format: date-time
                      description: Date and time (in ISO 8601 format) after which the subscription plan
                        cannot be purchased by guests. This is the purchase cut-off time, and a business
                        can use it to nudge guests into purchasing a subscription.
                      examples:
                      - '2023-04-28T13:59:47+05:30'
                    subscriber_capping:
                      type: number
                      description: Maximum number of unique active subscribers for a plan. If the number
                        of active subscribers reaches this limit, fresh purchases in that plan will be
                        stopped.
                      examples:
                      - 400
                    external_plan_identifier:
                      type: string
                      description: UPC/SKU of the subscription plan as present on third-party applications
                        of enterprise businesses and is configured on this subscription plan. This will
                        be stored in the database, and the business can use it for analytics purposes.
                    plan_id:
                      type: integer
                      description: System-generated unique ID of a subscription plan created in the Punchh
                        platform
                      format: int64
                      examples:
                      - 10
                    purchase_price:
                      type: number
                      format: float
                      description: Cost of purchase of one unit of a subscription plan
                      examples:
                      - 12.32
                    image:
                      type: string
                      minLength: 1
                      description: Cover image of a subscription plan uploaded at the time of subscription
                        plan creation
                      examples:
                      - test-image.png
                    time_zone:
                      type: string
                      description: Time zone configured for the subscription plan (e.g., "America/Los_Angeles”
                        )
                    plan_image_url:
                      type: string
                      description: URL of the image that is configured for a specific subscription plan
                    active_subscribers:
                      type: number
                      description: Number of unique active subscribers of the plan
                      examples:
                      - 251
                    enable_multibenefit:
                      type: boolean
                      description: "Indicates whether the subscription plan has multi-benefit enabled,\
                        \ allowing up to 5 benefits to be configured on a single plan. Once enabled on\
                        \ a plan, this setting cannot be disabled. \n\nThe <b>Enable multibenefit</b>\
                        \ setting under Wallet and Passes > Passes > Subscription Plans > Plan Details\
                        \ is only available when the multi-benefit subscription feature is enabled for\
                        \ the business. Contact your Punchh representative to update this Punchh platform\
                        \ configuration.\n"
                    purchasable_location_ids:
                      type: array
                      items:
                        type: integer
                      description: "An array of location IDs where the subscription plan is available\
                        \ for purchase. When configured, the plan will only appear as purchasable at these\
                        \ specific locations. If empty or not set, the plan is purchasable at all locations.\
                        \ \n\nReturned only when the multi-benefit subscription feature is enabled for\
                        \ the business, and the subscription plan's <b>Enable multibenefit</b> setting\
                        \ under Wallet and Passes > Passes > Subscription Plans > Plan Details is enabled\
                        \ in the Punchh platform. Contact your Punchh representative to update this Punchh\
                        \ platform configuration.\n"
                    purchasable_tag_ids:
                      type: array
                      items:
                        type: integer
                      description: "An array of location group (tag) IDs where the subscription plan is\
                        \ available for purchase. Location groups allow admins to scope purchasability\
                        \ to a set of locations defined by a reusable group. Works in conjunction with\
                        \ purchasable_location_ids — admins can select individual locations, location\
                        \ groups, or both. \n\nReturned only when the multi-benefit subscription feature\
                        \ is enabled for the business, and the subscription plan's <b>Enable multibenefit</b>\
                        \ setting under Wallet and Passes > Passes > Subscription Plans > Plan Details\
                        \ is enabled in the Punchh platform. Contact your Punchh representative to update\
                        \ this Punchh platform configuration.\n"
                    multiple_effective_locations_name:
                      type: string
                      description: "A human-readable display name summarizing the effective purchasable\
                        \ locations configured for the plan (e.g., selected location names or location\
                        \ group names). Useful for rendering location-scope information on guest-facing\
                        \ surfaces. \n\nReturned only when the multi-benefit subscription feature is enabled\
                        \ for the business, and the subscription plan's <b>Enable multibenefit</b> setting\
                        \ under Wallet and Passes > Passes > Subscription Plans > Plan Details is enabled\
                        \ in the Punchh platform. Contact your Punchh representative to update this Punchh\
                        \ platform configuration.\n"
              examples:
                example:
                  value:
                  - name: SUBSCRIPTION_NAME_GOES_HERE
                    description: DESCRIPTION_GOES_HERE
                    miscellaneous: MISC_INFORMATION_GOES_HERE
                    validity: 30
                    start_time: '2023-05-28T13:59:47+05:30'
                    end_time: '2023-09-28T13:59:47+05:30'
                    signup_start_date: '2023-05-28T13:59:47+05:30'
                    signup_end_date: '2023-09-28T13:59:47+05:30'
                    subscriber_capping: 500
                    external_plan_identifier: null
                    plan_id: 10
                    purchase_price: 100
                    image: test-image.png
                    time_zone: Asia/Kolkata
                    plan_image_url: PLAN_IMAGE_URL_GOES_HERE
                    active_subscribers: 250
                    enable_multibenefit: true
                    purchasable_location_ids:
                    - 2
                    - 11
                    purchasable_tag_ids:
                    - 1
                    - 2
                    multiple_effective_locations_name: location-name-1, location-name-10, PineCrossing,
                      Eagle Creek
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    errors:
                      client: Required parameter missing or the value is empty.
                properties:
                  errors:
                    type: object
                    required:
                    - client
                    properties:
                      client:
                        type: string
                        minLength: 1
                        examples:
                        - Required parameter missing or the value is empty.
                required:
                - errors
              examples:
                example:
                  value:
                    errors:
                      client: Required parameter missing or the value is empty.
        '412':
          description: Precondition Failed
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    errors:
                      invalid_signature:
                      - Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is
                properties:
                  errors:
                    type: object
                    properties:
                      invalid_signature:
                        type: array
                        items:
                          type: string
                          examples:
                          - Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is
              examples:
                example:
                  value:
                    errors:
                      invalid_signature:
                      - Signature doesn't match. For information about generating the x-pch-digest header,
                        see https://developers.punchh.com.
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    errors:
                      disabled_feature: Your current loyalty program configuration does not support this
                        feature. Please connect with your Customer Success representative for resolution
                        of the issue.
                properties:
                  errors:
                    type: object
                    properties:
                      disabled_feature:
                        type: string
                        minLength: 1
                        examples:
                        - Your current loyalty program configuration does not support this feature. Please
                          connect with your Customer Success representative for resolution of the issue.
              examples:
                example:
                  value:
                    errors:
                      disabled_feature: Your current loyalty program configuration does not support this
                        feature. Please connect with your Customer Success representative for resolution
                        of the issue.
      description: This API allows online ordering vendors to get a list of all subscription plans that
        are available for purchase.
      parameters:
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Accept-Language'
      - $ref: '#/components/parameters/x-pch-digest'
      - $ref: '#/components/parameters/Content-Type'
      x-stoplight:
        id: 78c0011bde123
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                client:
                  type: string
                  description: OAuth client ID provided by the business
                  default: CLIENT_GOES_HERE
              required:
              - client
            examples:
              application json:
                value:
                  client: CLIENT_GOES_HERE
    post:
      summary: Purchase Subscription
      operationId: post-api-auth-subscriptions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  example-1:
                    subscription_id: '24'
                    start_time: '2021-04-28T13:59:47+05:30'
                    end_time: '2021-04-28T13:59:47+05:30'
                properties:
                  subscription_id:
                    type: integer
                    description: System-generated unique ID of the subscription plan that is issued for
                      a guest
                  start_time:
                    type: string
                    minLength: 1
                    format: date-time
                    description: Date and time (in ISO 8601 format) from which the subscription plan purchased
                      for the guest will become active
                    examples:
                    - '2021-04-28T13:59:47+05:30'
                  end_time:
                    type: string
                    minLength: 1
                    format: date-time
                    description: Date and time (in ISO 8601 format) until which the subscription plan
                      purchased for the guest will remain active
                    examples:
                    - '2021-04-28T13:59:47+05:30'
                  external_plan_identifier:
                    type: string
                    description: UPC/SKU of the subscription plan as present on third-party applications
                      of enterprise businesses and is configured on this subscription plan. This will
                      be stored in the database, and the business can use it for analytics purposes.
                required:
                - subscription_id
                - start_time
                - end_time
              examples:
                example:
                  value:
                    subscription_id: 23
                    start_time: '2021-04-28T13:59:47+05:30'
                    end_time: '2021-04-28T13:59:47+05:30'
                    external_plan_identifier: EXTERNAL_PLAN_IDENTIFIER GOES HERE
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    errors:
                      client: Required parameter missing or value empty.
                properties:
                  errors:
                    type: object
                    required:
                    - client
                    properties:
                      client:
                        type: string
                        minLength: 1
                        examples:
                        - Required parameter missing or value empty.
                required:
                - errors
              examples:
                example:
                  value:
                    errors:
                      client: Required parameter missing or value empty.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    errors:
                      unauthorized:
                      - An active access token must be used to query information about the current user.
                properties:
                  errors:
                    type: object
                    required:
                    - unauthorized
                    properties:
                      unauthorized:
                        type: array
                        items:
                          type: string
                          examples:
                          - An active access token must be used to query information about the current
                            user.
                required:
                - errors
              examples:
                example:
                  value:
                    errors:
                      unauthorized:
                      - An active access token must be used to query information about the current user.
        '412':
          description: Precondition Failed
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    errors:
                      invalid_signature:
                      - Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is
                properties:
                  errors:
                    type: object
                    required:
                    - invalid_signature
                    properties:
                      invalid_signature:
                        type: array
                        items:
                          type: string
                          examples:
                          - Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is
                required:
                - errors
              examples:
                example:
                  value:
                    errors:
                      invalid_signature:
                      - Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  example-1:
                    errors:
                      disabled_feature: Your current loyalty program configuration does not support this
                        feature. Please connect with your Customer Success representative for resolution
                        of the issue.
                properties:
                  errors:
                    type: object
                    properties:
                      disabled_feature:
                        type: string
                        minLength: 1
                        examples:
                        - Your current loyalty program configuration does not support this feature. Please
                          connect with your Customer Success representative for resolution of the issue.
                required:
                - errors
              examples:
                Subscription Feature is not configured:
                  value:
                    errors:
                      disabled_feature: Your current loyalty program configuration does not support this
                        feature. Please connect with your Customer Success representative for resolution
                        of the issue.
                Invalid Plan ID:
                  value:
                    errors:
                      invalid_request: Invalid Plan ID
                Auto renewal is set as true for a single use subscription:
                  value:
                    errors:
                      base:
                      - This is a single use subscription and cannot be renewed automatically. Please
                        check request to send 'auto_renewal' as 'false'.
                Purchase price Null or Negative:
                  value:
                    errors:
                      price: Price must be greater than or equal to 0
                Start time Null:
                  value:
                    errors:
                      start_time: Start time cannot be blank
                End time is Null:
                  value:
                    errors:
                      end_time: End time cannot be blank
                Purchase call made is past the signup end time or end time of the plan:
                  value:
                    errors:
                      plan_expired: Plan has expired
                Recurring payments option is disabled:
                  value:
                    errors:
                      recurring_payment_off_for_adapter:
                      - Payment Service not available.
      description: 'This API supports the purchase of a subscription plan created in the Punchh platform.


        If the Single Use setting is enabled for the subscription plan, and if you send auto_renewal as
        `true` in the Purchase Subscription API, then the API returns an error: This is a single use subscription
        and cannot be renewed automatically. Please check the request to send auto_renewal as false.'
      parameters:
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/x-pch-digest'
      - schema:
          type: string
          default: en
        in: header
        name: Accept-Language
        description: Language parameter
      - $ref: '#/components/parameters/Authorization'
      x-stoplight:
        id: d135642ff639e
      requestBody:
        content:
          application/json:
            schema:
              type: object
              x-examples:
                example-1:
                  plan_id: 23
                  start_time: '2021-04-28T13:59:47+05:30'
                  end_time: '2021-05-28T13:59:47+05:30'
                  purchase_price: '23.34'
                  auto_renewal: 'true'
              properties:
                client:
                  type: string
                  description: Client key of the business
                authentication_token:
                  type: string
                  description: 'The authentication token of the user, required if the `HTTP_AUTHORIZATION`
                    header is not added. You can retrieve this from the response of a successful sign
                    in API call or through the [SSO process](/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile). '
                plan_id:
                  type: integer
                  description: System-generated unique ID of a subscription plan created in the Punchh
                    platform. A subscription based on this plan ID will be issued to the guest when a
                    purchase call is made.
                  examples:
                  - 23
                start_time:
                  type: string
                  minLength: 1
                  format: date-time
                  description: 'Date and time (in ISO 8601 format) from which the subscription being issued
                    will become active '
                  examples:
                  - '2021-04-28T13:59:47+05:30'
                end_time:
                  type: string
                  minLength: 1
                  format: date-time
                  description: 'Date and time (in ISO 8601 format) until which the subscription being
                    issued will remain active '
                  examples:
                  - '2021-04-28T13:59:47+05:30'
                purchase_price:
                  type: number
                  format: float
                  description: Price at which one unit of the subscription plan is purchased
                  examples:
                  - 23.45
                auto_renewal:
                  type: boolean
                  default: false
                  description: A guest’s preference of having a newly purchased subscription plan get
                    automatically renewed per the plan's schedule. Third parties where auto renewal is
                    considered default should send this value as "true".
                payment_card_uuid:
                  type: string
                  description: Unique digital identifier/token of the user's credit card can be referred
                    to as the uuid of the saved payment card, required if a saved payment card is used
                    for payments. The transaction token is issued by a payment processor used by a business.
              required:
              - client
              - authentication_token
              - plan_id
              - start_time
              - end_time
              - purchase_price
              - auto_renewal
            examples:
              example:
                value:
                  client:

# --- truncated at 32 KB (80 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/punchh/refs/heads/main/openapi/punchh-online-ordering-subscription-openapi.yml