Punchh Subscription API - Platform Functions

info:
  title: Subscription API - Platform Functions
  version: '1.0'
  contact:
    name: Punchh Dev Support
    url: https://developers.punchh.com
  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).'
paths:
  /api2/dashboard/subscriptions/purchase:
    post:
      summary: Purchase Subscription
      operationId: post-api2-dashboard-subscriptions-purchase
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  example-1:
                    subscription_id: 1234
                    start_time: '2021-05-18 11:34:46'
                    end_time: '2021-05-28 11:34:46'
                    external_plan_identifier: EXTERNAL_PLAN_IDENTIFIER_GOES_HERE
                    location_id: 12345
                properties:
                  subscription_id:
                    type: integer
                    format: int64
                    description: System-generated unique ID of the subscription that is issued for a guest
                    examples:
                    - 123
                  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-05-18 11:34:46'
                  end_time:
                    type: string
                    minLength: 1
                    format: date-time
                    description: Date and time (in ISO 8601 format) until the subscription plan purchased
                      for the guest will remain active
                    examples:
                    - '2021-05-28 11:34:46'
                  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. '
                  location_id:
                    type: integer
                    x-stoplight:
                      id: 2y9gerkqfxe32
                    description: ID of a valid Punchh location where the subscription plan is purchased.
                      It identifies the origin of the subscription purchase for the loyalty guest. If
                      an invalid or missing location_id is passed, the API returns a 400 Bad Request error
                      with the message "Invalid or missing location_id".
                required:
                - subscription_id
                - start_time
                - end_time
        '400':
          description: Bad Request - Invalid or missing location_id
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    x-stoplight:
                      id: azkv213niqwq4
              examples:
                Invalid or missing location_id:
                  value:
                    error: Invalid or missing location_id
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    error: You need to sign in or sign up before continuing.
                properties:
                  error:
                    type: string
                    minLength: 1
                    examples:
                    - You need to sign in or sign up before continuing.
                required:
                - error
              examples:
                example:
                  value:
                    error: You need to sign in or sign up before continuing.
        '406':
          description: Not Acceptable
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    invalid: Subscription cannot be renewed.
                properties:
                  invalid:
                    type: string
                    minLength: 1
                    examples:
                    - Subscription cannot be renewed.
              examples:
                Invalid User Subscription:
                  value:
                    invalid_subscription: Invalid User Subscription.
        '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:
                Subscriptions is not enabled:
                  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:
                      base:
                      - 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'.
                Plan not active:
                  value:
                    errors:
                      base:
                      - Plan is not active.
                Plan Expired:
                  value:
                    errors:
                      base:
                      - Plan has expired.
                Plan is not available for purchase:
                  value:
                    errors:
                      base:
                      - Plan is not available for purchase.
                Start time is blank:
                  value:
                    errors:
                      start_time:
                      - Start time can't be blank
                End Time is Blank:
                  value:
                    errors:
                      end_time:
                      - End time can't be blank
                Invalid Price:
                  value:
                    errors:
                      price:
                      - Price is not a number
                Recurring payments option is disabled:
                  value:
                    errors:
                      recurring_payment_off_for_adapter:
                      - Payment Service not available.
      parameters:
      - schema:
          type: string
        in: header
        name: Content-Type
        description: application/json
        required: true
      - schema:
          type: string
        in: header
        name: Accept
        description: application/json
        required: true
      - schema:
          type: string
        in: header
        name: Authorization
        description: Bearer token for admin authorization, who is making a call on behalf of the customer
        required: true
      description: 'This API allows third-party platforms (e.g., middleware that interfaces with the mobile
        app of the business) to purchase a new subscription plan in the Punchh platform without the need
        for guests to be logged in to the Punchh platform.


        If a business is migrating active subscriptions from an incumbent system to the Punchh platform,
        the subscription ID for each user in the incumbent system can be mapped to the corresponding subscription
        ID 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.'
      x-stoplight:
        id: 31a7819307f07
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: integer
                  format: int64
                  description: 'System-generated unique ID of a guest created on the Punchh platform

                    '
                  examples:
                  - 1234
                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-05-18 11:34:46'
                plan_id:
                  type: integer
                  format: int64
                  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:
                  - 12
                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-05-28 11:34:46'
                purchase_price:
                  type: number
                  description: Price charged to the user for purchasing the subscription plan
                  format: float
                  examples:
                  - 20
                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".
                migration:
                  type: boolean
                  default: false
                  description: This key determines if a particular purchase call should be considered
                    as a fresh purchase or the migration of an existing subscription from the incumbent
                    system to the Punchh platform. A value of "true" indicates that this purchase is a
                    migration, and value of "false" indicates that this is a fresh purchase.
                lifetime_debits:
                  type: number
                  format: float
                  description: Total discounted units under this plan ID, issued in the incumbent system
                    before the guest migrated over to Punchh. This value should be sent only once at the
                    time of making the purchase call for migration. This is relevant only if the value
                    of the "migration" parameter is "true".
                  examples:
                  - 30
                lifetime_savings:
                  type: number
                  format: float
                  description: Total volume of savings under this plan ID, issued in the incumbent system
                    before the guest migrated over to Punchh. This value should be sent only once at the
                    time of making the purchase call for migration. This is relevant only if the value
                    of the "migration" parameter is "true".
                  examples:
                  - 50
                initial_debits:
                  type: number
                  format: float
                  description: Number of discounted units for the migrated subscription. Based on this
                    value, further discounting of units will be done in the Punchh system after the guest
                    migrates. This value should not be included in lifetime_debits and should be sent
                    only once at the time of making the purchase call for migration. This is relevant
                    only if the value of the "migration" parameter is "true".
                  examples:
                  - 10
                initial_savings:
                  type: number
                  format: float
                  description: 'Volume of savings for the migrated subscription. Further savings in the
                    Punchh platform will be added to this. This value should not be included in lifetime_savings
                    and should be sent only once at the time of making the purchase call for migration.
                    This is relevant only if the value of the "migration" parameter is "true". '
                  examples:
                  - 20
                source_subscription_id:
                  type: integer
                  description: This key should be sent if the purchase call is being made because a guest
                    decides to change the subscription plan. In all other cases, this key should be sent
                    as null.
                  format: int64
                  examples:
                  - 'null'
                location_id:
                  type: integer
                  x-stoplight:
                    id: pfyeucrbvxgv2
                  description: ID of the location where the subscription plan is purchased. It identifies
                    the origin of the subscription purchase for the loyalty guest. If an invalid or missing
                    location_id is passed, the API returns a 400 Bad Request error with the message "Invalid
                    or missing location_id".
              required:
              - user_id
              - start_time
              - plan_id
              - end_time
              - purchase_price
              - auto_renewal
              - location_id
            examples:
              Request:
                value:
                  user_id: 1234
                  start_time: '2021-05-18 11:34:46'
                  plan_id: 12
                  end_time: '2021-05-28 11:34:46'
                  purchase_price: 20
                  auto_renewal: false
                  migration: false
                  lifetime_debits: 30
                  lifetime_savings: 50
                  initial_debits: 10
                  initial_savings: 20
                  source_subscription_id: 'null'
                  location_id: 12345
        description: ''
  /api2/dashboard/subscriptions/renew:
    parameters: []
    post:
      summary: Renew Subscription
      operationId: post-api2-dashboard-subscription
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  example-1:
                    subscription_id: 40
                    start_time: '2021-04-20T21:09:38Z'
                    end_time: '2021-04-20T21:09:38Z'
                properties:
                  subscription_id:
                    type: integer
                    description: System-generated unique ID of the subscription that is issued for a guest
                    examples:
                    - 40
                  start_time:
                    type: string
                    minLength: 1
                    format: date-time
                    description: Date and time (in ISO 8601 format) from which the renewed subscription
                      will become active
                    examples:
                    - '2021-04-20T21:09:38Z'
                  end_time:
                    type: string
                    minLength: 1
                    format: date-time
                    description: Date and time (in ISO 8601 format) from until which the renewed subscription
                      will remain active
                    examples:
                    - '2021-04-20T21:09:38Z'
                  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: 40
                    start_time: '2021-04-20T21:09:38Z'
                    end_time: '2021-04-20T21:09:38Z'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    error: You need to sign in or sign up before continuing.
                properties:
                  error:
                    type: string
                    minLength: 1
                    examples:
                    - You need to sign in or sign up before continuing.
                required:
                - error
              examples:
                example:
                  value:
                    error: You need to sign in or sign up before continuing.
        '406':
          description: Not Acceptable
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    invalid: Subscription cannot be renewed.
                properties:
                  invalid:
                    type: string
                    minLength: 1
                    examples:
                    - Subscription cannot be renewed.
              examples:
                Invalid User Subscription:
                  value:
                    invalid_subscription: Invalid User Subscription.
                Subscription is not of auto renewal type:
                  value:
                    invalid_subscription: Subscription cannot be renewed.
        '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:
                Subscriptions is not enabled:
                  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:
                      base:
                      - Invalid Plan ID
                Plan not active:
                  value:
                    errors:
                      base:
                      - Plan is not active.
                Plan Expired:
                  value:
                    errors:
                      base:
                      - Plan has expired.
                Plan is not available for purchase:
                  value:
                    errors:
                      base:
                      - Plan is not available for purchase.
                Start time is blank:
                  value:
                    errors:
                      start_time:
                      - Start time can't be blank
                End Time is Blank:
                  value:
                    errors:
                      end_time:
                      - End time can't be blank
                Invalid Price:
                  value:
                    errors:
                      price:
                      - Price is not a number
      description: This API allows the business to renew subscriptions by making back-end calls on the
        designated date of renewal registered on the business end.
      parameters:
      - schema:
          type: string
          default: application/json
        in: header
        name: Content-Type
        description: application/json
        required: true
      - schema:
          type: string
          default: application/json
        in: header
        name: Accept
        description: application/json
        required: true
      - schema:
          type: string
        in: header
        name: Authorization
        description: Bearer token for admin authorization, who is making a call on behalf of the customer
        required: true
      x-stoplight:
        id: 69ba7735654cb
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              type: object
              x-examples:
                example-1:
                  subscription_id: '35'
                  start_time: '2021-04-20T21:09:38Z'
                  end_time: '2021-05-20T21:09:38Z'
                  purchase_price: '23.09'
              properties:
                subscription_id:
                  type: integer
                  description: Unique ID of the subscription plan that was issued to the guest and is
                    being renewed
                  examples:
                  - 38
                start_time:
                  type: string
                  minLength: 1
                  format: date-time
                  description: Date and time (in ISO 8601 format) from which the renewed subscription
                    will become active
                  examples:
                  - '2021-04-20T21:09:38Z'
                end_time:
                  type: string
                  minLength: 1
                  format: date-time
                  description: Date and time (in ISO 8601 format) until which the renewed subscription
                    will remain active
                  examples:
                  - '2021-04-20T21:09:38Z'
                purchase_price:
                  type: number
                  format: float
                  description: Cost of renewal of one unit of the subscription plan that is being renewed
                  examples:
                  - 23.98
                new_plan_id:
                  type: integer
                  description: This is sent only if the guest wants to switch to a different subscription
                    plan (e.g., changing from a monthly plan to a quarterly plan)
                  examples:
                  - 24
              required:
              - subscription_id
              - start_time
              - end_time
              - purchase_price
            examples:
              example:
                value:
                  subscription_id: 38
                  start_time: '2021-04-20T21:09:38Z'
                  end_time: '2021-04-20T21:09:38Z'
                  purchase_price: 23.98
  /api2/dashboard/subscriptions/cancel:
    patch:
      summary: Cancel Subscription (Turn off Auto Renewal)
      operationId: patch-api2-dashboard-subscriptions-cancel
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                minItems: 1
                uniqueItems: true
                x-examples:
                  example-1:
                  - Subscription auto renewal cancelled.
                description: Cancellation response from the server.
                items:
                  type: string
                  examples:
                  - Subscription auto renewal cancelled.
              examples:
                200 Ok:
                  value:
                  - Subscription auto renewal cancelled.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    error: You need to sign in or sign up before continuing.
                properties:
                  error:
                    type: string
                    minLength: 1
                    examples:
                    - You need to sign in or sign up before continuing.
                required:
                - error
              examples:
                example:
                  value:
                    error: You need to sign in or sign up before continuing.
        '406':
          description: Not Acceptable
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    invalid: Subscription cannot be renewed.
                properties:
                  invalid:
                    type: string
                    minLength: 1
                    examples:
                    - Subscription cannot be renewed.
              examples:
                Invalid User Subscription:
                  value:
                    invalid_subscription: Invalid User Subscription.
        '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:
                Subscriptions is not enabled:
                  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.
                Plan not active:
                  value:
                    errors:
                      base:
                      - Plan is not active.
      description: This API can be used to cancel an active subscripition.
      parameters:
      - schema:
          type: string
          default: application/json
        in: header
        name: Content-Type
        description: application/json
        required: true
      - schema:
          type: string
          default: application/json
        in: header
        name: Accept
        description: application/json
        required: true
      - schema:
          type: string
        in: header
        name: Authorization
        description: Bearer token for admin authorization, who is making a call on behalf of the customer
      x-stoplight:
        id: 2d76036913613
      requestBody:
        content:
          application/json:
            schema:
              type: object
              x-examples:
                example-1:
                  subscription_id: '126'
                  cancellation_reason: Do not like your service
                  cancellation_type: hard_cancelled
              properties:
                subscription_id:
                  type: integer
                  format: int64
                  description: Punchh-generated unique ID of the subscription that needs to be cancelled
                  examples:
                  - 123
                cancellation_reason:
                  type: string
                  minLength: 1
                  description: Reason provided by the admin at the time of cancellation
                  examples:
                  - Guest does not need service any more.
                cancellation_type:
                  type: string
                  minLength: 1
                  enum:
                  - hard_cancelled
                  - soft_cancelled
                  description: 'Type of cancellation -- either "hard_cancelled" or "soft_cancelled". If
                    “soft_cancelled”, end users can enjoy the benefits until the “end_time” of the subscription.
                    If “hard_cancelled”, subscription benefits are terminated immediately.  '
                  examples:
                  - hard_cancelled
              required:
              - subscription_id
              - cancellation_reason
              - cancellation_type
            examples:
              Example Request:
                value:
                  subscription_id: '126'
                  cancellation_reason: Do not like your service
                  cancellation_type: hard_cancelled
x-stoplight:
  id: 7e93bcfd755c7
openapi: 3.1.1
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
components:
  schemas: {}
  securitySchemes: {}
x-ext-urls: {}