openapi: 3.2.0 info: title: Punchh Auth API contact: name: Punchh Dev Support url: https://developers.punchh.com version: '1.0' description: 'Operations tagged Auth across 3 of this provider''s published API definitions: punchh-online-ordering-redemptions-legacy-openapi.yml, punchh-online-ordering-redemptions-v2-openapi.yml, punchh-online-ordering-subscription-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com tags: - name: Auth paths: /api/auth/redemptions/online_order: post: responses: '200': description: '' content: application/json: schema: type: object properties: status: type: string description: Message that explains if the customer's redemption was successfully completed or not redemption_amount: type: integer description: Total redemption amount that can be applied on the order category: type: string description: 'Category returned for redemption requested where values can be: `redeemable`, `processed`, `expired`, `invalid`, `unassigned`. Consider redemption valid only when the category is returned as `redeemable`.' qualified_menu_items: $ref: '#/components/schemas/Menu-items' discount_distribution_items: $ref: '#/components/schemas/discount_distribution_items' redemption_id: type: integer format: int64 description: Unique ID associated with the redemption. Save this in your system for future reference. redemption_code: type: string description: Redemption code associated with redemption max_applicable_quantity: type: number description: 'Maximum quantity that can be discounted. Note: This parameter will be returned for offers related to Price Rollback.' campaign_name: type: string x-stoplight: id: 7s3sui5p01net description: Name of the campaign through which the guest received the offer qualifying_conditions: type: object x-stoplight: id: ox2f9fs82bs54 description: The object lists all qualification criteria (both receipt-level and line-item) for submitted offers that failed while processing the redemption. This object is returned in the response only if the option to return the qualifying conditions for Redemption 1.0 APIs is enabled for the business in the Punchh platform. See the `data` object under [Get Qualification Criteria Response](https://developers.partech.com/docs/dev-portal-platform-functions/97ec083d6cf57-get-qualification-criteria-qc-list#response-body) in Platform Functions for descriptions of the parameters in `qualifying_conditions`. examples: default: value: status: Redeemed at Feb 26, 2026 10:49 by FIRST_NAME_GOES_HERE LAST_NAME_GOES_HERE at Naperville. Please HONOR it. redemption_amount: 8 category: redeemable qualified_menu_items: - item_name: Sandwich item_qty: 1 item_amount: 5 menu_item_type: M menu_item_id: '102000' menu_family: Sandwich menu_major_group: Sandwich serial_number: '1.0' - item_name: Coke item_qty: 1 item_amount: 7 menu_item_type: M menu_item_id: '102000' menu_family: Coke menu_major_group: Coke serial_number: '2.0' discount_distribution_items: - item_name: Sandwich DISCOUNT item_qty: 1 item_amount: -3 menu_item_type: R menu_item_id: '102000' menu_family: Sandwich menu_major_group: Sandwich serial_number: 1 - item_name: Coke DISCOUNT item_qty: 1 item_amount: -5 menu_item_type: R menu_item_id: '102000' menu_family: Coke menu_major_group: Coke serial_number: 2 max_applicable_quantity: 1 campaign_name: Mass Campaign Offer redemption_id: 21762 redemption_code: REDEMPTION_CODE_GOES_HERE '401': description: Sending invalid credentials '412': description: Sending invalid Signature '422': description: '' content: application/json: examples: default: value: - Given reward is not accessible for this guest description: "Redeems a card, reward, redeemable, or discount specified in the `discount_type` parameter against a receipt.\n\nPunchh evaluates eligibility during the Possible Redemptions call using the receipt details provided (item name, price, quantity, identifiers, etc.). During the Create Online Redemption API call, Punchh revalidates the same receipt to ensure the qualifying conditions are still met before honoring the redemption. \n\nIf any item attributes change between the two calls, Punchh may be unable to match the qualifying items, which can cause the Create Online Redemption API call to fail or return a different result—even if the Possible Redemptions call was successful.\n\n**NOTE**: **When processing a redemption, DO NOT include the `query` parameter in the API request.** Use this parameter only to check for possible redemptions. " summary: Create Online Redemption (Redemptions 1.0) operationId: sso_create_online_redemption parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/User-Agent' x-stoplight: id: 60069336e34d4 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). query: type: boolean description: Include this parameter only if you want to make a possible redemptions call. The parameter value must be true. If you want to process a redemption, do not include this parameter in the request. cc_last4: type: string description: Last 4 digits of credit card number employee_id: type: string description: Employee ID employee_name: type: string description: Employee name store_number: type: string description: The location where the redemption must be redeemed menu_items: $ref: '#/components/schemas/menu_items' receipt_amount: type: number format: double 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. subtotal_amount: type: number format: double 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_datetime: type: string description: Timestamp of receipt as per ISO 8601, in YYYY-MM-DDThh:mm:ssZ format transaction_no: type: string description: Receipt number or transaction number on the receipt external_uid: type: string description: 'Unique ID generated by your system. We use this to prevent duplicates in case the same transaction gets triggered twice. ' client: type: string description: Client key of the business channel: type: string enum: - pos - web - online_order - mobile - dashboard - chatbot - kiosk description: 'Channel through which the redemption was requested. Possible values are: online_order, pos, web, mobile, dashboard, chatbot, and kiosk. ' state: type: string description: 'The current state of the check-in. Possible values are: committed, pending, or void' discount_type: type: string enum: - reward - card_completion - redeemable - discount_amount - redemption_code - subscription description: 'Any one of these values: card_completion || reward || redeemable || discount_amount || redemption_code || subscription. For details, see [Getting Started With Online Ordering APIs](/docs/dev-portal-online-ordering/0130fe9413a97-getting-started-with-online-ordering-ap-is).' reward_id: type: integer description: Send this value when discount_type is reward. This is the ID of the reward the user wants to redeem. format: int64 redeemable_id: type: string description: Send this value when discount_type is redeemable. This is the ID of the redeemable the user wants to redeem. redeemed_points: type: string description: Send this value when discount_type is discount_amount. This is the amount of the banked rewards the user wants to redeem. redemption_code: type: string description: Send this value when discount_type is redemption_code. This is the redemption code or Punchh coupon code that is associated with redemption. subscription_id: type: string description: Send this value when discount_type is subscription. This is a system-generated unique ID of the subscription that is issued to the guest. email: type: string description: Email address of the user (required to be sent only in case of coupons and promos) required: - store_number - receipt_amount - subtotal_amount - receipt_datetime - transaction_no - client - discount_type tags: - Auth servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com /api/auth/redemptions: post: responses: '200': description: '' content: application/json: schema: type: object properties: internal_tracking_code: type: integer description: Internal tracking code generated on the redemption expiry_hours: type: integer description: Total number of hours after which the redemption code will expire examples: default: value: internal_tracking_code: '2142353' expiry_hours: '24' '401': description: Sending invalid credentials '412': description: Sending invalid Signature '422': description: Sending invalid Entity summary: Fetch Redemption Code (Redemptions 1.0) description: 'This endpoint generates an internal tracking code, which can be used to [look up a user on the POS system](/docs/dev-portal-pos/b3A6NTAyODM5MTc-user-lookup-and-fetch-balance) and [redeem the selected reward or banked currency at the POS](/docs/dev-portal-pos/4aa6c9741c85d-create-redemption-redemptions-1-0). To generate an internal tracking code via this endpoint, you must supply either a reward ID in the **reward_id** parameter or a value for the banked currency to redeem in the **redeemed_points** parameter. While the internal tracking code is active, the selected reward or banked currency value is eligible for redemption at the POS using the value of the internal tracking code as the **redemption_code** in the [POS Redemption API endpoint](/docs/dev-portal-pos/4aa6c9741c85d-create-redemption-redemptions-1-0). >User authentication required > >This API requires authentication_token to be supplied as `HTTP_AUTHORIZATION` header or in the `authentication_token` parameter.' operationId: sso_fetch_redemption_code parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' x-stoplight: id: 85f9cf163d423 requestBody: content: application/json: schema: type: object properties: 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). client: type: string description: Client key of the business location_id: type: integer format: int32 description: Location ID of the redemption locale: type: string description: Locale used for language longitude: type: string description: Longitude of the redemption location latitude: type: string description: Latitude of the redemption location redeemed_points: type: number format: double description: Value of banked currency to redeem. Use this field only if you have a Points Convert to Currency program type and you are trying to redeem banked currency. Otherwise, use the **reward_id** field only. reward_id: type: integer format: int64 description: Reward ID (required if redeemed_points is not provided) gps_accuracy: type: integer description: 'GPS accuracy ' store_number: type: string description: 'Store number of the location. This can be used as an alternative to specify the location if location_id/latitute/longitude are not provided. ' required: - client - redeemed_points - reward_id examples: default: value: authentication_token: AUTHENTICATION_TOKEN_GOES_HERE client: CLIENT_GOES_HERE location_id: 304155 locale: '' longitude: '75.8136926' latitude: '26.9167509' redeemed_points: null reward_id: 12345 gps_accuracy: 27 store_number: '12' description: '' tags: - Auth delete: responses: '202': description: '' content: application/json: schema: type: object properties: {} summary: Void Processed Redemption (Redemptions 1.0) description: 'Voids a processed redemption. After a redemption is voided successfully, the offer tied to the redemption is returned to the guest''s account. Note: The Void Redemption API allows you to cancel a redemption without any time restrictions for most types of redemptions. However, for coupons and promos, redemptions can only be voided within 24 hours of the redemption process.' operationId: sso_void_processed_redemption parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' x-stoplight: id: b7e6468ce7ed7 requestBody: content: application/json: schema: type: object properties: redemption_id: type: integer format: int64 description: ID of the redemption that you want to delete 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 reason: type: string description: Why the redemption is being deleted redemption_code: type: string description: To be entered if the redemption ID is not provided. If both redemption_id and redemption_code are provided, then only redemption_id will be processed. required: - redemption_id - client examples: default: value: redemption_id: 323242 authentication_token: AUTHENTICATION_TOKEN_GOES_HERE client: CLIENT_GOES_HERE tags: - Auth servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com /api/auth/redemptions/applicable_offers: get: responses: '200': description: '' content: application/json: schema: type: array items: type: object properties: menu_items: $ref: '#/components/schemas/Menu-items' discount_amount: type: integer description: Discount amount applied to the order for an applicable offer or reward reward: type: object properties: created_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the reward was created, in YYYY-MM-DD format end_date_tz: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the reward will expire, in YYYY-MM-DD format start_date_tz: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the reward becomes available, in YYYY-MM-DD format updated_at: type: string enum: - YYYY-MM-DDThh:mm:ssZ format: date-time description: Date/time when the reward was updated, in YYYY-MM-DD format id: type: integer format: int64 description: ID of the reward image: type: string description: Image of the reward status: type: string description: 'Status of the reward (e.g., "unreedemmed", "expired") ' points: type: integer description: Points needed to redeem the reward discount_amount: type: integer description: Discount amount of the reward description: type: string description: Description of the reward name: type: string description: Name of the reward redeemable_properties: type: string description: Reedemable properties of the reward. Properties such as "Merchandise", "Food Item", etc. added to a particular redeemable. examples: default: value: - menu_items: - item_name: Adult item_qty: 1 item_amount: 100 menu_item_type: M menu_item_id: '1' menu_family: '1' menu_major_group: '1' serial_number: '3.0' discount_amount: 2 reward: created_at: '2023-04-03T05:42:02Z' end_date_tz: null start_date_tz: '2023-04-03T05:42:02Z' updated_at: '2023-04-03T05:42:02Z' id: 1 image: IMAGE_URL_GOES_HERE status: unredeemed points: 0 discount_amount: 2 description: $2 Off Your Order. Participating locations only. name: Redeemable - $2 Off Your Order redeemable_properties: null - menu_items: - item_name: Adult item_qty: 1 item_amount: 100 menu_item_type: M menu_item_id: '1' menu_family: '1' menu_major_group: '1' serial_number: '3.0' discount_amount: 2 reward: created_at: '2023-04-03T05:46:32Z' end_date_tz: null start_date_tz: '2023-04-03T05:46:32Z' updated_at: '2023-04-03T05:46:32Z' id: 2 image: IMAGE_URL_GOES_HERE status: unredeemed points: 0 discount_amount: 2 description: '' name: 2% off Subtotal Amount redeemable_properties: null '401': description: Sending invalid credentials '412': description: Sending invalid Signature '422': description: The given reward can't be applied to the given receipt details summary: Applicable Offers (Redemptions 1.0) description: Returns all applicable rewards available to the user per the items added to the check operationId: sso_applicable_offers parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' x-stoplight: id: ae5f635ab632f 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 receipt_amount: type: number format: double 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. subtotal_amount: type: number format: double 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_datetime: type: string format: date-time description: Timestamp of the receipt as per ISO 8601, in YYYY-MM-DDThh:mm:ssZ format store_number: type: string description: Location where the redemption must be redeemed menu_items: $ref: '#/components/schemas/menu_items' channel: type: string x-stoplight: id: tfd4xyagg7i9x description: 'Channel through which the order was placed. If a channel is defined in the Receipt Qualifier condition under Offers > Qualification Criteria in the Punchh platform, the API returns the list of offers applicable to the transaction after evaluating the value set for the channel. Possible values: online_order, web.' enum: - online_order - web required: - client - receipt_amount - subtotal_amount - receipt_datetime - channel tags: - Auth servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com /api/auth/discounts/auto_select: post: summary: Auto Redemption (Redemptions 2.0) operationId: post-api-auth-discounts-auto_select responses: '200': description: OK content: application/json: schema: type: object properties: redemption_ref: type: string description: Transaction level identifier for all discount selections locked: type: boolean x-stoplight: id: bza0ruu9nwh31 description: Indicates whether the discount basket is locked. A value of true means the basket is locked. created_at: type: string description: Date/time when the first discount was selected, in YYYY-MM-DDThh:mm:ss format format: date-time discount_basket_items: $ref: '#/components/schemas/discount_basket_items' examples: Example: value: redemption_ref: REDEMPTION_REF_GOES_HERE locked: true created_at: null discount_basket_items: - discount_basket_item_id: 4699 discount_type: reward discount_id: '33703164' discount_value: null created_at: '2022-08-25T10:03:48Z' discount_details: item_id: 777658 name: Flat $5 Off (Unlocks at 100 points) campaign_name: Mass Campaign Offer image: IMAGE_URL_GOES_HERE points: 100 base_amount: 5 description: '' item_properties: null meta_detail: null start_date_tz: null end_date_tz: null created_at: '2022-09-08T18:41:16Z' auto_select: true Listing expired discount with error message: value: redemption_ref: REDEMPTION_REF_GOES_HERE locked: true created_at: null discount_basket_items: - discount_basket_item_id: 4699 discount_type: reward discount_id: '33703164' discount_value: null created_at: '2022-08-25T10:03:48Z' discount_details: item_id: 777658 name: Flat $5 Off (Unlocks at 100 points) campaign_name: Mass Campaign Offer image: IMAGE_URL_GOES_HERE points: 100 base_amount: 5 description: '' item_properties: null meta_detail: null start_date_tz: null end_date_tz: null created_at: '2022-09-08T18:41:16Z' auto_select: true - discount_basket_item_id: 4890 discount_type: reward discount_id: '33703165' discount_value: null created_at: '2022-08-25T10:03:48Z' message: - Invalid Reward ID. discount_details: null '400': description: 'Bad Request - Example error responses: - Required parameter missing or the value is empty: receipt_amount - Required parameter missing or the value is empty: line_items' content: application/json: schema: type: object properties: {} '404': description: Not Found - User not found content: application/json: schema: type: object properties: {} '422': description: 'Unprocessable Entity - Example error responses: - Guest is not allowed to select/unselect from basket as he/she is banned or deactivated from the Loyalty program - Invalid Receipt Amount - Your current loyalty program configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. - Unable to access the user’s Discount Basket, the Basket is currently locked' content: application/json: schema: type: object properties: {} description: '- A discount should be automatically queued up in the discount basket if the auto-redemption feature is enabled for the business. - The business can configure the auto-redemption strategy. - If a discount expires after being added to the discount basket, it is removed from the discount basket. When you make a call to the API, it validates the discounts added to the discount basket. If one or more discounts are found to be honored, expired, perished, or archived, the API returns an error message indicating that these discounts cannot be honored. The API lists the invalid discounts in the `discount_basket_items` object with a message stating that the discount is invalid and returns a null value in the `discount_details` object. **Note**: Auto-redemption currently supports only subscriptions and non-points-based rewards.' parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/accept_language' x-stoplight: id: d3e1d4293ad65 requestBody: content: application/json: schema: type: object properties: client: type: string description: Client key of the business line_items: $ref: '#/components/schemas/line_items' receipt_datetime: type: string description: Timestamp of receipt per ISO 8601 format, including TZ offset from UTC (YYYY-MM-DDThh:mm:ss-±hh:mm) format: date-time 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 format: float 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. business_date: type: string description: Business date transaction_no: type: string description: Transaction number external_uid: type: string x-stoplight: id: l8errxvcbef2m description: 'Unique identifier generated by the system to lock the discount basket and prevent duplicate transactions. This parameter is optional when reward locking is enabled for the business in the Punchh platform. Note: Contact your Punchh representative to update this configuration.' required: - client - receipt_datetime - subtotal_amount - receipt_amount examples: Example: value: line_items: - item_name: coffee item_qty: 1 amount: 10 item_type: M item_id: 330 item_family: '10' item_group: gp serial_number: 1 - item_name: pizza item_qty: 1 amount: 20 item_type: M item_id: 331 item_family: '10' item_group: gp serial_number: 2 receipt_datetime: '2019-04-11T14:14:07+05:30' subtotal_amount: 100 receipt_amount: 100 business_date: transaction_no: '11111111111' client: CLIENT_GOES_HERE external_uid: EXTERNAL_UID_GOES_HERE tags: - Auth servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com /api/auth/discounts/select: post: responses: '200': description: '' content: application/json: schema: type: object properties: redemption_ref: type: string description: Transaction level identifier for all discount selections locked: type: boolean x-stoplight: id: eada20qcylhhh description: Indicates whether the discount basket is locked. A value of true means the basket is locked. created_at: type: string format: date-time description: Date/time when the first discount was selected, in YYYY-MM-DDThh:mm:ss format discount_basket_items: $ref: '#/components/schemas/discount_basket_items' examples: Example: value: redemption_ref: REDEMPTION_REF_GOES_HERE locked: false created_at: '2024-05-21T15:14:02Z' discount_basket_items: - discount_basket_item_id: 469363 discount_type: reward discount_id: '41049646877' discount_value: null created_at: '2024-05-24T08:36:52Z' discount_details: item_id: 48188 name: Sandwich Test | AK campaign_name: Mass Campaign Offer image: IMAGE_URL_GOES_HERE points: null base_amount: null description: '' item_properties: '' meta_detail: null start_date_tz: '2024-05-24T08:34:24Z' end_date_tz: '2024-06-30T03:15:00Z' created_at: '2023-08-18T08:29:36Z' auto_select: false - discount_basket_item_id: 541689 discount_type: reward discount_id: '41378920421' discount_value: null created_at: '2024-06-11T12:56:33Z' discount_details: item_id: 48188 name: Sandwich Test | AK campaign_name: Mass Campaign Offer image: IMAGE_URL_GOES_HERE points: null base_amount: null description: '' item_properties: '' meta_detail: null start_date_tz: '2024-05-31T13:25:08Z' end_date_tz: '2024-06-30T03:15:00Z' created_at: '2023-08-18T08:29:36Z' auto_select: false '400': description: 'Bad Request - Example error responses: - Required parameter missing or the value is empty: user_id - Required parameter missing or the value is empty: discount_basket_items_attributes - Required parameter missing or the value is empty: discount_type - Required parameter missing or the value is empty: external_uid' content: application/json: schema: type: object properties: {} '404': description: Not Found - User not found content: application/json: schema: type: object properties: {} '422': description: 'Unprocessable Entity - Example error responses: - Discount basket items have already been taken for the user - Same parameters provided multiple times - Not enough cards - Processing limit for discounts of loyalty type has been reached - Invalid Code - Coupon/Promo code is not active - The code can not be added, as the campaign has exceeded its usage limit - This coupon can only be used 1 time(s) per day - Invalid Business Configuration. Please connect with your Customer Success representative for resolution of the issue. - Mobile Coupon/Promo cannot be added into basket - Balance is insufficient to process request - Max Redemption Amount has been reached - Invalid Discount Value - Unable to access the user’s Discount Basket, the Basket is currently locked - Interoperability validation failed - Invalid Subscription ID - Invalid Redeemable ID - Invalid Reward ID - Guest is not allowed to select/unselect from basket as he/she is banned or deactivated from the Loyalty program - Redemption limit reached - Discount type should be card_completion, discount_amount, redemption_code, reward, fuel_reward, redeemable, subscription - Another transaction is currently accessing the same code. Please try after some time. - Cannot add more than one subscription into basket' content: application/json: schema: type: object properties: {} description: '- A single discount basket will be active at a time. If there is no active discount basket, the system will create a new active discount basket along with selected discounts passed in the request parameters. - The Punchh system will not have any validation based on points adjustments as discounts are added. - When a guest adds multiple discounts, and one is invalid for some reason, the entire request will fail with an error message. The guest will then be required to remove the invalid discount and resubmit. ' summary: Add Selection to Discount Basket (Redemptions 2.0) operationId: sso_create_online_redemption parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/accept_language' x-stoplight: id: 49c4867d18844 requestBody: content: application/json: schema: type: object properties: client: type: string description: Client key of the business discount_basket_items_attributes: type: array description: List of discounts to add to basket items: type: object properties: discount_type: type: string enum: - reward - card_completion - redeemable - discount_amount - redemption_code - subscription - fuel_reward description: 'The discount type can be any one of these values: card_completion || reward || redeemable || discount_amount || redemption_code || subscription || fuel_reward. For details, see [Getting Started With Online Ordering APIs](/docs/dev-portal-online-ordering/0130fe9413a97-getting-started-with-online-ordering-ap-is).' discount_id: type: integer description: Discount ID discount_value: type: number description: Value of discount. Send this value when discount_type is discount_amount. This is the amount of the banked rewards the user wants to redeem. format: float required: - discount_type external_uid: type: string x-stoplight: id: 3y6agmfqv4r4w description: 'Unique identifier generated by the system to lock the discount basket and prevent duplicate transactions. This parameter is optional when reward locking is enabled for the business in the Punchh platform. Note: Contact your Punchh representative to update this configuration.' required: - client - discount_basket_items_attributes examples: Example: value: discount_basket_items_attributes: - discount_id: 131 discount_type: reward - discount_value: 2 discount_type: discount_amount client: CLIENT_GOES_HERE external_uid: EXTERNAL_UID_GOES_HERE description: '' tags: - Auth servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com /api/auth/discounts/unselect: parameters: [] delete: summary: Remove Item From Discount Basket (Redemptions 2.0) operationId: delete-api-auth-discounts-unselect responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: redemption_ref: type: string description: Transaction level identifier for all discount selections locked: type: boolean x-stoplight: id: rl8ecf3bw8dll description: Indicates whether the discount basket is locked. A value of true means the basket is locked. created_at: type: string format: date-time description: Date/time when the first discount was selected, in YYYY-MM-DDThh:mm:ss format discount_basket_items: $ref: '#/components/schemas/discount_basket_items' examples: Example: value: redemption_ref: REDEMPTION_REF_GOES_HERE locked: false created_at: '2024-05-21T15:14:02Z' discount_basket_items: - discount_basket_item_id: 469363 discount_type: reward discount_id: '41049646877' discount_value: null created_at: '2024-05-24T08:36:52Z' discount_details: item_id: 48188 name: Sandwich Test | AK campaign_name: Mass Campaign Offer image: IMAGE_URL_GOES_HERE points: null base_amount: null description: '' item_properties: '' meta_detail: null start_date_tz: '2024-05-24T08:34:24Z' end_date_tz: '2024-06-30T03:15:00Z' created_at: '2023-08-18T08:29:36Z' auto_select: false - discount_basket_item_id: 541689 discount_type: reward discount_id: '41378920421' discount_value: null created_at: '2024-06-11T12:56:33Z' discount_details: item_id: 48188 name: Sandwich Test | AK campaign_name: Mass Campaign Offer image: IMAGE_URL_GOES_HERE points: null base_amount: null description: '' item_properties: '' meta_detail: null start_date_tz: '2024-05-31T13:25:08Z' end_date_tz: '2024-06-30T03:15:00Z' created_at: '2023-08-18T08:29:36Z' auto_select: false '400': description: 'Bad Request - Required parameter missing or the value is empty: discount_basket_item_ids' content: application/json: schema: type: object properties: {} '404': description: 'Not Found - Example error responses: - User does not have an active basket - User not found' content: application/json: schema: type: object properties: {} '422': description: 'Unprocessable Entity - Example error responses: - Discount Items not found with any given ids - Guest is not allowed to select/unselect from basket as he/she is banned or deactivated from the Loyalty program - Unable to access the user’s Discount Basket, the Basket is currently locked' content: application/json: schema: type: object properties: {} description: Delete one or more discounts from a discount basket. parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/accept_language' x-stoplight: id: 8a087a5033151 requestBody: content: application/json: schema: type: object properties: client: type: string description: Client key of the business discount_basket_item_ids: type: array description: IDs of items that need to be removed from the discount basket items: type: integer external_uid: type: string x-stoplight: id: wy2ef1w8pibgg description: 'Unique identifier generated by the system to lock the discount basket and prevent duplicate transactions. This parameter is optional when reward locking is enabled for the business in the Punchh platform. Note: Contact your Punchh representative to update this configuration.' required: - client - discount_basket_item_ids examples: Example: value: discount_basket_item_ids: - 4690 - 4691 client: CLIENT_GOES_HERE external_uid: EXTERNAL_UID_GOES_HERE tags: - Auth servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com /api/auth/discounts/active: get: summary: Get Active Discount Basket (Redemptions 2.0) tags: - Auth responses: '200': description: OK content: application/json: schema: type: object properties: redemption_ref: type: string description: Transaction level identifier for all discount selections locked: type: boolean x-stoplight: id: rq8knfiuv9tfn description: Indicates whether the discount basket is locked. A value of true means the basket is locked. created_at: type: string description: Date/time when the first discount was selected, in YYYY-MM-DDThh:mm:ss format format: date-time discount_basket_items: $ref: '#/components/schemas/discount_basket_items' examples: Example: value: redemption_ref: REDEMPTION_REF_GOES_HERE locked: true created_at: null discount_basket_items: - discount_basket_item_id: 4699 discount_type: reward discount_id: '33703164' discount_value: null created_at: '2022-08-25T10:03:48Z' discount_details: item_id: 777658 name: Flat $5 Off (Unlocks at 100 points) campaign_name: Mass Campaign Offer image: IMAGE_URL_GOES_HERE points: 100 base_amount: 5 description: '' item_properties: null meta_detail: null start_date_tz: null end_date_tz: null created_at: '2022-09-08T18:41:16Z' auto_select: true Listing expired discount with error message: value: redemption_ref: REDEMPTION_REF_GOES_HERE locked: true created_at: null discount_basket_items: - discount_basket_item_id: 4699 discount_type: reward discount_id: '33703164' discount_value: null created_at: '2022-08-25T10:03:48Z' discount_details: item_id: 777658 name: Flat $5 Off (Unlocks at 100 points) campaign_name: Mass Campaign Offer image: IMAGE_URL_GOES_HERE points: 100 base_amount: 5 description: '' item_properties: null meta_detail: null start_date_tz: null end_date_tz: null created_at: '2022-09-08T18:41:16Z' auto_select: true - discount_basket_item_id: 4890 discount_type: reward discount_id: '33703165' discount_value: null created_at: '2022-08-25T10:03:48Z' message: - Invalid Reward ID. discount_details: null '404': description: 'Not Found - Example error responses: - User does not have an active basket - User not found' content: application/json: schema: type: object properties: {} '422': description: 'Unprocessable Entity - Example error responses: - Your current loyalty program configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. - Unable to access the user’s Discount Basket, the Basket is currently locked' content: application/json: schema: type: object properties: {} operationId: get-api-auth-discounts-active parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/accept_language' description: '- Get a list of discount details that have been selected by a guest. Only one active basket can exist in the system for a particular guest. - If a discount expires after being added to the discount basket, it is removed from the discount basket. When you make a call to the API, it validates the discounts added to the discount basket. If one or more discounts are found to be honored, expired, perished, or archived, the API returns an error message indicating that these discounts cannot be honored. The API lists the invalid discounts in the `discount_basket_items` object with a message stating that the discount is invalid and returns a null value in the `discount_details` object.' x-stoplight: id: 1d4f01cf7aa32 requestBody: content: application/json: schema: type: object properties: client: type: string description: Client key of the business external_uid: type: string x-stoplight: id: 0bylg45q0jgsf description: 'Unique identifier generated by the system to lock the discount basket and prevent duplicate transactions. This parameter is optional when reward locking is enabled for the business in the Punchh platform. Note: Contact your Punchh representative to update this configuration.' required: - client examples: Example: value: client: CLIENT_GOES_HERE external_uid: EXTERNAL_UID_GOES_HERE servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com /api/auth/batch_redemptions: parameters: [] post: responses: '200': description: '' content: application/json: schema: type: object properties: redemption_ref: type: string description: Transaction level identifier for all discount selections success: type: array description: List of discounts results that are successfully redeemed items: type: object failures: type: array description: The failures array in the response lists discounts that are not successfully redeemed, even if the HTTP request returns a 200 status. Note that not all HTTP request failures result in a 4xx HTTP status code. items: type: object discount_basket_item_id: type: integer description: Unique identifier of selection discount_amount: type: integer description: Discount amount/points redemption_id: type: integer format: int64 description: Unique ID of the redemption redemption_type: type: string description: Redemption status discount_type: type: string description: Discount type (e.g., reward, redeemable, etc.) discount_id: type: integer description: Discount ID (e.g., reward_id, redeemable_id, redemption_code, coupon_code) discount_value: type: number description: Value of the currency that a user wants to redeem. This value is set for users on the “Points Convert to Currency” loyalty program. The default value is 0 if the user has not selected any amount to redeem or has no currency in the loyalty account. The parameter returns a “null” value for a business that does not support banking of points into currency. format: float message: type: string description: Error message qualified: type: boolean description: Indicates a discount's applicability to the receipt remaining_balance: type: number description: Total amount remaining meta_data: type: string description: Metadata that can be added to a redeemable. This can be used to program mobile apps to have a 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.

The `meta_data` value for the coupon redemption (i.e., when discount_type = redemption_code) is returned in the language specified in the Accept-Language request header, provided the meta_data has been translated into the relevant language in the Punchh platform. If the translation is unavailable, the response returns the value for this parameter in the default English language. For example, if the header specifies “fr” (French), the `meta_data` value for a coupon is returned in French only if a French translation is configured for the coupon meta data in the Punchh platform; otherwise the value is returned in the default English language. discount_details: $ref: '#/components/schemas/discount_details' qualified_items: $ref: '#/components/schemas/qualified_items' qualifying_conditions: type: object x-stoplight: id: o9y5lovw1ufdq description: The object lists all qualification criteria (both receipt-level and line-item) for submitted offers that failed while processing the redemption. This object is returned in the response only if the option to return the qualifying conditions for Redemption 2.0 flow is enabled for the business in the Punchh platform. See the `data` object under [Get Qualification Criteria Response](https://developers.partech.com/docs/dev-portal-platform-functions/97ec083d6cf57-get-qualification-criteria-qc-list#response-body) in Platform Functions for descriptions of the parameters in `qualifying_conditions`. examples: Discount Qualification on Receipt Failed: value: redemption_ref: REDEMPTION_REF_GOES_HERE success: [] failures: - discount_basket_item_id: 1 discount_amount: null redemption_id: null redemption_type: null discount_type: reward discount_id: '367778' discount_value: null message: - Discount qualification on receipt failed for Shubham Gupta at Airway. qualified: false remaining_balance: null meta_data: null qualifying_conditions: name: LIS QC 21 july 2025 external_id: EXTERNAL_UID_GOES_HERE amount_cap: null rounding_rule: '' max_discount_units: null target_price: null effective_location: [] stack_discounting: null reuse_qualifying_items: null enable_menu_item_aggregator: false min_post_rollback_rate: null unit_discount: null receipt_qualifiers: - attribute: amount operator: '>=' value: '5' - attribute: subtotal_amount operator: '>=' value: '5' percentage_of_processed_amount: null qc_processing_function: sum_amounts line_item_filters: - quantity: null processing_method: '' line_item_selector: name: LIS 17 july 2025 external_id: EXTERNAL_UID_GOES_HERE exclude_non_payable: false filter_item_set: base_and_modifiers base_items: clauses: - attribute: item_id operator: in value: 101,106,107 - attribute: item_name operator: like value: Cookie modifiers: processing_method: min_price max_discount_units: 2 clauses: - attribute: item_id operator: in value: '1010' item_qualifiers: - expression_type: net_amount_greater_than_or_equal_to net_value: 6 line_item_selector: name: LIS 2 17 july 2025 external_id: EXTERNAL_UID_GOES_HERE exclude_non_payable: false filter_item_set: base_only base_items: clauses: - attribute: item_id operator: in value: '102' modifiers: processing_method: '' max_discount_units: null clauses: [] aggregator_grouping_attributes: item_name: true item_id: true item_major_group: true item_family: true item_type: true discount_details: item_id: 92 name: LIS QC 21 july 2025 redeemable image: IMAGE_URL_GOES_HERE points: null base_amount: null description: LIS QC 21 july 2025 redeemable item_properties: null meta_detail: '' start_date_tz: '2025-08-04T05:48:26Z' end_date_tz: '2025-08-31T18:29:59Z' created_at: '2025-07-21T12:34:09Z' max_applicable_quantity: null prompt_text_short: null prompt_text_long: null qualified_items: [] - discount_basket_item_id: 2 discount_amount: null redemption_id: null redemption_type: null discount_type: reward discount_id: '367779' discount_value: null message: - Discount qualification on receipt failed for Shubham Gupta at Airway. qualified: false remaining_balance: null meta_data: null qualifying_conditions: name: LIS QC 21 july 2025 external_id: EXTERNAL_UID_GOES_HERE amount_cap: null rounding_rule: '' max_discount_units: null target_price: null effective_location: [] stack_discounting: null reuse_qualifying_items: null enable_menu_item_aggregator: false min_post_rollback_rate: null unit_discount: null receipt_qualifiers: - attribute: amount operator: '>=' value: '5' - attribute: subtotal_amount operator: '>=' value: '5' percentage_of_processed_amount: null qc_processing_function: sum_amounts line_item_filters: - quantity: null processing_method: '' line_item_selector: name: LIS 17 july 2025 external_id: EXTERNAL_UID_GOES_HERE exclude_non_payable: false filter_item_set: base_and_modifiers base_items: clauses: - attribute: item_id operator: in value: 101,106,107 - attribute: item_name operator: like value: Cookie modifiers: processing_method: min_price max_discount_units: 2 clauses: - attribute: item_id operator: in value: '1010' item_qualifiers: - expression_type: net_amount_greater_than_or_equal_to net_value: 6 line_item_selector: name: LIS 2 17 july 2025 external_id: EXTERNAL_UID_GOES_HERE exclude_non_payable: false filter_item_set: base_only base_items: clauses: - attribute: item_id operator: in value: '102' modifiers: processing_method: '' max_discount_units: null clauses: [] aggregator_grouping_attributes: item_name: true item_id: true item_major_group: true item_family: true item_type: true discount_details: item_id: 92 name: LIS QC 21 july 2025 redeemable image: IMAGE_URL_GOES_HERE points: null base_amount: null description: LIS QC 21 july 2025 redeemable item_properties: null meta_detail: '' start_date_tz: '2025-08-04T05:53:04Z' end_date_tz: '2025-08-31T18:29:59Z' created_at: '2025-07-21T12:34:09Z' max_applicable_quantity: null prompt_text_short: null prompt_text_long: null qualified_items: [] Possible Redemption: value: redemption_ref: REDEMPTION_REF_GOES_HERE success: - discount_basket_item_id: 266118 discount_amount: 5 redemption_id: 130097719 redemption_type: Redemption discount_type: redeemable discount_id: 777658 discount_value: null message: null qualified: true remaining_balance: null meta_data: null discount_details: item_id: 777658 name: Flat $5 Off (Unlocks at 100 points) campaign_name: Mass Campaign Offer image: IMAGE_URL_GOES_HERE points: 100 base_amount: 5 description: '' item_properties: null meta_detail: null start_date_tz: null end_date_tz: null created_at: '2022-09-08T18:41:16Z' auto_select: true qualified_items: - item_name: Pizza1 DISCOUNT item_qty: 2 amount: 3.04 item_type: R item_id: 101 item_family: '10' item_group: '999' serial_number: '1.0' failures: [] Process Redemption: value: redemption_ref: REDEMPTION_REF_GOES_HERE success: - discount_basket_item_id: 266118 discount_amount: 5 redemption_id: 130097719 redemption_type: Redemption discount_type: redeemable discount_id: 777658 discount_value: null message: null qualified: true remaining_balance: null meta_data: null discount_details: item_id: 777658 name: Flat $5 Off (Unlocks at 100 points) image: IMAGE_URL_GOES_HERE points: 100 base_amount: 5 description: '' item_properties: null meta_detail: null start_date_tz: null end_date_tz: null created_at: '2022-09-08T18:41:16Z' qualified_items: - item_name: Pizza1 DISCOUNT item_qty: 2 amount: 3.04 item_type: R item_id: 101 item_family: '10' item_group: '999' serial_number: '1.0' failures: [] Redemption is not successful: value: redemption_ref: REDEMPTION_REF_GOES_HERE success: [] failures: - discount_basket_item_id: 274165 discount_amount: 0 redemption_id: 311367823 redemption_type: Redemption discount_type: redeemable discount_id: '33089' discount_value: null message: null qualified: false remaining_balance: null meta_data: null discount_details: item_id: 33089 name: Punchh Free Beverage image: IMAGE_URL_GOES_HERE points: 50 base_amount: null description: '' item_properties: '' meta_detail: null start_date_tz: null end_date_tz: null created_at: '2024-04-09T23:27:45Z' auto_select: false prompt_text_short: '' prompt_text_long: '' qualified_items: [] '400': description: 'Bad Request - Example error responses: - Required parameter missing or the value is empty: line_items - Required parameter missing or the value is empty: item_name_0 - Required parameter missing or the value is empty: item_qty_0 - Required parameter missing or the value is empty: receipt_amount - Required parameter missing or the value is empty: id' content: application/json: schema: type: object properties: {} '404': description: Not Found - User not found content: application/json: schema: type: object properties: {} '422': description: 'Unprocessable Entity - Example error responses: - Processing limit for discounts of loyalty type has been reached - Redemption limit reached - No Basket found - Points Balance is insufficient to process request - Your current loyalty program configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. - Invalid Receipt Amount - Unable to access the user’s Discount Basket, the Basket is currently locked' content: application/json: schema: type: object properties: {} description: "Evaluates the validity of all inputs and commits the redemption. \n\nPunchh evaluates eligibility during the Possible Redemptions call using the receipt details provided (item name, price, quantity, identifiers, etc.). During the Batch Redemption Process call, Punchh revalidates the same receipt to ensure the qualifying conditions are still met before honoring the redemption. \n\nIf any item attributes change between the two calls, Punchh may be unable to match the qualifying items, which can cause the Batch Redemption Process call to fail or return a different result—even if the Possible Redemptions call was successful.\n\nNOTE: When processing a redemption, DO NOT include the `query` parameter in the API request. Use this parameter only to check for possible redemptions.\n\nAdditional behavior:\n - For orders placed for a future date, the guest’s loyalty account balance is evaluated on the order commit date (sysdate), not on the scheduled pickup or delivery date.\n - Locks the user's discount basket using a unique identifier `external_uid` generated by your application for the transaction when reward locking is enabled in the Punchh platform for the business. Locking the discount basket prevents other channels from creating simultaneous transactions or modifying the discount basket. See [Discount Basket Locking Developer Guide](/docs/dev-portal-developer-resources/d7b83074c9f23-redemptions-2-0-discount-basket-locking). You must log in to the developer portal to access the developer guide.\n\nWhen the Batch Redemption Process API commits the redemption, one of the following actions may occur based on the discount type:\n - Loyalty points are deducted from the guest account when `discount_type` = \"redeemable\" or \"card_completion\"\n - The reward is debited from the guest account when `discount_type` = \"reward\"\n - Banked rewards / currency are deducted from the guest’s loyalty account when `discount_type` = \"discount_amount\"" summary: Batch Redemption Process (Redemptions 2.0) operationId: sso_create_online_redemption parameters: - $ref: '#/components/parameters/Signature' - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/accept_language' x-stoplight: id: 6031cbeb5bec2 requestBody: content: application/json: schema: type: object properties: query: type: boolean description: Include this parameter only if you want to make a possible redemptions call. The parameter value must be true. If you want to process a redemption, do not include this parameter in the request. store_number: type: integer description: Unique identifier for store location client: type: string description: Client key of the business line_items: $ref: '#/components/schemas/line_items' receipt_datetime: type: string description: Timestamp of receipt per ISO 8601 format, including TZ offset from UTC (YYYY-MM-DDThh:mm:ss-±hh:mm) format: date-time 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 format: float 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. transaction_no: type: string description: Transaction number external_uid: type: string x-stoplight: id: x2lb8yfixy7a4 description: 'Unique identifier generated by the system to lock the discount basket and prevent duplicate transactions. This parameter is required when reward locking is enabled for the business in the Punchh platform. Note: Contact your Punchh representative to update this configuration.' required: - store_number - client - line_items - receipt_datetime - subtotal_amount - receipt_amount examples: Possible Redemption: value: query: true store_number: 900 client: CLIENT_GOES_HERE line_items: - item_name: coffee item_qty: 1 amount: 10 item_type: M item_id: 330 item_family: '10' item_group: gp serial_number: 1 - item_name: pizza item_qty: 1 amount: 20 item_type: M item_id: 331 item_family: '10' item_group: gp serial_number: 2 receipt_datetime: '2019-04-11T14:14:07+05:30' subtotal_amount: 100 receipt_amount: 100 transaction_no: '11111111111' external_uid: EXTERNAL_UID_GOES_HERE Process Redemption: value: store_number: 900 client: CLIENT_GOES_HERE line_items: - item_name: coffee item_qty: 1 amount: 10 item_type: M item_id: 330 item_family: '10' item_group: gp serial_number: 1 - item_name: pizza item_qty: 1 amount: 20 item_type: M item_id: 331 item_family: '10' item_group: gp serial_number: 2 receipt_datetime: '2019-04-11T14:14:07+05:30' subtotal_amount: 100 receipt_amount: 100 transaction_no: '11111111111' external_uid: EXTERNAL_UID_GOES_HERE description: '' tags: - Auth servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com /api/auth/batch_redemptions/{redemption_ref}: parameters: - schema: type: string name: redemption_ref in: path required: true description: Transaction level identifier for all discount selections
Example - aBCDEfghIJkL-MN1opR delete: summary: Void Redemption (Redemptions 2.0) operationId: delete-api-auth-batch_redemptions responses: '202': description: Accepted - Success Response '400': description: 'Bad Request - Required parameter missing or the value is empty: id' content: application/json: schema: type: object properties: {} '404': description: Not Found - User not found content: application/json: schema: type: object properties: {} '410': description: The checkin associated with the external_uid has already been committed and cannot be voided. content: application/json: schema: type: object properties: error: type: object properties: message: type: string code: type: string examples: Example: value: error: message: Checkin associated with external_uid 9020-202-102252700 has been committed. code: commited '422': description: 'Unprocessable Entity - Example error responses: - Your current loyalty program configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. - No Basket found' content: application/json: schema: type: object properties: {} description: 'Voids the complete discount basket. The value of `redemption_ref` must be appended to the URL path. You can get the `redemption_ref` value from the [Get Active Discount Basket](/docs/dev-portal-online-ordering/apis/oo-redemptions-2-0-new-api/paths/~1api~1auth~1discounts~1active/get) API response. Example: `DELETE https://{base}/api/auth/batch_redemptions/aBCDEfghIJkL-MN1opR` Note: It will not support partial voiding of a discount basket.' parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Signature' x-stoplight: id: 5938281f47e7a requestBody: content: application/json: schema: type: object properties: client: type: string description: Client key of the business required: - client examples: Example: value: client: CLIENT_GOES_HERE tags: - Auth servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com /api/auth/discounts/unlock: put: summary: Unlock Discount Basket (Redemptions 2.0) operationId: put-api-auth-discounts-unlock responses: '200': description: OK - Discount Basket is unlocked successfully. '404': description: Not Found - User not found content: application/json: schema: type: object properties: {} '422': description: 'Unprocessable Entity - Example error responses: - Unable to find valid discount basket - Invalid Business Configuration. Please connect with your Customer Success representative for resolution of the issue. - Your current loyalty program configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. - User does not have an active basket' content: application/json: schema: type: object properties: {} description: 'When reward locking is enabled in the Punchh Platform, the guest''s discount basket must be locked. An external ID will be required to lock the discount basket to prevent other channels from creating simultaneous transactions or modifying the discount basket. In this mode, the guest''s discount basket must be locked when discounts are applied to a transaction, using a unique identifier `external_uid` specific to the transaction generated by your application. The `external_uid` ensures that no modifications or updates are allowed by any channel (e.g., POS terminals/devices, mobile, etc.) except the application that initially locked the discount basket with the `external_uid`. Contact your Punchh representative to update this Punchh platform configuration setting. In some scenarios, such as where a transaction is cancelled or when the guest modifies the order after the basket is locked, the guest''s discount basket needs to be unlocked so that transactions can be processed for the guest via other channels (e.g., POS terminals/devices, mobile, etc.). To unlock the discount basket, the `external_uid` must be passed in the API request along with the user-level `access_token` of the guest.' parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/content_type' - $ref: '#/components/parameters/User-Agent' - $ref: '#/components/parameters/Signature' x-stoplight: id: dd5af3bade194 requestBody: content: application/json: schema: type: object properties: client: type: string x-stoplight: id: q6dstpcnyg9rp description: Client key of the business external_uid: type: string x-stoplight: id: g2knm8l3t6byc description: Unique identifier generated by the system to lock the discount basket to prevent duplicate transactions required: - client - external_uid examples: example: value: client: CLIENT_GOES_HERE external_uid: EXTERNAL_UID_GOES_HERE tags: - Auth servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com /api/auth/subscriptions: parameters: [] get: summary: Fetch Active Purchasable Subscription Plans operationId: post-api-auth-subscriptions responses: '200': description: Success response if the business supports subscriptions headers: {} content: application/json: schema: type: array minItems: 1 uniqueItems: true x-examples: example-1: - name: test v1 description: '' miscellaneous: '' validity: 30 start_time: '2021-04-28T13:59:47+05:30' end_time: '2021-05-28T13:59:47+05:30' signup_end_date: '2021-05-18T13:59:47+05:30' plan_id: 4 purchase_price: 12 image: test-image.png - name: Test3 description: hello test 3 miscellaneous: null validity: null start_time: '2021-04-28T13:59:47+05:30' end_time: '2021-05-28T13:59:47+05:30' signup_end_date: '2021-05-18T13:59:47+05:30' plan_id: 3 purchase_price: 12 image: null - name: Test2 description: hello test 2 miscellaneous: null validity: null start_time: '2021-04-28T13:59:47+05:30' end_time: '2021-05-28T13:59:47+05:30' signup_end_date: '2021-05-18T13:59:47+05:30' plan_id: 2 purchase_price: 12 image: null - name: Test1 description: hello test miscellaneous: null validity: null start_time: '2021-04-28T13:59:47+05:30' end_time: '2021-05-28T13:59:47+05:30' signup_end_date: '2021-05-18T13:59:47+05:30' plan_id: 1 purchase_price: 12 image: null description: Array of the active subscription plans items: type: object properties: name: type: string minLength: 1 description: 'Name of the subscription plan as provided by an admin at the time of subscription plan creation Note: The subscription `name` is returned in the language specified in the Accept-Language request header, provided the name has been translated into the relevant language in the Punchh platform. If the translation is not available, then no value is returned for this parameter in the API response. For example, if the header specifies “fr” (French), the subscription name is returned in French only if a French translation for the name is configured in the Punchh platform.' description: type: string description: 'Text description of the subscription plan as configured by an admin on the subscription plan. This is used to explain the offerings of the subscription plan to guests. Note: The subscription `description` is returned in the language specified in the Accept-Language request header, provided the description has been translated into the relevant language in the Punchh platform. If the translation is not available, then no value is returned for this parameter in the API response. For example, if the header specifies “fr” (French), the subscription description is returned in French only if a French translation for the description is configured in the Punchh platform.' miscellaneous: type: string description: 'Free-form text field that can be used by businesses to enter additional information or a JSON code snippet for greater customization in the mobile app Note: The subscription `miscellaneous` information is returned in the language specified in the Accept-Language request header, provided it has been translated into the relevant language in the Punchh platform. If the translation is not available, then no value is returned for this parameter in the API response. For example, if the header specifies “fr” (French), the subscription miscellaneous information is returned in French only if a French translation for the miscellaneous is configured in the Punchh platform.' validity: type: integer format: int32 description: Number of days for which one unit of the subscription plan remains valid after purchase examples: - 30 start_time: type: string minLength: 1 format: date-time description: Date and time (in ISO 8601 format) from which the subscription plan can be purchased by guests examples: - '2023-04-28T13:59:47+05:30' end_time: type: string minLength: 1 format: date-time description: Date and time (in ISO 8601 format) until which the subscription plan can be purchased by guests examples: - '2023-04-28T13:59:47+05:30' signup_start_date: type: string description: Date and time (in ISO 8601 format) after which the subscription plan can be purchased by guests in advance. This can be used by businesses to make a plan available for purchase before it actually starts. Any subscriptions bought after this date and before the start date of the subscription plan will start from the `start_time` of the Subscription Plan. format: date-time examples: - '2023-04-28T13:59:47+05:30' signup_end_date: type: string minLength: 1 format: date-time description: Date and time (in ISO 8601 format) after which the subscription plan cannot be purchased by guests. This is the purchase cut-off time, and a business can use it to nudge guests into purchasing a subscription. examples: - '2023-04-28T13:59:47+05:30' subscriber_capping: type: number description: Maximum number of unique active subscribers for a plan. If the number of active subscribers reaches this limit, fresh purchases in that plan will be stopped. examples: - 400 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. plan_id: type: integer description: System-generated unique ID of a subscription plan created in the Punchh platform format: int64 examples: - 10 purchase_price: type: number format: float description: Cost of purchase of one unit of a subscription plan examples: - 12.32 image: type: string minLength: 1 description: Cover image of a subscription plan uploaded at the time of subscription plan creation examples: - test-image.png time_zone: type: string description: Time zone configured for the subscription plan (e.g., "America/Los_Angeles” ) plan_image_url: type: string description: URL of the image that is configured for a specific subscription plan active_subscribers: type: number description: Number of unique active subscribers of the plan examples: - 251 enable_multibenefit: type: boolean description: "Indicates whether the subscription plan has multi-benefit enabled, allowing up to 5 benefits to be configured on a single plan. Once enabled on a plan, this setting cannot be disabled. \n\nThe Enable multibenefit setting under Wallet and Passes > Passes > Subscription Plans > Plan Details is only available when the multi-benefit subscription feature is enabled for the business. Contact your Punchh representative to update this Punchh platform configuration.\n" purchasable_location_ids: type: array items: type: integer description: "An array of location IDs where the subscription plan is available for purchase. When configured, the plan will only appear as purchasable at these specific locations. If empty or not set, the plan is purchasable at all locations. \n\nReturned only when the multi-benefit subscription feature is enabled for the business, and the subscription plan's Enable multibenefit setting under Wallet and Passes > Passes > Subscription Plans > Plan Details is enabled in the Punchh platform. Contact your Punchh representative to update this Punchh platform configuration.\n" purchasable_tag_ids: type: array items: type: integer description: "An array of location group (tag) IDs where the subscription plan is available for purchase. Location groups allow admins to scope purchasability to a set of locations defined by a reusable group. Works in conjunction with purchasable_location_ids — admins can select individual locations, location groups, or both. \n\nReturned only when the multi-benefit subscription feature is enabled for the business, and the subscription plan's Enable multibenefit setting under Wallet and Passes > Passes > Subscription Plans > Plan Details is enabled in the Punchh platform. Contact your Punchh representative to update this Punchh platform configuration.\n" multiple_effective_locations_name: type: string description: "A human-readable display name summarizing the effective purchasable locations configured for the plan (e.g., selected location names or location group names). Useful for rendering location-scope information on guest-facing surfaces. \n\nReturned only when the multi-benefit subscription feature is enabled for the business, and the subscription plan's Enable multibenefit setting under Wallet and Passes > Passes > Subscription Plans > Plan Details is enabled in the Punchh platform. Contact your Punchh representative to update this Punchh platform configuration.\n" examples: example: value: - name: SUBSCRIPTION_NAME_GOES_HERE description: DESCRIPTION_GOES_HERE miscellaneous: MISC_INFORMATION_GOES_HERE validity: 30 start_time: '2023-05-28T13:59:47+05:30' end_time: '2023-09-28T13:59:47+05:30' signup_start_date: '2023-05-28T13:59:47+05:30' signup_end_date: '2023-09-28T13:59:47+05:30' subscriber_capping: 500 external_plan_identifier: null plan_id: 10 purchase_price: 100 image: test-image.png time_zone: Asia/Kolkata plan_image_url: PLAN_IMAGE_URL_GOES_HERE active_subscribers: 250 enable_multibenefit: true purchasable_location_ids: - 2 - 11 purchasable_tag_ids: - 1 - 2 multiple_effective_locations_name: location-name-1, location-name-10, PineCrossing, Eagle Creek '400': description: Bad Request content: application/json: schema: description: '' type: object x-examples: example-1: errors: client: Required parameter missing or the value is empty. properties: errors: type: object required: - client properties: client: type: string minLength: 1 examples: - Required parameter missing or the value is empty. required: - errors examples: example: value: errors: client: Required parameter missing or the value is empty. '412': description: Precondition Failed content: application/json: schema: description: '' type: object x-examples: example-1: errors: invalid_signature: - Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is properties: errors: type: object properties: invalid_signature: type: array items: type: string examples: - Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is examples: example: value: errors: invalid_signature: - Signature doesn't match. For information about generating the x-pch-digest header, see https://developers.punchh.com. '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: example: 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. description: This API allows online ordering vendors to get a list of all subscription plans that are available for purchase. parameters: - $ref: '#/components/parameters/Accept_2' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/x-pch-digest' - $ref: '#/components/parameters/Content-Type' x-stoplight: id: 78c0011bde123 requestBody: content: application/json: schema: type: object properties: client: type: string description: OAuth client ID provided by the business default: CLIENT_GOES_HERE required: - client examples: application json: value: client: CLIENT_GOES_HERE tags: - Auth post: summary: Purchase Subscription operationId: post-api-auth-subscriptions responses: '200': description: OK content: application/json: schema: type: object x-examples: example-1: subscription_id: '24' start_time: '2021-04-28T13:59:47+05:30' end_time: '2021-04-28T13:59:47+05:30' properties: subscription_id: type: integer description: System-generated unique ID of the subscription plan that is issued for a guest 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-04-28T13:59:47+05:30' end_time: type: string minLength: 1 format: date-time description: Date and time (in ISO 8601 format) until which the subscription plan purchased for the guest will remain active examples: - '2021-04-28T13:59:47+05:30' 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: 23 start_time: '2021-04-28T13:59:47+05:30' end_time: '2021-04-28T13:59:47+05:30' external_plan_identifier: EXTERNAL_PLAN_IDENTIFIER GOES HERE '400': description: Bad Request content: application/json: schema: description: '' type: object x-examples: example-1: errors: client: Required parameter missing or value empty. properties: errors: type: object required: - client properties: client: type: string minLength: 1 examples: - Required parameter missing or value empty. required: - errors examples: example: value: errors: client: Required parameter missing or value empty. '401': description: Unauthorized content: application/json: schema: description: '' type: object x-examples: example-1: errors: unauthorized: - An active access token must be used to query information about the current user. properties: errors: type: object required: - unauthorized properties: unauthorized: type: array items: type: string examples: - An active access token must be used to query information about the current user. required: - errors examples: example: value: errors: unauthorized: - An active access token must be used to query information about the current user. '412': description: Precondition Failed content: application/json: schema: description: '' type: object x-examples: example-1: errors: invalid_signature: - Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is properties: errors: type: object required: - invalid_signature properties: invalid_signature: type: array items: type: string examples: - Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is required: - errors examples: example: value: errors: invalid_signature: - Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is '422': description: Unprocessable Entity content: application/json: schema: 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. required: - errors examples: Subscription Feature is not configured: 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: invalid_request: 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'. Purchase price Null or Negative: value: errors: price: Price must be greater than or equal to 0 Start time Null: value: errors: start_time: Start time cannot be blank End time is Null: value: errors: end_time: End time cannot be blank Purchase call made is past the signup end time or end time of the plan: value: errors: plan_expired: Plan has expired Recurring payments option is disabled: value: errors: recurring_payment_off_for_adapter: - Payment Service not available. description: 'This API supports the purchase of a subscription plan created 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.' parameters: - $ref: '#/components/parameters/Accept_2' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/x-pch-digest' - schema: type: string default: en in: header name: Accept-Language description: Language parameter - $ref: '#/components/parameters/Authorization' x-stoplight: id: d135642ff639e requestBody: content: application/json: schema: type: object x-examples: example-1: plan_id: 23 start_time: '2021-04-28T13:59:47+05:30' end_time: '2021-05-28T13:59:47+05:30' purchase_price: '23.34' auto_renewal: 'true' properties: client: type: string description: Client key of the business authentication_token: type: string description: 'The authentication token of the user, required if the `HTTP_AUTHORIZATION` header is not added. 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). ' plan_id: type: integer 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: - 23 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-04-28T13:59:47+05:30' 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-04-28T13:59:47+05:30' purchase_price: type: number format: float description: Price at which one unit of the subscription plan is purchased examples: - 23.45 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". payment_card_uuid: type: string description: Unique digital identifier/token of the user's credit card can be referred to as the uuid of the saved payment card, required if a saved payment card is used for payments. The transaction token is issued by a payment processor used by a business. required: - client - authentication_token - plan_id - start_time - end_time - purchase_price - auto_renewal examples: example: value: client: CLIENT_GOES_HERE authentication_token: AUTH_TOKEN_GOES HERE plan_id: 23 start_time: '2023-04-28T13:59:47+05:30' end_time: '2023-04-28T13:59:47+05:30' purchase_price: '23.09' auto_renewal: 'true' payment_card_uuid: PAYMENT_CARD_UUID_GOES_HERE description: '' tags: - Auth servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com /api/auth/subscriptions/cancel: put: summary: Cancel Subscription (Turn off Auto Renewal) operationId: put-api-auth-subscriptions responses: '200': description: OK content: application/json: schema: type: object x-examples: example-1: message: Subscription auto renewal cancelled properties: message: type: string minLength: 1 default: Subscription auto renewal cancelled required: - message examples: example: value: message: Subscription auto renewal cancelled '400': description: 'Bad Request: Sending an invalid/blank cancellation reason ID' content: application/json: schema: type: object x-examples: example-1: errors: client: Required parameter missing or value empty. properties: error: type: string examples: Sending an invalid/blank cancellation reason ID: value: error: 'Required parameter missing or the value is empty: cancellation_reason_id' '401': description: 'Unauthorized: Sending an invalid/empty access or authentication token ' content: application/json: schema: type: object x-examples: example-1: errors: unauthorized: - An active access token must be used to query information about the current user. properties: error: type: string examples: Sending invalid/empty access or authentication token: value: error: You need to sign in or sign up before continuing. '412': description: "Precondition Failed: Sending an invalid/empty client \n\nInvalid Signature means the signature generated at the Punchh Server for the API call does not match the signature generated by the client. See [Generating x-pch-digest Header for Online Ordering APIs](/docs/dev-portal-online-ordering/additional-topics/x-pch-digest-sha-1)" content: application/json: schema: type: array x-examples: example-1: errors: invalid_signature: - Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is items: {} examples: Invalid Signature: value: - Invalid Signature '422': description: Unprocessable Entity content: application/json: schema: 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: error: type: object properties: message: type: array items: type: string examples: - Your current loyalty program configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. code: type: string examples: Cancelling an already renewed subscription: value: error: message: - This subscription is already renewed. You can cancel the newly issued Subscription which will remain valid till its end date. code: cancel_renewed_subscription Subscription feature is not enabled: value: error: message: - Your current loyalty program configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. code: disabled_feature Sending an invalid/blank subscription ID: value: error: message: - Invalid User Subscription. code: invalid_subscription Cancelling an already cancelled Subscription: value: error: message: - Subscription is already canceled. code: already_canceled description: This API allows the end user to cancel an active subscription (turn off auto renewal for the subscription). This is a soft cancellation wherein the benefits remain valid until the end time of the subscription. parameters: - $ref: '#/components/parameters/Accept_2' - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/x-pch-digest' - schema: type: string default: en in: header name: Accept-Language description: Language parameter - $ref: '#/components/parameters/Authorization' x-stoplight: id: 68979e4953b9d requestBody: content: application/json: schema: type: object x-examples: example-1: client: CLIENT_GOES_HERE subscription_id: 26 cancellation_reason: Did not like the service properties: client: type: string description: OAuth client ID provided by the business (per the OAuth app in the Punchh platform) minLength: 1 authentication_token: type: string x-stoplight: id: ihzprqch1t3j7 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). subscription_id: type: integer description: System-generated unique ID of the subscription of the guest that needs to be cancelled examples: - 26 cancellation_feedback: type: string minLength: 1 description: Reason for cancelling the subscription as provided by the end user examples: - No longer needed cancellation_type: type: string 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. enum: - 'hard_cancelled ' - soft_cancelled minLength: 1 examples: - soft_cancelled cancellation_reason_id: type: string description: ID of the chosen cancellation reason. You can get this value from the `subscription_cancellation_reasons` object returned in the response of a successful [Subscription Meta API](/docs/dev-portal-online-ordering/apis/oo-subscription-api/paths/~1api~1auth~1subscription_meta/get) call. required: - client - subscription_id - cancellation_feedback - cancellation_type - cancellation_reason_id examples: example: value: client: CLIENT_GOES_HERE subscription_id: 24 cancellation_feedback: Price too High. cancellation_reason_id: '1' cancellation_type: soft_cancelled tags: - Auth servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com /api/auth/user_subscriptions: get: summary: Fetch Subscription Plans for a User operationId: post-api-auth-user-subscriptions responses: '200': description: OK content: application/json: schema: type: object x-examples: example-1: subscriptions: - subscription_id: 19 start_time: '2021-05-18T21:09:38+05:30' end_time: '2021-06-03T21:09:38+05:30' plan_id: 9 image: test-image.png name: fuel_price description: '' miscellaneous: '' status: Active benefits: - benefit_id: 3 discounts: - discount_id: 7 threshold: 40 discounted_value: 80 discounted_quantity: 40 - discount_id: 8 threshold: 1000 discounted_value: 1000 discounted_quantity: 1000 properties: has_any_subscriptions: type: boolean x-stoplight: id: 0n8ymiyjzstq7 description: 'Indicates whether or not a user''s account currently has an active subscription or has ever had an active subscription. This parameter can be used by developers to customize the app experience as per the needs of the business. Possible values: true, false' subscriptions: type: array uniqueItems: true minItems: 1 description: Array object containing different subscriptions issued to the guest items: type: object properties: subscription_id: type: number description: System-generated unique ID of the subscription that is issued to the guest start_time: type: string minLength: 1 description: Date and time (in ISO 8601 format) from which this current subscription becomes active for a guest end_time: type: string minLength: 1 description: Date and time (in ISO 8601 format) until which this current subscription remains active for a guest plan_id: type: number description: System-generated unique ID of the plan against which this subscription is issued for the guest image: type: string minLength: 1 description: Cover image of a subscription plan uploaded at the time of subscription plan creation cancellation_reason: type: string description: Reason for cancellation as sent to Punchh at the time of cancellation cancelled_at: type: string format: date-time description: Date and time (in ISO 8601 format) when the subscription is cancelled name: type: string minLength: 1 description: 'Name of the subscription plan as provided by the admin at the time of subscription plan creation. Note: The subscription `name` is returned in the language specified in the Accept-Language request header, provided the name has been translated into the relevant language in the Punchh platform. If the translation is not available, then no value is returned for this parameter in the API response. For example, if the header specifies “fr” (French), the subscription name is returned in French only if a French translation for the name is configured in the Punchh platform. ' description: type: string description: 'Text description of the subscription plan as configured by the admin on the subscription plan. This is used to explain the offerings of the subscription plan to guests. Note: The subscription `description` is returned in the language specified in the Accept-Language request header, provided the description has been translated into the relevant language in the Punchh platform. If the translation is not available, then no value is returned for this parameter in the API response. For example, if the header specifies “fr” (French), the subscription description is returned in French only if a French translation for the description is configured in the Punchh platform. ' miscellaneous: type: string description: 'Free-form text field that can be used by businesses to enter additional information or a JSON code snippet for greater customization in the mobile app. Note: The subscription `miscellaneous` information is returned in the language specified in the Accept-Language request header, provided it has been translated into the relevant language in the Punchh platform. If the translation is not available, then no value is returned for this parameter in the API response. For example, if the header specifies “fr” (French), the subscription miscellaneous information is returned in French only if a French translation for the miscellaneous is configured in the Punchh platform. ' status: type: string minLength: 1 description: "Subscriptions issued to a guest can have multiple statuses. Currently supported statuses are:\n1. active: The subscription is active and the guest can enjoy the benefits until its end_time.\n2. expired: The subscription is not renewed and expired. The end_time of the subscription is in the past, and it was not cancelled before its expiration.\n3. soft_cancelled: The subscription is cancelled either by the guest or by an admin. The benefits remain valid until the end_time. \n4. hard_cancelled: The subscription is cancelled by an admin and the benefits become invalid immediately from the time of cancellation.\n5. renewed: The subscription is renewed.\n" benefits: type: array uniqueItems: true minItems: 1 maxItems: 5 description: 'A subscription plan may contain multiple benefits. This object includes the details of benefits available to the guest for this subscription ID. ' items: type: object properties: benefit_id: type: number description: System-generated unique ID of the benefit that is configured on the subscription plan and is issued to the guest for this subscription benefit_name: type: string description: Name of the individual benefit, set in Benefits & Rules (Wallet and Passes > Subscription Plans) in the Punchh platform. Up to 5 benefits per plan. This parameter is returned when enabled for the business. Contact your Punchh representative to update this platform configuration. benefit_description: type: string description: Description of the individual benefit, set in Benefits & Rules (Wallet and Passes > Subscription Plans) in the Punchh platform. This parameter is returned when enabled for the business. Contact your Punchh representative to update this platform configuration. benefit_priority: type: integer description: 'Sets the order in which benefits are applied to a transaction and displayed in the web app within a multi-benefit subscription plan. Lower value = higher priority (starts at 1 and goes up to the number of benefits in the plan). Priority ordering matters when benefits can affect each other''s eligibility — for example, applying a free item first might drop the bill below a threshold needed for a percentage discount. The benefit priority order is locked once the plan becomes visible to customers. Note: This parameter is returned when enabled for the business. Contact your Punchh representative to update this platform configuration.' benefit_type: type: string description: Type of the benefit examples: - sku_discounting discounts: type: array uniqueItems: true minItems: 1 description: A benefit may contain multiple discounts. This object contains the details of different discounts issued to the guest for this subscription. items: type: object properties: discount_id: type: number description: System-generated unique ID of the discounting rule configured under the benefit. occurrence: type: number x-nullable: true description: 'The number of times this discount can be applied. A null value means no specific occurrence limit is set. Note: This parameter is returned when enabled for the business. Contact your Punchh representative to update this platform configuration.' gap_units: type: number x-nullable: true description: 'The number of time units (defined by gap_unit_type) that must elapse between consecutive uses of this discount. A null value means no gap restriction. Note: This parameter is returned when enabled for the business. Contact your Punchh representative to update this platform configuration.' gap_unit_type: type: string description: 'The unit of time for the gap_units value (e.g., "hours"). Defines the cooldown period type between discount usages. Note: This parameter is returned when enabled for the business. Contact your Punchh representative to update this platform configuration.' start_time: type: string format: date-time x-nullable: true description: 'The start date/time from which this discount becomes active. A null value means no specific start time constraint — the discount is available from the subscription''s start. Note: This parameter is returned when enabled for the business. Contact your Punchh representative to update this platform configuration.' end_time: type: string format: date-time x-nullable: true description: 'The end date/time after which this discount expires. A null value means no specific end time constraint — the discount remains valid until the subscription ends. Note: This parameter is returned when enabled for the business. Contact your Punchh representative to update this platform configuration.' threshold: type: number description: 'Maximum number of units that can be discounted for this particular discounting rule. ' threshold_discount: type: number description: 'The maximum discount value that can be applied per use of this discounting rule (e.g., 100.0 means up to 100 units of % or $, depending on discount_type). Note: This parameter is returned when enabled for the business. Contact your Punchh representative to update this platform configuration.' discount_type: type: string description: 'The type of discounting rule configured under the benefit. Common values include "%_or_$_off" (percentage or dollar amount off), "sku_discounting" (item-level discount), "target_price_bundle_advanced" (bundle pricing), and "receipt_level_discount" (order-level discount). Note: This parameter is returned when enabled for the business. Contact your Punchh representative to update this platform configuration.' discounted_value: type: number description: Value of discounts given as per this discounting rule. discounted_quantity: type: number description: Number of units discounted as per this discounting rule. 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. This value can be used to make the purchase of the subscription plan instead of using the “plan_id”. plan_image_url: type: string description: URL of the image that is configured for a specific subscription plan renewed_on: type: string description: Date and time when the subscription was renewed on format: date-time upcoming_renewal: type: string description: Date and time of next renewal of the subscription format: date-time examples: - '2023-05-11T05:00:00+05:30' purchase_price: type: integer description: amount paid for the subscription auto_renewal: type: boolean 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". default: true payment_card: type: object description: The object shows payment card settings properties: uuid: type: string description: Saved payment card UUID nickname: type: string description: Payment card nickname as set by the user preferred: type: boolean description: Whether this card will be selected as the default card or not when the user makes a payment through the mobile app. If the value is set to true, this card will be selected as the default card for payments. card_details: type: object description: The object shows payment card details properties: name_on_card: type: string description: Cardholder name ' card_type': type: string description: Card type like VISA, Mastercard, Amex, etc cc_4: type: string description: Last 4 digits of the card expiry_month: type: string description: Expiry month of the card expiry_year: type: string description: Expiry year of the card cancellation_feedback: type: string description: Subjective feedback that a guest provides when cancelling a subscription from the mobile application, or the feedback that an administrator provides when cancelling a subscription from the Punchh platform. examples: Success: value: has_any_subscriptions: true subscriptions: - subscription_id: 19 start_time: '2023-05-18T21:09:38+05:30' end_time: '2023-06-03T21:09:38+05:30' plan_id: 9 image: test-image.png cancellation_reason: Found better alternative cancelled_at: null name: fuel_price description: '' miscellaneous: '' status: Active external_plan_identifier: EXTERNAL_PLAN_IDENTIFIER_GOES_HERE plan_image_url: PLAN_IMAGE_URL_GOES_HERE renewed_on: '2023-04-10T05:00:00+05:30' upcoming_renewal: '2023-05-11T05:00:00+05:30' purchase_price: 100 auto_renewal: true benefits: - benefit_id: 3 benefit_type: sku_discounting benefit_name: Free Coffee benefit_description: Get a free coffee on your next visit benefit_priority: 1 discounts: - discount_id: 7 occurrence: 5 gap_units: 24 gap_unit_type: hours start_time: '2023-05-18T00:00:00+05:30' end_time: '2023-06-03T23:59:59+05:30' threshold: 40 threshold_discount: 100 discount_type: sku_discounting discounted_value: 80 discounted_quantity: 40 - discount_id: 8 occurrence: null gap_units: null gap_unit_type: hours start_time: null end_time: null threshold: 1000 threshold_discount: 100 discount_type: sku_discounting discounted_value: 1000 discounted_quantity: 1000 - benefit_id: 4 benefit_type: sku_discounting benefit_name: Fuel Discount benefit_description: Get 10% off on fuel purchases benefit_priority: 2 discounts: - discount_id: 7 occurrence: 10 gap_units: null gap_unit_type: hours start_time: null end_time: null threshold: 40 threshold_discount: 50 discount_type: '%_or_$_off' discounted_value: 80 discounted_quantity: 40 - discount_id: 8 occurrence: null gap_units: null gap_unit_type: hours start_time: null end_time: null threshold: 1000 threshold_discount: 100 discount_type: receipt_level_discount discounted_value: 1000 discounted_quantity: 1000 payment_card: uuid: SAVED_CARD_UUID nickname: My card preferred: true card_details: name_on_card: CARDHOLDER_NAME_GOES_HERE cc_4: '1111' card_type: Visa expiry_month: 09 expiry_year: '23' cancellation_feedback: Found better alternative '401': description: 'Unauthorized: Sending an invalid/empty access or authentication token' content: application/json: schema: type: object x-examples: example-1: errors: client: Required parameter missing or the value is empty. properties: error: type: string examples: Sending an invalid/empty access or authentication token: value: error: You need to sign in or sign up before continuing. '412': description: "Precondition Failed: Sending an invalid/empty client \n\nInvalid Signature means the signature generated at the Punchh Server for the API call does not match the signature generated by the client. See [Generating x-pch-digest Header for Online Ordering APIs](/docs/dev-portal-online-ordering/additional-topics/x-pch-digest-sha-1)" content: application/json: schema: type: array x-examples: example-1: errors: invalid_signature: - Signature doesn't match. Please see our documentation https://developers.punchh.com/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is items: {} examples: Sending invalid/empty client: value: - Invalid Signature '422': description: Unprocessable Entity content: application/json: schema: 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: message: type: array items: type: string examples: - Your current loyalty program configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. examples: - Your current loyalty program configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. code: type: string examples: Sending invalid value in the status filter: value: error: message: - Possible values are active, expired, cancelled. code: invalid_status Subscription Feature is not configured: value: error: message: - Your current loyalty program configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. code: disabled_feature description: "This API returns the subscriptions attached to a guest's profile. While the response can be filtered based on \"status\" and \"past_subscriptions\", the default response will include subscriptions that are either \"active\" or \"soft_cancelled\" and have their end time in the future.\n " parameters: - $ref: '#/components/parameters/Accept_2' - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/x-pch-digest' - $ref: '#/components/parameters/Authorization' - schema: type: string in: query name: filter description: '''Filter subscription by status and past_subscriptions.

If the status is not sent, the API returns subscriptions that are `active`, `soft_cancelled`, and have an end_time that is not in the past. Supported "filter” values are ''''active'''', ''''expired'''', and ''''cancelled''''.

When the API call is made using the past_subscriptions filter, the response returns only such subscriptions that have their end date/time in the past. The status against each subscription can have the following possible values: ‘expired’, ‘renewed’, ‘soft_cancelled’, and ‘hard_cancelled’.'' ' - $ref: '#/components/parameters/Content-Type' x-stoplight: id: 649a7bc739ad1 requestBody: content: application/json: schema: type: object properties: client: type: string description: Oauth client ID provided by the business authentication_token: type: string x-stoplight: id: 3uvpozny7zpso 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). required: - client examples: default: value: client: CLIENT_GOES_HERE description: '' tags: - Auth servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com /api/auth/subscription_meta: get: summary: Subscription Meta tags: - Auth responses: '200': description: OK content: application/json: schema: type: object properties: enable_cancellation_feedback: type: boolean description: Whether feedback is to be collected at the time when guests cancel a subscription or not. cancellation_feedback_placeholder: type: string description: This is the cancellation feedback placeholder which can be used by app developers as the title/label/placeholder text while capturing subjective feedback from guests when they cancel a subscription. subscription_cancellation_reasons: $ref: '#/components/schemas/Subscription-Cancellation-Reasons' examples: default: value: enable_cancellation_feedback: false cancellation_feedback_placeholder: Test subscription_cancellation_reasons: - cancellation_reason_id: 1 cancellation_reason: Overvalued for me. component_code: price - cancellation_reason_id: 2 cancellation_reason: Service not up to the mark. component_code: service - cancellation_reason_id: 3 cancellation_reason: Switching to other plan. component_code: other plan '422': description: ' Unprocessable Entity: The feature is turned off for the business.' content: application/json: schema: type: object properties: error: type: object properties: message: type: array items: {} code: type: string examples: Feature is turned off for the business: value: error: message: - Your current loyalty program configuration does not support this feature. Please connect with your Customer Success representative for resolution of the issue. code: disabled_feature operationId: get-api-auth-subscription_meta parameters: - schema: type: string default: application/json in: header description: Advertises which content types the client is able to understand name: Accept required: true - $ref: '#/components/parameters/Accept-Language' - $ref: '#/components/parameters/Content-Type' - schema: type: string in: header description: Signature generated using the request path, body, and OAuth secret provided by the business required: true name: x-pch-digest description: 'Returns subscription cancellation reasons, which are configured in the Punchh platform under Wallet and Passes > Subscription Cancellation Reasons. Note: If the option to enable meta cache update on request is not enabled in the Punchh platform, then the API won''t return any subscription cancellation reasons in the Subscription Meta API response. Contact your Punchh representative to update this configuration.' x-stoplight: id: 0482957e6918f requestBody: content: application/json: schema: type: object properties: ' client': type: string description: OAuth client ID provided by the business required: - ' client' examples: default: value: ' client': CLIENT_GOES_HERE servers: - url: https://SERVER_NAME_GOES_HERE.punchh.com components: schemas: menu_items: type: array title: Menu Items (Array Object) x-stoplight: id: 8e03e64d17406 description: This object used in the API request contains one or more menu items added to an order. See [How To Send Menu Items to Punchh](/docs/dev-portal-online-ordering/5277d762b8c6d-how-to-send-menu-items-to-punchh) 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. ' format: float menu_item_type: type: string description: 'The classification of the item. Choose from the following types based on the item: M - Menu item ( + or - ) S - 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. D - Discount (negative). Either internal or Punchh will always evaluate lines as ( - ) regardless of the sign assigned in the API call. We do not recommend sending any line item types set to D in any Redemptions 1.0 requests. Instead, send them in the [Create Loyalty Check-in](/docs/dev-portal-online-ordering/f1943957e38b4-create-loyalty-check-in) and [Update Loyalty Check-in](/docs/dev-portal-online-ordering/386045cf184bc-update-loyalty-check-in) API calls.

If any items with line item type D are sent in these requests, the business will require additional configuration for all offers to filter out the line item type D. See the [Qualification Criteria](https://support.punchh.com/s/article/Qualification-Criteria) article on the Support Portal. Note: To view the Punchh product documentation on the Punchh Support Portal, you must log in to a Punchh platform production environment. If you already have access to a production environment, follow the instructions [here](https://support.punchh.com/s/article/How-do-I-access-the-Punchh-Support-Portal-Single-Sign-On) to access the Punchh Support Portal.

Any non-loyalty discounts should be reflected in reduced totals of the line items of type M that the discounts apply to. For example, if a business offers a $2 discount on a $10 burger, send the burger as $8 ($10 - $2) in the API request. T - Tax item. Taxes of all sorts P - Payment item. Visa, MasterCard, cash, gift card/certificate (when used to pay for the order) Note: See [Multiple Redemptions Example](/docs/dev-portal-online-ordering/5277d762b8c6d-how-to-send-menu-items-to-punchh#multiple-redemptions-example) for processing multiple discounts.' 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 discount_distribution_items: type: array title: Discount Distribution Items (Array Object) description: 'An array containing details of how the applied discount is distributed across individual menu items. Each object represents one line item that receives a portion of the discount. ' items: type: object properties: item_name: type: string description: Name of the discounted menu item as it displays in the POS catalog menu_item_id: type: string description: Unique identifier that your POS system uses for the discounted menu item item_qty: type: number description: Quantity associated with the discounted item. item_amount: type: number description: A negative amount that indicates a reduction in price. The sum of all `item_amount` values across the array equals the total discount applied. menu_item_type: type: string description: 'The classification of the item. R - Redemption Discount item (negative). The `menu_item_type` attribute will always be set to "R" to indicate that it is a redemption-related discount. If a user redeemed a reward giving $3 off, the response may include a line with `menu_item_type` as "R" and `item_amount` as -3.' menu_major_group: type: string description: The major group that the discounted item belongs to menu_family: type: string description: The family that the discounted item belongs to serial_number: type: number description: A serialized number that differentiates distinct items on the check. The value in the field identifies which items on the check 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. Menu-items: title: Menu Items (Array Object) x-stoplight: id: fk2m3spgtavow type: array description: Returns a list of menu items in the API response items: x-stoplight: id: 39aiodk09xagj type: object properties: item_name: type: string x-stoplight: id: zuuv1bygx021y description: Name of the menu item item_qty: type: integer x-stoplight: id: 131hg1tvuvejg description: Quantity ordered by the customer. If the item is a modifier (such as extra cheese on a pizza base item), 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 x-stoplight: id: i1ib310cm4q9z format: float 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. This value is always represented as a positive number, even when the item is a discount. menu_item_type: type: string x-stoplight: id: pft0otv42wuox description: 'The classification of the item. Choose from the following types based on the item: M - Menu item ( + or - ) S - 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. D - Discount (negative). Either internal or Punchh will always evaluate lines as ( - ) regardless of the sign assigned in the API call T - Tax item. Taxes of all sorts P - Payment item. Visa, MasterCard, cash, gift card/certificate (when used to pay for the order)' menu_item_id: type: string x-stoplight: id: kf0plfkst335o description: Unique identifier for the item menu_family: type: string x-stoplight: id: ioa8b7ctpuek0 description: The family that the item belongs to. The family is the subcategory for the item. A blank value means the item does not belong to a family. menu_major_group: type: string x-stoplight: id: 1gk2qcww5dghn description: The major group that the item belongs to. The major group is the parent category for the item. A blank value means the item does not belong to a major group. serial_number: type: string x-stoplight: id: opx6xr7o23r4i description: A serialized number that differentiates distinct menu items on a receipt. The value identifies 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. discount_details: title: Discount Details (Object) x-stoplight: id: jb42b7k6rcni9 type: object description: List of a discount's defining attributes. In the case of the [Auto Redemption](/docs/dev-portal-online-ordering/d3e1d4293ad65-auto-redemption-redemptions-2-0) and [Get Active Discount Basket](/docs/dev-portal-online-ordering/1d4f01cf7aa32-get-active-discount-basket-redemptions-2-0) APIs, the object returns a null value for invalid discounts. x-examples: Example: - item_id: 777658 name: Flat $5 Off (Unlocks at 100 points) image: IMAGE_URL_GOES_HERE points: 100 base_amount: 5 description: '' item_properties: null meta_detail: null start_date_tz: null end_date_tz: null created_at: '2022-09-08T18:41:16Z' properties: item_id: type: integer x-stoplight: id: 80qo2jvwbm2ty description: Item ID name: type: string x-stoplight: id: egg0ue3bz5ooy description: External discount name.

The `name` value is returned in the language specified in the Accept-Language request header, provided the redeemable name and subscription plan name have been translated into the relevant language in the Punchh platform. If the translation is unavailable, the response returns the value for this parameter in the default English language. For example, if the header specifies “fr” (French), the name is returned in French if a French translation is configured for the name in the Punchh platform; otherwise the value is returned in the default English language. image: type: string x-stoplight: id: uifkndmwtrpl0 description: Image URL of the reward points: type: integer x-stoplight: id: 2h0pv5to7g1zu description: Points associated with the current reward base_amount: type: integer x-stoplight: id: 6utoa8q5q6jgk description: Discounted value description: type: string x-stoplight: id: 77ptihpodzby8 description: Description that explains rewards as configured in the Punchh platform.

The `description` value is returned in the language specified in the Accept-Language request header, provided the descriptions of redeemable and subscription have been translated into the relevant language in the Punchh platform. If the translation is unavailable, the response returns the value for this parameter in the default English language. For example, if the header specifies “fr” (French), the description is returned in French only if a French translation is configured for the description in the Punchh platform; otherwise the value is returned in the default English language. item_properties: type: string x-stoplight: id: fvvz638acsq2n 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. meta_detail: type: string x-stoplight: id: 1mn40oficjohy description: 'Meta information configured for `discount_type` values: redemption_code, subscription, reward, and redeemable. The response returns a value only if the meta data field is configured in the Punchh platform when creating the discount. Currently, the Punchh platform supports multilingual values for `meta_detail` only for coupon redemption.

The `meta_detail` value for the coupon redemption (i.e., when discount_type = redemption_code) is returned in the language specified in the Accept-Language request header, provided the coupon meta data has been translated into the relevant language in the Punchh platform. If the translation is unavailable, the response returns the value for this parameter in the default English language. For example, if the header specifies “fr” (French), the `meta_data` value for a coupon is returned in French only if a French translation is configured for the coupon meta data in the Punchh platform; otherwise the value is returned in the default English language.' start_date_tz: type: string x-stoplight: id: isw2tsm6zr6mk description: Start date of the reward in ISO 8601 format format: date-time end_date_tz: type: string x-stoplight: id: tlmhixyau7uxk description: Expiry date of the reward in ISO 8601 format format: date-time created_at: type: string x-stoplight: id: baxgj83g3j6ou format: date-time description: Date/time when the reward was created, in YYYY-MM-DDThh:mm:ss format auto_select: type: boolean x-stoplight: id: zqd660e52fd5u description: 'Whether the offer is enabled for auto-redemption or not. Possible values: true, false' campaign_name: type: string x-stoplight: id: gq2mm46hfx7vv description: Name of the campaign through which the guest received the offer max_applicable_quantity: type: integer x-stoplight: id: 8a7wbw8b7d76w description: 'The maximum quantity that can be discounted. Note: This parameter is returned for offers related to Price Rollback, Target Price for Bundle, and Target Price for Bundle (Advanced).' discount_basket_items: title: Discount Basket Items (Array Object) x-stoplight: id: 3a95e69093e06 type: array description: List of discounts. In the case of the [Auto Redemption](/docs/dev-portal-online-ordering/d3e1d4293ad65-auto-redemption-redemptions-2-0) and [Get Active Discount Basket](/docs/dev-portal-online-ordering/1d4f01cf7aa32-get-active-discount-basket-redemptions-2-0) APIs, the object lists invalid discounts with a message stating that the discount is invalid. x-examples: Example: - discount_basket_item_id: 4699 discount_type: reward discount_id: 131 discount_value: null created_at: '2024-01-25T10:03:48Z' items: type: object properties: discount_basket_item_id: type: integer description: Unique identifier of selection discount_type: type: string description: Discount type (e.g., reward, redeemable, etc.) discount_id: type: string description: Discount ID discount_value: type: number format: float description: Value of the currency that a user wants to redeem. This value is set for users on the “Points Convert to Currency” loyalty program. The default value is 0 if the user has not selected any amount to redeem or has no currency in the loyalty account. The parameter returns a “null” value for a business that does not support banking of points into currency. created_at: type: string format: date-time description: Date/time when the discount was selected, in YYYY-MM-DDThh:mm:ss format message: type: string x-stoplight: id: 8ho23rz6fjjfq description: Error message for invalid discount. If a discount is found to be honored, expired, perished, or archived, the API returns an error message in the parameter for the discount indicating that the discount is invalid. discount_details: $ref: '#/components/schemas/discount_details' line_items: title: Line Items (Array Object) x-stoplight: id: ij9mvwtn03jof type: array description: List of line items x-examples: Example: - item_name: coffee item_qty: 1 amount: 10 item_type: M item_id: 330 item_family: '10' item_group: gp serial_number: 1 items: type: object properties: item_name: type: string description: Item name item_qty: type: integer description: The input of item quantity which reflects the specified number of items ordered amount: type: number format: float description: Total item amount. In case of multiple quantities, this is the sum total of all item amounts. item_type: type: string description: "M - Menu item ( + or - )\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. In the case of a single scan flow, send a menu item with the service menu item type for the selected tip amount. \n\nNote: We do not recommend sending the following menu item types in this API call. Instead, send them in the [Create Loyalty Check-in](/docs/dev-portal-online-ordering/f1943957e38b4-create-loyalty-check-in) and [Update Loyalty Check-in](/docs/dev-portal-online-ordering/386045cf184bc-update-loyalty-check-in) API calls.\n\nD - Discount (negative). Either internal or Punchh will always evaluate lines as ( - ) regardless of the sign assigned in the API call. We do not recommend sending any line item types set to D in any multiple Redemptions 2.0 requests. If any items with line item type D are sent in these requests, the business will require additional configuration for all offers to filter out the line item type D. See the [Qualification Criteria](https://support.punchh.com/s/article/Qualification-Criteria) article on the Support Portal.

Note: To view the Punchh product documentation on the Punchh Support Portal, you must log in to a Punchh platform production environment. If you already have access to a production environment, follow the instructions [here](https://support.punchh.com/s/article/How-do-I-access-the-Punchh-Support-Portal-Single-Sign-On) to access the Punchh Support Portal.\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)\n\nFor example, if a business offers a $2 discount on a $10 burger, send the burger as $8 ($10 - $2) in the API request. These discounts should be sent as line item type D in the Check-in or Update API call." item_id: type: integer description: Item ID item_family: type: string description: Item family is required if the menu family is categorized for the item. For more information, see [How To Send Menu Items to Punchh](/docs/dev-portal-online-ordering/5277d762b8c6d-how-to-send-menu-items-to-punchh#structure-of-menu-item-data). item_group: type: string description: Item group is required if menu_major_group is categorized for the item. For more information, see [How To Send Menu Items to Punchh](/docs/dev-portal-online-ordering/5277d762b8c6d-how-to-send-menu-items-to-punchh#structure-of-menu-item-data). serial_number: type: number format: float description: Serial numbers are assigned to menu items on a receipt. 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. The numbering explains that particular items are modifiers associated with the main item. required: - item_name - item_qty - amount - item_type - item_id - item_family - item_group - serial_number qualified_items: title: Qualified Items (Array Object) x-stoplight: id: l9prb666730b6 type: array description: List of qualified items x-examples: Example: - item_name: Pizza1 DISCOUNT item_qty: 2 amount: 3.04 item_type: R item_id: 101 item_family: '10' item_group: '999' serial_number: '1.0' items: type: object properties: item_name: type: string description: Menu item name item_qty: type: integer description: The input of item quantity which reflects the specified number of items ordered amount: type: number format: float description: Total item amount. In case of multiple quantities, this is the sum total of all item amounts. item_type: type: string description: "M - Menu item ( + or - )\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. In the case of a single scan flow, send a menu item with the service menu item type for the selected tip amount. \n\nNote: We recommend not sending the following menu item types in this API call. Instead, send them in the [Create Loyalty Check-in](/docs/dev-portal-online-ordering/f1943957e38b4-create-loyalty-check-in) and [Update Loyalty Check-in](/docs/dev-portal-online-ordering/386045cf184bc-update-loyalty-check-in) API calls.\n\nD - Discount (negative). Either internal or Punchh will always evaluate lines as ( - ) regardless of the sign assigned in the API call\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)\n\nFor example, if a business offers a $2 discount on a $10 burger, send the burger as $8 ($10 - $2) in the API request. Send the discount as a line item in the Check-in API call." item_id: type: integer description: Item ID item_family: type: string description: Item family is required if menu_family is categorized for the item. For more information, see [How To Send Menu Items to Punchh](/docs/dev-portal-online-ordering/5277d762b8c6d-how-to-send-menu-items-to-punchh#structure-of-menu-item-data). item_group: type: string description: Item major group. Required if menu_major_group is categorized for the item; else pass it as a blank field in the API request. Generically, every menu item belongs to a family group. A family group is a sub-category of a major group. For more information, see [How To Send Menu Items to Punchh](/docs/dev-portal-online-ordering/5277d762b8c6d-how-to-send-menu-items-to-punchh#structure-of-menu-item-data). serial_number: type: string format: float description: Serial numbers are assigned to menu items on a receipt. 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. The numbering explains that particular items are modifiers associated with the main item. Subscription-Cancellation-Reasons: title: Subscription Cancellation Reasons x-stoplight: id: c28miitm20q4q type: array x-examples: application/json: subscription_cancellation_reasons: - cancellation_reason_id: 1 cancellation_reason: Overvalued for me. component_code: price - cancellation_reason_id: 2 cancellation_reason: Service not up to the mark. component_code: service - cancellation_reason_id: 3 cancellation_reason: Switching to other plan. component_code: other plan description: 'Different cancellation reasons that the business has configured and guests can select from within the mobile app while cancelling a subscription. ' items: type: object properties: component_code: type: string description: This is the business-defined component code. The component code reflects the category of a cancellation reason. This may/may not be shown on the mobile app at the brand’s discretion. cancellation_reason_id: type: integer description: System generated unique ID of the business-defined cancellation reason. cancellation_reason: type: string description: Cancellation reason as configured by the business. 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`. accept_language: schema: type: string default: en in: header name: Accept-Language description: 'Preferred language. Punchh supports multiple languages for the redeemable name, redeemable description, meta data for coupon, subscription plan name, and subscription description in the API response as per the locale specified in the Accept-Language request header. Possible values: es for Spanish, fr for French, fr-ca for French-Canada, en-CY for English-Cyprus, ro for Romania, es-US for Spanish United States, etc.
The locales for a business are configured in the Punchh platform under Administration > Business Profile > Address > Alternate Languages. In the Punchh platform, the admin of a business has to configure in the relevant language(s) 1) the redeemable name and redeemable description when creating/editing a redeemable under Offers > All Redeemables, 2) meta data for coupons when creating/editing a coupon campaign under Campaign Management, and 3) subscription plan name and subscription description when creating/editing a subscription plan under Wallet and Passes > Subscription Plans. ' Accept-Language: schema: type: string default: en name: Accept-Language in: header required: false description: 'Preferred language. Punchh supports multiple languages for the subscription plan `name`, `description`, and `miscellaneous` parameters in the API response as per the locale specified in the Accept-Language request header. Possible values: es for Spanish, fr for French, fr-ca for French-Canada, en-CY for English-Cyprus, ro for Romania, es-US for Spanish United States, etc. The locales for a business are configured in the Punchh platform under Administration > Business Profile > Address > Alternate Languages. Administrators have to configure Name, Description, and Miscellaneous fields in the relevant language(s) on the subscription plan in the Punchh platform under Wallet and Passes > Subscription Plans. If these fields are not configured in Punchh in the language specified in the Accept-Language request header, then the API response will include the subscription plan `name`, `description`, and `miscellaneous` parameters with empty values. ' Content-Type: schema: type: string name: Content-Type in: header required: true description: Set this header to application/json Accept_2: schema: type: string default: application/json name: Accept in: header required: true description: Advertises which content types the client can understand x-pch-digest: schema: type: string name: x-pch-digest in: header required: true description: Signature generated using the request path, body, and OAuth secret provided by the business. For details, see [signature](/docs/dev-portal-mobile/additional-topics/signature-sha256) x-refined-from: - punchh-online-ordering-redemptions-legacy-openapi.yml - punchh-online-ordering-redemptions-v2-openapi.yml - punchh-online-ordering-subscription-openapi.yml x-stoplight: id: bf6eddb435209 x-ext-urls: {}