x-stoplight:
id: 7d3d29e919e4b
info:
title: POS API
version: '1.0'
contact:
name: Punchh Dev Support
url: https://developers.punchh.com
description: Punchh provides robust APIs for integrating POS (Point-of-Sale) terminals with its back
end. The integration helps businesses to offer their customers loyalty programs directly from their
POS systems.
paths:
/api/pos/locations/configuration:
get:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
banked_rewards_mode:
type: boolean
description: 'Set to 1 if program type of business is banked rewards. If this is 1,
visits_mode and points_unlock_mode will be 0. <b>Note</b>: This parameter, along
with `visits_mode` and `points_unlock_mode` parameters, is included in the response
if the option to display the loyalty program structure in the POS API response is
enabled in the Punchh platform for the business. Contact your Punchh representative
to update this configuration setting.'
business_name:
type: string
description: Business ID and business name.
header:
type: string
description: Header message of location on receipt.
location_id:
type: integer
description: Punchh's internal location ID.
location_name:
type: string
description: Location ID and location name.
log_level:
type: integer
description: 'Log level (0-6) of the location:
0 - None - no logs generated
1 - System - system level logs
2 - Error - any error from API or system errors
3 - Warning - app level or system level warning
4 - Information - app level logs
5 - Request - logs for all request data
6 - Response - logs for all request and response details'
points_unlock_mode:
type: boolean
description: 'Set to 1 if program type of business is points unlock redeemables. If
this is 1, banked_rewards_mode and visits_mode will be 0. <b>Note</b>: This parameter,
along with `visits_mode` and `banked_rewards_mode` parameters, is included in the
response if the option to display the loyalty program structure in the POS API response
is enabled in the Punchh platform for the business. Contact your Punchh representative
to update this configuration setting.'
print_barcodes:
type: boolean
description: Set '1' to print the generated barcode on receipt; else '0'.
send_to_datasink:
type: boolean
description: Send receipt details to Datasink API if set to 1 once receipt is closed.
short_key:
type: integer
description: Short location access key, by which location can be accessible
trailer_1:
type: string
description: Line 1 of receipt message
trailer_2:
type: string
description: Line 2 of receipt message
trailer_3:
type: string
description: Line 3 of receipt message
trailer_4:
type: string
description: Line 4 of receipt message
trailer_5:
type: string
description: Line 5 of receipt message
update_interval:
type: integer
description: The time polling interval between the POS and Punchh is known as the
update_interval (minutes).
visits_mode:
type: boolean
description: 'Set to 1 if program type of business is visit-based. If this is 1, banked_rewards_mode
and points_unlock_mode will be 0. <b>Note</b>: This parameter, along with `banked_rewards_mode`
and `points_unlock_mode` parameters, is included in the response if the option to
display the loyalty program structure in the POS API response is enabled in the
Punchh platform for the business. Contact your Punchh representative to update this
configuration setting.'
multiple_redemption_on_location:
type: boolean
x-stoplight:
id: uvxd2oc1qw9uu
description: Indicates whether the multiple redemptions feature is enabled for a particular
location. You can access this setting for a location on the Punchh platform under
Store Locations > All Store Locations > [choose location] > Location > Allow Location
for Multiple Redemption.
examples:
default:
value:
banked_rewards_mode: '1'
business_name: BUSINESS_NAME_GOES_HERE
header: Header Punchh
location_id: '327922'
location_name: 327922-punchh-demo
log_level: '6'
points_unlock_mode: '0'
print_barcodes: '1'
send_to_datasink: '1'
short_key: '6624'
trailer_1: 'Barcode Punchh Line #1'
trailer_2: 'Barcode Punchh Line #2'
trailer_3: 'Barcode Punchh Line #3'
trailer_4: 'Barcode Punchh Line #4'
trailer_5: THANKS Punchh
update_interval: '60'
visits_mode: '0'
multiple_redemption_on_location: true
summary: Location Configuration
description: "Get the configuration for a location using a unique API key (i.e., location key).\n\
\nThis API call requires the API key as well as the business key to be sent in the HTTP Authorization\
\ header in the following format:\n\nAuthorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE\n\
\nwhere \n\nLOCATION_KEY_GOES_HERE is the API key (which is unique for a location) and BUSINESS_KEY_GOES_HERE\
\ is the business key (which is unique for a business). \n\nSee cURL examples for more details.\n"
operationId: pos_location_config
tags:
- Point Of Sale
parameters:
- schema:
type: string
default: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE
in: header
name: Authorization
required: true
description: This is a combination of unique API key as well as business key (UUID) as the Authorization
header.
- schema:
type: string
default: en
in: header
name: Accept-Language
description: Short code for locale variant (e.g., fr-ca, es-ES, en-EN, etc.)
x-stoplight:
id: 319b73fb3a8de
/api/pos/meta:
get:
responses:
'200':
description: 'Automated approach based on different programs: A partner could use different
values and also programmatically identify to display them accordingly via the Program Meta
API.
1. For program_type as “visits”, in order to fetch the count for available unredeemed cards,
use the “unredeemed_cards” field. In this case, net_balance will show the available visits
balance earned for a user.
2. For program_type as “points” -- “points_conversion_type”: “currency” -- in order to fetch
the value for dollar amount available in the user’s account, use the “banked_rewards” field.
In this case, net_balance will also show banked reward currency available, but if you want
to display current points available, use points_balance. This gets reset once it reaches the
threshold value (returned in meta API under “points_conversion_threshold”) where those points
are converted to fixed banked reward value as configured in the platform. For example, if
as per business setup every 100 points earned get converted to $10 and the user currently
has 40 points, then the points_balance value will be 40 until the user earns 60 more points
where they will get converted to $10. Once the user earns 60 more points, the points_balance
reaches 100 where it will get converted to $10 and the points_balance value will become 0.
3. For program_type as “points_unlock_redeemables” -- “points_conversion_type”: “staged” or
“points_conversion_type”: “none” -- in this case, in order to fetch the current balance, you
can use the net_balance value from the balance object which will get updated after every check-in
or redemption. The points_balance value will also update based on earnings but will reset
once it reaches the threshold value. Here, we do not recommend the point_balance value to
be displayed as there is no conversion into currency or reward.
4. For program_type as "points" -- “points_conversion_type”: “rewards” -- in this case, the
points_balance will show current points which will get reset once it reaches the threshold
value (returned in meta API under “points_conversion_threshold”) where points are converted
to a reward. Also, net_balance will display total available points of the user. For example,
if as per business setup every 100 points earned get converted to a reward and the user currently
has 40 points, then the points_balance value will be 40 until the user earns 60 more points
where they will get converted to a reward. Once the user earns 60 more points, the points_balance
reaches 100 where it will get converted to a reward and the points_balance value will become
0.'
content:
application/json:
schema:
type: object
properties:
minimum_payable_price:
type: number
description: Minimum price per unit (e.g., gallon) that needs to be paid for fuel
at the time of fuel discount redemption as configured in the platform.
format: float
maximum_discountable_quantity:
type: number
description: Maximum fuel volume on which a discount can be applied at the time of
fuel discount redemption.
format: float
program_type:
type: string
description: Provides information about the program type configured for the business
in the Punchh platform.
points_conversion_type:
type: string
description: 'Provides information about the conversion type configured for the business
in the Punchh platform: “staged”, “currency”, “rewards”, “no conversion”.'
visits_per_card:
type: integer
description: Number of visits that are required for a single card completion.
card_redemption_value:
type: number
description: The value an end-user gets after a complete card is redeemed by the user.
format: float
minimum_visit_amount:
type: number
description: Minimum amount in selected currency that is required for a visit/check-in
to be counted.
format: float
minimum_visit_hours:
type: integer
description: Minimum duration between two consecutive visits of an end-user so that
both visits are counted separately.
minimum_age_to_signup:
type: integer
description: Minimum age at which an end-user is allowed to sign up.
earning_unit:
type: string
description: The value an end-user earns as the result of a check-in and as configured
in the platform.
currency_earned:
type: number
description: Value of points/visits earned as the result of a check-in as configured
in the platform.
format: float
points_conversion_threshold:
type: integer
description: The threshold value at which an end-user's accumulated points get converted
to rewards as configured in the platform.
redemption_expiry_minutes:
type: integer
description: The duration after which a redemption code generated by an end-user expires.
pending_points:
type: boolean
description: Values can be true or false based on the Punchh platform configuration.
For example, if no pending check-in is selected, then its value should be 0 or false.
Contact your Punchh representative for more information about this Punchh platform
configuration setting.
pending_points_duration:
type: integer
description: Pending points value configured in minutes as “Receipt update delay minutes”
if pending point strategy is “Automatic after a configured time delay”.
configurable_default_time_eod:
type: string
description: All of the pending checks will be settled at this time or after the configured
"Receipt update delay minutes”, whichever is earlier.
enum:
- In HH:MM:SS
format: time
autocreate_user_phone:
type: boolean
description: This determines whether user creation should be allowed via phone number
through POS or not. The values can be true or false depending on the platform configuration.
coupon_prefix:
type: string
description: This field is used to provide the coupon prefix as configured in the
Punchh platform.
redeemables:
type: array
description: Returns the redeemables object. Refer to the redeemables object documentation
for details.
items:
type: object
properties:
redeemable_image_url:
type: string
description: URL of the image displayed in the app to depict the redeemable.
redeemable_properties:
type: string
description: Properties such as "Merchandise", "Food Item", etc. can be added
to a particular redeemable.
redeemable_id:
type: integer
description: Unique ID to identify a redeemable in the system.
name:
type: string
description: Name of the redeemable.
description:
type: string
description: Description of the redeemable that appears in the app. It should
lure the end-users in to redeeming.
points_required_to_redeem:
type: integer
description: Value of points required to redeem a particular redeemable.
meta_data:
type: string
description: Meta data that can be added to a redeemable. This can be used to
program mobile apps to have certain behavior when specific data are received
from the server, OR it can be used as the business wishes. This can be configured
from the Punchh platform and has a maximum length of 255 characters.
multiple_redemptions_enabled:
type: boolean
x-stoplight:
id: tau684ctggtyg
description: Indicates whether the multiple redemptions feature is enabled for the
business. If set to true, the API returns the `multiple_redemptions` object in the
response.
multiple_redemptions:
$ref: '#/components/schemas/multiple-redemptions'
examples:
200 OK:
value:
minimum_payable_price: null
maximum_discountable_quantity: null
program_type: points_unlock_redeemables
points_conversion_type: staged
visits_per_card: 5
card_redemption_value: 2
minimum_visit_amount: 5
minimum_visit_hours: 4
minimum_age_to_signup: 0
earning_unit: point
currency_earned: 0
points_conversion_threshold: 50
redemption_expiry_minutes: 24
pending_points: true
pending_points_duration: 15
configurable_default_time_eod: '23:59:59'
autocreate_user_phone: true
coupon_prefix: ''
redeemables:
- redeemable_image_url: IMAGE_URL_GOES_HERE
redeemable_properties: null
meta_data: Meta data
redeemable_id: REDEEMABLE_ID_GOES_HERE
name: 'Test Redeemable #2'
description: Test redeemable description
points_required_to_redeem: 20
- redeemable_image_url: IMAGE_URL_GOES_HERE
redeemable_properties: null
redeemable_id: REDEEMABLE_ID_GOES_HERE
name: Chips & Salsa
description: Chips & Salsa redeemable. only be used in the redemption of Chips &
Salsa
points_required_to_redeem: 35
- redeemable_image_url: IMAGE_URL_GOES_HERE
redeemable_properties: null
meta_data: deal 1
redeemable_id: REDEEMABLE_ID_GOES_HERE
name: 50% off
description: Test Description
points_required_to_redeem: 200
- redeemable_image_url: IMAGE_URL_GOES_HERE
redeemable_properties: null
redeemable_id: REDEEMABLE_ID_GOES_HERE
name: Test Redeemable
description: Redeemable to test redemption!
points_required_to_redeem: 1500
multiple_redemptions:
exclude_interoperability_strategy_between:
- offer|loyalty
- loyalty|pre_purchased
- promo_coupon|offer
- pre_purchased|promo_coupon
auto_unlock_duration: 100
discount_processing_strategy: date_of_expiry
processing_priority_by_discount_type:
- reward
allow_multiple_redemption_on_item: true
allow_qualifying_items_reused: true
auto_redemption: true
auto_redemption_discounts:
- offer
- subscription
enable_auto_unlock: true
enable_discount_locking: true
max_redemptions_in_transaction: 20
processing_priority_by_acquisition_type:
- code: offer
priority: 1
multiplication_factor: 20
- code: loyalty
priority: 2
multiplication_factor: 10
- code: promo_coupon
priority: 3
multiplication_factor: 5
- code: pre_purchased
priority: 4
multiplication_factor: 4
multiple_redemptions_enabled: true
summary: Program Meta
operationId: pos_program_meta
tags:
- Point Of Sale
parameters:
- schema:
type: string
default: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE
in: header
name: Authorization
description: This is a combination of unique API key as well as business key (UUID) as the Authorization
header.
required: true
- schema:
type: string
default: en
in: header
name: Accept-Language
description: Short code for locale variant (e.g., fr-ca, es-ES, en-EN, etc.)
description: 'Get information about business-level data, such as program type, platform configurations,
list of redeemables (in case of points unlock redeemable program), etc.
>Any update made to the configuration in the platform will be reflected in the response after
15 minutes, instead of in real time, in order to improve the response time.
'
x-stoplight:
id: c6b60d909fe82
/api/pos/users:
post:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
address_line1:
type: string
description: Address of the user
age_verified:
type: boolean
description: Is the age of the user verified or not
anniversary:
type: string
enum:
- YYYY-MM-DD
format: date
description: Anniversary of the user in YYYY-MM-DD format
avatar_remote_url:
type: string
description: Avatar URL of the user profile image
balance:
type: object
title: Balance
description: Balance Object
properties:
banked_rewards:
type: string
description: Banked rewards of the user account. This value is set only if the
program type is banked rewards based; else it will be 0.
expired_membership_level:
type: string
description: Expired membership level
x-nullable: true
initial_visits:
type: integer
description: Captures all of the visits that the guest made up to the time of
migration
membership_level:
type: string
description: Membership level of the user
x-nullable: true
membership_level_id:
type: string
description: Membership level ID of the user
x-nullable: true
net_balance:
type: number
description: Net available balance of the current account. This value always shows
the available balance of the user, whether visits, banked rewards, or points.
net_debits:
type: number
description: Net debits of the user
pending_points:
type: integer
description: Pending points of the user
points_balance:
type: integer
description: 'Returns the points balance of the user account. This value gets
reset based on the point conversion value once reached, as configured in the
Punchh platform.
Note: It will increase only as per points earned, and it resets once the threshold
value is reached to convert points into currency or reward.'
signup_anniversary_day:
type: string
description: Sign-up anniversary day of the current account
total_credits:
type: number
format: double
description: Total credits of the current account
total_debits:
type: string
description: Total debits of the current account
total_point_credits:
type: integer
description: Total points credits of the user
total_redeemable_visits:
type: integer
description: Total redeemable visits of the user
total_visits:
type: integer
description: Total number of loyalty visits
unredeemed_cards:
type: integer
description: Number of unredeemed cards of a user. This value is set only if the
program type is visit-based; else it will be 0.
birthday:
type: string
description: Birthday date of the user in YYYY-MM-DD format
city:
type: string
description: City in which the user lives
created_at:
type: string
description: Date/time when the user was created in the system in ISO 8601 format
discount_type:
type: string
description: Discount type. e.g., 'card_completion' || 'reward' || 'discount_amount'
|| 'redemption_code'
email:
type: string
description: Email address of the user
email_verified:
type: boolean
description: Is the email address of the user verified or not
fb_uid:
type: string
description: Unique Facebook ID of the user
first_name:
type: string
description: First name of the user
gender:
type: string
description: Gender of the user
id:
type: integer
description: Unique ID of the user
last_name:
type: string
description: Last name of the user
phone:
type: string
description: Phone number of the user
privacy_policy:
type: boolean
description: Has the user agreed to the privacy policy or not
rewards:
type: object
title: Rewards Object
properties:
rewards:
type: array
items:
type: object
properties:
created_at:
type: string
description: Date/time when the reward was created (in ISO 8601 format)
description:
type: string
description: Description that explains rewards as configured in the Punchh
platform
discount_amount:
type: integer
description: Discount amount associated with the current reward
end_date_tz:
type: string
description: Expiry date of the reward in ISO 8601 format
id:
type: integer
description: Reward ID
format: int64
image:
type: string
description: Image URL of the reward
name:
type: string
description: Name of the reward
points:
type: integer
description: Points associated with the current reward
redeemable_properties:
type: string
description: Comma-separated values that provide additional details about
a redeemable. For example, a redeemable could be a "Food_Item" or "Merchandise",
etc. Can be configured for a business in the Punchh platform and attached
to a redeemable. If no value is attached to a redeemable, a blank field
will be returned.
start_date_tz:
type: string
description: Start date of the reward in ISO 8601 format
status:
type: string
description: The redemption status of a reward. Currently only the value
"Unredeemed" will be returned. This signifies that the reward has not
been redeemed by an end-user.
updated_at:
type: string
description: Date/time when the reward was updated (in ISO 8601 format)
type:
type: string
description: 'This will be either redeemable or reward. Possible Redemptions
and Create Redemption API requests depend on what is returned in this
field.
In cases where this field is not returned, assume that the type is reward.'
meta_data:
type: string
description: Meta data that can be added to a redeemable. This
# --- truncated at 32 KB (221 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/punchh/refs/heads/main/openapi/punchh-pos-api-openapi.yml