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
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:
1Format: date-time
required

Date and time (in ISO 8601 format) until which the subscription being issued will remain active
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".
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
start_time
Type: string
min length:
1Format: date-time
required

Date and time (in ISO 8601 format) from which the subscription being issued will become active
user_id
Type: integerFormat: int64
required

System-generated unique ID of a guest created on the Punchh platform
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".
migration
Type: boolean

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.

Responses

application/json
application/json
application/json
application/json
application/json

post/api2/dashboard/subscriptions/purchase

curl https://SERVER_NAME_GOES_HERE.punchh.com/api2/dashboard/subscriptions/purchase \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Accept: ' \
  --header 'Authorization: ' \
  --data '{
  "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
}'

Show Schema

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