openapi: 3.2.0 info: title: Online Ordering and SSO Rewards API version: '1.0' description: "The Punchh SSO API endpoints provide user-management functions such as login, registration, forgot password, and connect with Facebook for users on the Punchh loyalty platform. You can also fetch user-specific information such as rewards or point balances. \n\nThe Punchh Online Ordering API endpoints enable users to earn and redeem rewards for online orders." contact: name: Punchh Dev Support url: https://developers.punchh.com servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com tags: - name: Rewards paths: /api/auth/loyalty_points_estimator: get: responses: '200': description: '' content: application/json: schema: type: object properties: estimated_points: type: integer description: 'System-estimated loyalty points of the user based on the `subtotal_amount` provided in the request. This value depends on the points conversion rate, which can be configured in the Punchh platform. Contact your Punchh representative to update this configuration. ' examples: default: value: estimated_points: 46 summary: Estimate Loyalty Points Earning description: 'Returns a prediction of how many points can be earned before submitting the transaction. The estimate is derived from the base earning rate of the business and does not account for special promotions or campaigns. ' operationId: sso_estimate_loyalty_points_earning parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' tags: - Rewards x-stoplight: id: f588025c608a3 requestBody: content: application/json: schema: type: object properties: client: type: string description: Client key of the business default: CLIENT_GOES_HERE authentication_token: type: string default: AUTHENTICATION_TOKEN_GOES_HERE description: The authentication token of the user. 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). subtotal_amount: type: number format: float description: Order amount before any taxes (sum of all amounts minus any discounts). This is the amount upon which loyalty points/visits are granted. required: - client - subtotal_amount examples: default: value: client: CLIENT_GOES_HERE authentication_token: AUTHENTICATION_TOKEN_GOES_HERE subtotal_amount: 10 /api/auth/conversions: post: responses: '200': description: '' content: application/json: schema: type: array items: type: string examples: default: value: - 250 points converted into 2 summary: Convert Points description: Converts points to cash, fuel discounts, and charities based on the configuration or conversion rules set in the Punchh platform operationId: sso_points_conversion_api parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/content_type' tags: - Rewards x-stoplight: id: d23537781e07c requestBody: content: application/json: schema: type: object properties: client: type: string description: Client key of the business default: CLIENT_GOES_HERE authentication_token: type: string default: AUTHENTICATION_TOKEN_GOES_HERE conversion_rule_id: type: integer description: Conversion rule ID set for the Punchh platform configuration (returned for the converted_category_balances object as category_id) format: int32 source_value: type: integer format: int32 description: Number of points the user wants to convert to cash, fuel discounts, or charities converted_value: type: integer description: Values of the cash, fuel discounts, or charities converted from points format: int32 social_cause_campaign_id: type: string description: Campaign ID in case of points converted to charity required: - client - conversion_rule_id - source_value - converted_value examples: default: value: client: CLIENT_GOES_HERE authentication_token: AUTHENTICATION_TOKEN_GOES_HERE conversion_rule_id: 8 source_value: 100 converted_value: 10 social_cause_campaign_id: '12' /api/auth/estimate_points: get: responses: '200': description: '' content: application/json: schema: type: object properties: estimated_points: type: integer description: System-estimated loyalty points of the user based on the subtotal_amount provided in the request. This value depends on the points conversion rate, which can be configured in the Punchh platform. Contact your Punchh representative to update this configuration. examples: default: value: estimated_points: 200 summary: Estimate Points Earning description: Returns a prediction of how many points can be earned before submitting the transaction. The estimate is derived from the base earning rate of the business and does not account for special promotions or campaigns. operationId: sso_estimate_points_earning parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' tags: - Rewards x-stoplight: id: bce80fc26cf46 requestBody: content: application/json: schema: type: object properties: client: type: string description: Client key of the business default: CLIENT_GOES_HERE authentication_token: type: string default: AUTHENTICATION_TOKEN_GOES_HERE menu_items: $ref: '#/components/schemas/menu_items' subtotal_amount: type: number format: float description: Order amount before taxes (sum of all item amounts minus any discounts). Same as `receipt_amount`. For historical reasons, include this parameter along with `receipt_amount` in the API request. receipt_amount: type: number description: Order amount before taxes, calculated as the sum of all item amounts minus any discounts. This is the amount used to calculate loyalty points/visits. The value of this parameter should match `subtotal_amount`. For example, if the order amount is $10, both `receipt_amount` and `subtotal_amount` will be 10. If a $2 discount is applied, both will be 8. format: double required: - client - subtotal_amount - receipt_amount examples: default: value: client: CLIENT_GOES_HERE authentication_token: AUTHENTICATION_TOKEN_GOES_HERE menu_items: - item_name: White rice item_qty: 1 item_amount: 2 menu_item_type: M menu_item_id: '3419' menu_family: '800' menu_major_group: '152' serial_number: '1.0' - item_name: Brown rice item_qty: 1 item_amount: 8 menu_item_type: M menu_item_id: '3418' menu_family: '800' menu_major_group: '152' serial_number: '2.0' subtotal_amount: 10 receipt_amount: 10 /api/auth/ordering_meta: get: responses: '200': description: '' content: application/json: schema: type: object properties: base_redeemable_name: type: string description: Name of the base reedemable base_redeemable_description: type: string description: Description of the base reedemable base_redeemable_image: type: string description: Image of the base reedemable base_redeemable_properties: type: - string - 'null' description: Properties of the base reedemable examples: default: value: base_redeemable_name: 'Punch Card = FREE Adult Buffet or Carryout 1-Topping Pizza ' base_redeemable_description: 'You just earned yourself an awesome reward! Now, you get to choose a FREE Adult Buffet or your favorite Carryout 1-Topping Pizza. Either way, you win. *To redeem, use your Punch Card Reward when ordering online or through the MyAcme App.' base_redeemable_image: IMAGE_URL_GOES_HERE base_redeemable_properties: null '400': description: Sending invalid credentials '412': description: Sending invalid Signature summary: Ordering Meta description: Retrieves information about the base redeemable operationId: sso_ordering_meta parameters: - $ref: '#/components/parameters/Signature' - schema: type: string default: base_redeemable in: query name: filter required: true description: Send "base_redeemable" to get metadata about the redeemable - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Accept' tags: - Rewards x-stoplight: id: 7108126712419 requestBody: content: application/json: schema: type: object properties: client: type: string description: Client key of the business default: CLIENT_GOES_HERE authentication_token: type: string x-stoplight: id: h11lxep7b4xy6 description: The authentication token of the user. You can retrieve this from the response of a successful sign-in API call or through the [SSO process](https://developers.partech.com/docs/dev-portal-online-ordering/9a41534336c87-sso-flow-for-web-and-mobile). required: - client examples: default: value: client: CLIENT_GOES_HERE /api/auth/offers: get: responses: '200': description: '' content: application/json: schema: type: object properties: pinned_message: type: string description: Message attached with available offers rewards: $ref: '#/components/schemas/Rewards-Attribute' notifications: $ref: '#/components/schemas/Notifications' redeemables: $ref: '#/components/schemas/Redeemables-Attributes' examples: default: value: pinned_message: '' rewards: - code: '531611' id: 1014491 business_id: 470 redeemable_id: 105 start_date: '2015-06-16' end_date: '2015-07-15' read_at: null start_date_tz: '2015-06-15T18:30:00Z' end_date_tz: '2015-07-15T18:29:59Z' gaming_level_id: null gifted_for_type: Admin gift_reason: Admin Generosity location_ids: - 303133 - 303134 external_store_numbers: - '3613' - '3614' notifications: - id: 8415352 message: notification message user_id: 111111111 token: null sent_at: '2015-05-28T17:03:27Z' kind: campaign network: null status: sent deleted_at: null created_at: '2015-05-28T17:03:26Z' updated_at: '2015-05-28T17:03:27Z' read_at: null business_name: BUSINESS_NAME_GOES_HERE sent_at_tz: '2015-05-28T11:03:27-06:00' redeemables: - description: Free Soft Drink (600 ml) when you purchase a Pizza!! discount_amount: 700 id: 105 image: /images/punchh-icon-small.png name: Free Soft Drink Offer! points: 0 redeemable_id: 105 thumb_image: /images/punchh-icon-thumb.png applicable_as_loyalty_redemption: null '412': description: Sending invalid Signature '422': description: Sending invalid Entity summary: Fetch Available Offers description: Fetches available offers or offer details of a user. This request returns how many offers are available to the user. operationId: sso_auth_fetchavailableoffers parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' tags: - Rewards x-stoplight: id: ba92ee7891a30 requestBody: content: application/json: schema: type: object properties: authentication_token: type: string description: The authentication token of the user. 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). client: type: string description: Client key of the business required: - client examples: default: value: authentication_token: AUTHENTICATION_TOKEN_GOES_HERE client: CLIENT_GOES_HERE components: schemas: Redeemables-Attributes: type: array items: type: object properties: applicable_as_loyalty_redemption: type: boolean description: Applicable on loyalty redeemable_properties: type: string description: Comma-separated values that provide additional details about a redeemable. For example, a redeemable could be "Food Item" or "Merchandise", etc. These 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. discount_amount: type: integer description: Amount of discount on the reward discount_channel: type: string description: 'Can accept any one of the following values: - all - discountable everywhere - online_only - online orders only - offline_only - in store only' expire_redemption_code_with_reward_end_date: type: - boolean - 'null' description: Whether the redemption code expires with the expiry of the reward id: type: integer description: Identification of the reward image: type: string description: Image of the redeemable item points: type: integer description: Total number of points required for redemption redeemable_id: type: integer description: Identification of the redeemable item redemption_expiry: type: integer description: Expiry of the redemption, in minutes thumb_image: type: string description: Thumbnail image of the redeemable item name: type: string description: Name of the redeemable item description: type: string description: Description of the redeemable item title: Redeemables Attributes (Object) x-stoplight: id: 173597e963ebd menu_items: type: array items: type: object properties: item_name: type: string description: 'Name of the menu item ' item_qty: type: integer description: Quantity ordered by the customer. If the item is a modifier (such as extra cheese on a pizza base item), make sure the quantity reflects the total number of base items included. For example, if you have a pizza base item with a certain item ID and a quantity of two, and the pizzas each have an extra cheese modifier added to them, then the modifier quantity should be two to account for the modifier across both pizzas. This applies only to base items of the same ID. If different base items include the same modifier, you do not need to sum the modifiers. item_amount: type: number description: 'The total price of the line item or the amount of the discount that you applied to an item. In case of multiple quantities, this means the sum total of all item amounts. Always represent this value as a positive number, even when the item is a discount. ' menu_item_type: type: string description: "The classification of the item. Choose from the following types based on the item:\n\nM - Menu item ( + or - ) \n\nD - Discount (negative). Either internal or Punchh will always evaluate lines as ( - ) regardless of the sign assigned in the API call\n\nS - Service item. Any item representing money received that is not a sale. For example, service charges, delivery fees, tips, purchase of gift cards/certificates, etc. \n\nT - Tax item. Taxes of all sorts \n\nP - Payment item. Visa, MasterCard, cash, gift card/certificate (when used to pay for the order)" menu_item_id: type: string description: Unique identifier for the item menu_family: type: string description: The family that the item belongs to. The family is the subcategory for the item. Even though the parameter is required, you can pass it in the request with a blank value. You can leave this blank if the item does not belong to a family. menu_major_group: type: string description: 'The major group that the item belongs to. The major group is the parent category for the item. Even though the parameter is required, you can pass it in the request with a blank value. You can leave this blank if the item does not belong to a major group. ' serial_number: type: string description: A serialized number that differentiates distinct menu items on a receipt. The purpose of this field is to identify which items on the receipt are base items and which items are modifiers to the base items. For example, a main menu item (such as pizza) may have serial number "1.0", and the associated modifiers (such as "extra cheese", "olives", and "jalapenos") may have serial numbers "1.1", "1.2", and "1.3" respectively. Serialization is limited to one decimal point, so you can only modify the base item. You cannot modify a modifier with 1.x.x, and so on. required: - item_name - item_qty - item_amount - menu_item_type - menu_item_id - menu_family - menu_major_group - serial_number title: Menu Items (Object) x-stoplight: id: e8647930d00a4 Notifications: type: array description: Returns the details of the notifications received by a user. A maximum of 10 notifications will be fetched. items: type: object properties: id: type: integer description: ID of the notification kind: type: string description: 'Type of notification. There are three types of notifications that a user can receive: ''system'', ''campaign'', and ''news''.' message: type: string description: Message sent to the user in the notification read_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time x-nullable: true created_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time title: Notifications (Object) x-stoplight: id: ba4734ac30a93 Rewards-Attribute: type: array items: type: object properties: business_id: type: integer description: Identification of the business end_date: type: string description: Date after which the reward will not be allowed on redemption, in YYYY-MM-DD format enum: - YYYY-MM-DD format: date end_date_tz: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Timestamp with time zone gaming_level_id: type: string description: Gaming level that the user has reached gifted_for_type: type: string description: 'The reward can be gifted for the following types: - Admin reward - Offered by the administrator to a user - Campaign - Offered to a user under a campaign triggered by a business - Checkin - When a user makes a check-in - FeedbackReply - Feedback provided by a user - MassGifting - If a user is among the population of users that received rewards - Referral - Referral of one user by another user - ScratchPlay - Mobile game' gift_reason: type: string description: Reward given for activity performed by a user id: type: integer description: ID of reward format: int64 location_ids: type: array description: Location IDs are interchangeable with external store numbers. items: type: integer read_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Time when the user acknowledged the reward redeemable_id: type: integer description: ID of the redeemable item reward_properties: description: Properties of the reward x-nullable: true start_date: type: string enum: - YYYY-MM-DD format: date description: Date from which the reward is applicable, in YYYY-MM-DD format start_date_tz: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Tmestamp with time zone external_store_numbers: type: array description: External store numbers are interchangeable with location IDs. items: type: integer type: type: string description: This will be either redeemable or reward. The Create Online Redemption API request depends on what is returned in this field. title: Rewards Attributes (Object) x-stoplight: id: b56f79b98e3cd parameters: User-Agent: schema: type: string default: Punchh/OnlineOrder/1.0/Web/BrowserVersion/OS_Type name: User-Agent in: header required: true description: For details, see [User Agent](/docs/dev-portal-online-ordering/additional-topics/user-agent). content_type: schema: type: string default: application/json in: header name: Content-Type description: Set this header to **application/json**. required: true Signature: schema: type: string default: SIGNATURE_GOES_HERE in: header name: x-pch-digest description: The [signature](/docs/dev-portal-online-ordering/additional-topics/x-pch-digest-sha-1) for the API call required: true Accept: schema: type: string default: application/json in: header name: Accept description: Advertises which content types the client is able to understand required: true Authorization: schema: type: string default: Bearer ACCESS_TOKEN_GOES_HERE name: Authorization in: header required: true description: You may pass the access_token instead of the authentication_token in Online Ordering endpoints to authorize the request. It must be supplied as `Bearer ACCESS_TOKEN_GOES_HERE`. x-stoplight: id: 73bbc35439926 x-ext-urls: {}