Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Vendor FAQs

Glossary

tmp reservation = temporary reservation attr = attributes

FAQs

Question: How to use "Create Temporary Reservation" API and What is it for?

When customer has selected pax/date/time/packages we create tmp reservation to block inventory. And after customer confirm booking on checkout page, then we create reservation against that tmp reservation.

Question: Where should vendor place their booking ID in the "reference_id" or "tmp_reservation_id"?

vendor place their booking ID on reference_id

Question: How vendor can get "vendor_reservation_id"?

From response of create reservation API.

Question: Which field can vendor check in "Create New Reservation (With Vendor Payment)"?

Its on vendor_reservation_id in create reservation response.

Question: Would it be okay that vendor don't integrate "create tmp reservation" API?

Not possible, since it is mandatory to pass tmp_reservation_id in params of create reservation api.

Question: What's the scenario involving "cancel_modified"?

When reservation is updated, old reservation is canceled with canceled _modified status, and new reservation is created (there will be old_reservation_id attr. too if you get details of that updated reservation). It's more for change date, time if it's available. user can't increase or reducing the number of booking participant.

Question: Are all "package type IDs" fixed values?

yes, it will be fix values from Get All Package Types API

Question: How many package type that HungryHub have, and the ID for it?

Hungryhub have 3 types of packages in production :

  1. All you can eat (id: 1)
  2. Party Pack (id: 2)
  3. Xperience (id: 3) ➝ Xperience is for staycation n activities that bundle with food like golf or bowling or others same ids for testing environment (hh-venus)

Question: If there is one order failed and vendor want to retry API, should we use the "Create New Reservation (With Vendor Payment)" API again, or should we use the "Update Reservation" API?

There is time limit to create reservation within 10 minutes or else hungryhub will cancel temporary reservation. Once reservation is created, then vendor can use update reservation API to update against reservation_id

Question: If the booking fails due to an API error (such as a timeout), can vendor simply retry calling the "Create New Reservation (With Vendor Payment)" API to attempt the booking again for the same order?

Vendor have to call Get Available Time API against a date, to get available inventory for each timeslot against a date. and try create reservation against temp reservation id within the time limit.

Question: The system limits the maximum number of days for inventory data retrieval to 20 days. We would like to know if it is possible to extend it?

Yes, the system currently supports a 20-day retrieval limit per request for optimal performance. You can access additional days by using pagination.

Question: How can vendor use the pagination, can share an example?

you can see example in Get Reviews API params. pass page[number] and page[size] params.

{{base_url}}/api/vendor/v1/reviews.json?restaurant_id=997&page[number]=1&page[size]=20

Question: What should vendor insert on params transaction_id on Create New Reservation (With Vendor Payment) API?

The transaction_id field should be unique and connected to only 1 reservation_id. vendor can put their booking_id.

Question: Will the "booked_seat" field affect the value of "seat_left"? What does "booked_seat" refer to?

if there are 100 seats for 7pm, and there are bookings with total 20 adults, then booked_seat is 20, seat_left

Question: What if vendor have user from different country. Is it possible to use prices in other currencies as well?

No. For amount_cents in the request body we expect you to put it only on THB currency.

Question: Will HungryHub do price matching? Will exchange rate differencesect our reconciliation?

We expect vendor to send the amount_cents in THB and every month our accounting team download the booking report and generate invoice based on it. So the conversion should be done from vendor side and we only stored the amount_cents in THB.

Question: For Xperience and Party Packs products, which are purchased by package, we're unable to allow customers to select *the number of adults/children*. Therefore, can we transmit the adult value based on the number of packages, while setting children as a fixed value of 0?

Currently for Xperience and Party Pack or package type that has pricing type per_pack then you can ignore or make the kids value as 0, bcs we only count the adult number. For example, a party pack package has max pax 2 adult and the customer tried to booking with 6 adult and 2 kids, then the quantity is 6/2 = 3 (they need to buy 3 pax of package) and we ignore the kids value

Question: When customers buy products by packages/sets, we don't ask customers to provide the number of adults or children. We can only put "adult":1(= the number of packages) in the "adult" when they purchase 1 pack. (and we will put 2 in the "adult" when they purchase 2 packs) Will they be any issues if we send API this way?

If like that, you can use the Max PAX Per Pack value as the adult default value for XP or PP packages so your customer don't need to provide the number of adults. For example this package has Max PAX Per Pack 5 adults, so if the customer tried to choose this package then the customer can bring max 5 people for this package. You can see this attribute from "rules[0].per_pack" or "package_info.per_pack" but for this case, we can do it on our backend itself if empty. currently we get number of sets from our manual booking too. see this as example, our ops team don't know number of adults but we just select to the max number of adults allowed for the number of sets selected and put that as number of adults, so we can use the same workaround, see example, we don't get number of adults if it's a set based

Question: So if the package has Max Pax/pack 5 adults, we will get "package_info.per_pack"= 5?

yes, there is only Set quantity field no adult field. So can you just set adult = per pack * set quantity. If per pack is 5 and user choose 2 quantity then adult is 10

Question: In what scenario is "per_pack": null? Does it affect the calculation of total amounts or the number of people?

"per_pack" will null if the package pricing type is not per pack, and it will not affect the calculation of total amount or the number of people

Question: When "kids_price_v2" = null, does it mean there is no kid price?

we have another params "use_kids_price", if this params return "true", it use kids price v2, if its "false" its not using kids price v2

Question: What is the definition of "pay_now" in Get Restaurant All Packages API?

1. prepayment -> fully or partially paid when user booking 2. pay at restaurant -> zero payment when user booking, user will pay when they arrived at restaurant 3. pay now -> it allow user to choose they want to pay at restaurant or pay when they make the booking

Question: When can we expect to view these 2 parameters in APIs?`exclude_postpaid_packages: true/false` & payment_type

you can find those params on this API: 1. Get Restaurant All Packages 2. Get Restaurant Package By ID 3. Get Available Packages

Question: "transac2NE1 Official Lightsticktion_id": What should be placed here?

  • Field Name: transaction_id => String (required)
  • Description: The transaction_id field is used to uniquely identify a payment transaction associated with a reservation. This identifier is utilized within the vendor_payment section of the request body when utilizing the Create New Reservation API.
  • Usage: 1. When to Include: This field should be included in the request body if the vendor (third party) is responsible for handling the payment associated with the reservation. If the vendor is not involved in payment processing, the vendor_payment field can be omitted. 2. Format: The transaction_id should be a string value representing the identifier assigned to the payment transaction by the vendor. It is essential that this identifier accurately corresponds to the payment transaction within the vendor's system. 3. Location: The transaction_id field resides within the vendor_payment section of the request body for the Create New Reservation API. 4. Example:
{"vendor_payment": {"transaction_id": "VENDOR1234567890",// Other vendor_payment fields...},// Other reservation details...}

Copy

Question: Is "amount_cents" the cost price or the selling price?

Field Name: amount_cents => Integer (required) Description: The amount_cents field represents the total payment amount in Thai Baht cents associated with the reservation. This value is utilized within the vendor_payment section of the request body, indicating the total payment made by the vendor. Usage:

  1. When to Include: This field should always be included in the request body when utilizing the Create New Reservation API, specifically within the vendor_payment section. It is required to ensure accurate tracking of the payment amount.
  2. Format: The amount_cents field should be an integer value representing the total payment amount in Thai Baht cents. It is essential to note that 1 Baht is equivalent to 100 cents.
  3. Currency Conversion: If the vendor handles the payment using a currency other than Thai Baht, it is the vendor's responsibility to convert the payment amount to Thai Baht before providing the value for amount_cents. This ensures consistency in currency across systems.
  4. Example:
{"vendor_payment": {"amount_cents": 500000, // Represents 5,000 Thai Baht// Other vendor_payment fields...},// Other reservation details...}

Copy

Question: For "paid_at" timestamp, is it in the Thailand timezone?

Answer: Field Name: paid_at => Timestamp (required) Description: The paid_at field represents the timestamp indicating the time when the payment for the reservation was made by the user on the vendor's side. This timestamp should be in the Thailand timezone (GMT+7). Usage:

  1. When to Include: This field should be included in the request body within the vendor_payment section when utilizing the Create New Reservation API. It is used to specify the exact time of payment.
  2. Format: The paid_at field should be a timestamp in string format following the pattern: "YYYY-MM-DD HH:MM:SS". The timestamp should reflect the local time in the Thailand timezone (GMT+7).
  3. Timezone: It is important to ensure that the paid_at timestamp is provided in the Thailand timezone (GMT+7). This ensures accurate recording of the payment time.
  4. Example:
{"vendor_payment": {"paid_at": "2024-05-07 12:00:00",// Other vendor_payment fields...},// Other reservation details...}

Copy

Question: What shoud we put in "source" and "special_request"?

Answer: Field Name: source => String (required) Description: The source field indicates the origin or source of the reservation. For vendor-initiated reservations, the value for this field is always "vendor_app". Usage:

  1. When to Include: This field should be included in the request body when utilizing the Create New Reservation API. It is required to specify the source of the reservation.
  2. Format: The source field should be a string value representing the origin of the reservation. For vendor-initiated reservations, the value should always be "vendor_app".
  3. Example:
{"source": "vendor_app",// Other reservation details...}

Copy

Field Name: special_request => String (optional) => The value can be anything Description: The special_request field allows customers to provide any special requests or notes related to their reservation. These requests could include special events, allergies, or any other specific requirements. Usage:

  1. When to Include: This field should be included in the request body when utilizing the Create New Reservation API. It is optional and should only be included if the customer has provided any special requests.
  2. Format: The special_request field should be a string value containing any notes or special requests from the customer.
  3. Example:
{"special_request": "Please prepare a birthday cake for the reservation.",// Other reservation details...}

Copy

Question: Can we leave "menu_sections" empty on the Create Reservation API?

Answer: Yes, it can be empty

Question: Can you provide the common error messages returned in case of the scenarios (e.g., order, inventory failure) when a request fails?

You don't have access to this Doc

Question: Create New Reservation: Should we fill in package[].quantity with the total number of pax or the number of packages?

[external] Restaurant Package Display: API to UI Attribute Mapping Guide (https://doc.clickup.com/d/h/8ca1fpw-33036/3e552c1a079c66d/8ca1fpw-37936) Private (https://app.clickup.com/9003122396/docs/8ca1fpw-21682/8ca1fpw-26662)

Question: for "amount_cents": so would you use it for price check in Create New Reservation API? If so, is it compared to rules[].price?

You can use the Calculate Package Price API (https://documenter.getpostman.com/view/27128735/2s93eU2ZKm#023664cf-8b7c-49f0-baf2-e947b544ef3e) to get the total price and no need to count it manually.

Question: Why was the reservation request rejected with the error "Mix and match is not allowed for [Package Name]"

The reservation request was rejected because the request contained multiple packages that are not allowed to be mixed together. To avoid this issue in the future, please check the package details before sending the reservation request. Each package has an attribute called is_allow_mix, which indicates whether the package can be mixed with others.

  • If is_allow_mix is set to false, you should not include any other package in the same reservation request.
  • If is_allow_mix is set to true, then the package can be mixed with others.

You can retrieve the is_allow_mix attribute from the following API responses: