post-api2-dashboard-subscriptions-purchase

Purchase Subscription

​

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.

Headers
  • Content-Type
    Type: string
    required

    application/json

  • Accept
    Type: string
    required

    application/json

  • Authorization
    Type: string
    required

    Bearer token for admin authorization, who is making a call on behalf of the customer

Body
application/json
  • auto_renewal
    Type: boolean
    default: 
    false
    required

    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".

  • end_time
    Type: string
    min length:  
    1    Format: date-time
    required

    Date and time (in ISO 8601 format) until which the subscription being issued will remain active

  • initial_debits
    Type: numberFormat: float

    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".

  • initial_savings
    Type: numberFormat: float

    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".

  • lifetime_debits
    Type: numberFormat: float

    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".

  • lifetime_savings
    Type: numberFormat: float

    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".

  • location_id
    Type: integer
    required

    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".

  • migration
    Type: boolean
    default: 
    false

    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.

  • plan_id
    Type: integerFormat: int64
    required

    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.

  • purchase_price
    Type: numberFormat: float
    required

    Price charged to the user for purchasing the subscription plan

  • source_subscription_id
    Type: integerFormat: int64

    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.

  • start_time
    Type: string
    min length:  
    1    Format: date-time
    required

    Date and time (in ISO 8601 format) from which the subscription being issued will become active

Responses
  • 201
    Type: object
    • end_time
      Type: string
      min length:  
      1      Format: date-time
      required

      Date and time (in ISO 8601 format) until the subscription plan purchased for the guest will remain active

    • external_plan_identifier
      Type: string

      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

      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".

    • start_time
      Type: string
      min length:  
      1      Format: date-time
      required

      Date and time (in ISO 8601 format) from which the subscription plan purchased for the guest will become active

    • subscription_id
      Type: integerFormat: int64
      required

      System-generated unique ID of the subscription that is issued for a guest

  • 400
    Type: object
    • error
      Type: string
  • 401
    Type: object
    • error
      Type: string
      min length:  
      1
      required
  • 406
    Type: object
    • invalid
      Type: string
      min length:  
      1
  • 422
    Type: object
    • errors
      Type: object
post/api2/dashboard/subscriptions/purchase
{
  "subscription_id": 123,
  "start_time": "2021-05-18 11:34:46",
  "end_time": "2021-05-28 11:34:46",
  "external_plan_identifier": "string",
  "location_id": 1
}

Created