Orders
Order Webhooks allow you to subscribe to all available order events past checkout.
Once successfully subscribed and integrated, you'll receive POST requests with an order subscription object as the payload. The event payload represents the current state of the order. No deltas are provided for more straightforward event consumption.
Integration Process
Step 1. Subscribe
Contact your ReserveBar representative
Provide them with your URL/Endpoint for order event subscriptions
Requirements:
Must be a secure URL with valid SSL certificate
Must accept POST method HTTPS calls
Note: You will be provided with a client secret to use for HMAC signature checks.
Step 2. Test
Use the test API to send a test webhook with mocked information. Required parameters:
targetUrl: The endpoint where the webhook request will be sentsecret: Key used to sign the request (signature is sent in the header)
Step 3. Receive the Webhook
Event Topics
Webhook notifications are triggered by the following order events:
paid: Order has been successfully paidscheduled: Paid order is scheduledconfirmed: Retailer has received and started processing the orderdelivered: Order is successfully deliveredcanceled: Order is canceled
Important Notes
Webhook requests are sent to the registered API
Failed requests will be retried up to three times maximum
After three failed attempts, no new attempts will be made
Response Requirements
Your endpoint must quickly return a successful status code (2xx)
Return the success response before performing any complex logic
Example: Return 200 before updating your order management system
Step 4. Best Practices
Security
Verify data integrity using the digital signature
Each webhook request includes a base64-encoded X-Liquid-Hmac-256 header
Header is calculated using:
Your app's client secret
The webhook request payload
Handling Missed Events
While webhooks provide real-time order information, delivery is not guaranteed
Failed deliveries will be retried twice (3 total attempts)
Recommendations for handling delivery issues:
Use the Orders API as a backup to fetch transactional order information
Save order information upon receiving the first event
Process complete order data sent with every event (allows recovery from missed events)
Liquid Cloud always sends complete order data with every event, allowing you to process events even if previous ones were missed
Event Processing Best Practices
Save initial order information on first event
Process complete order data with each event
Use Orders API as backup for missed events
Verify payload integrity using HMAC signature
Return success response before complex processing
Implement proper error handling and logging
Consider implementing retry logic on your end
Monitor webhook performance and failures
Maintain proper security protocols
Keep endpoint documentation updated
Order Object Properties
Order:
number
string required Order number
firstName
string required Customer first name
lastName
string required Customer last name
string required Customer email
phone
string Customer phone
birthdate
string Customer birthdate
status
string required Order status. Possible values: placed, paid, scheduled, confirmed, delivered, canceled
gift
boolean required Is order a gift?
createdAt
string required Order creation date
updatedAt
string required Order last update date
amounts
OrderAmounts required Order amounts
shippingAddress
Address required Shipping address
billingAddress
Address required Billing address
deliveryNotes
string Delivery notes
giftDetails
GiftDetails required Gift details present only if order is a gift
marketingOptIn
MarkrtingOptIn required Marketing opt-in info
paymentMethods
PaymentMethod[] required Payment methods used in the order.
shipments
Shipment[] required Shipments within the order
MarketingOptIn:
sms
boolean required Marketing opt-in for sms
boolean required Marketing opt-in for email
OrderAmounts:
tip
number required Tip amount
tax
number required Tax amount
total
number required Order total
serviceFee
number required Service fee
totalDiscounts
number required Total discounts
Address:
address1
string required Address line 1
address2
string Address line 2
city
string required Address city
state
string required Address state
postalCode
string required Address postal code
country
string required Address country
latitude
string Address latitude
GiftDetails:
message
string Gift message
recipient.phone
string Gift recipient phone
recipient.email
string Gift recipient email
recipient.firstName
string Gift recipient first name
recipient.lastName
string Gift recipient last name
PaymentMethod:
type
string required Type of payment method credit_card or gift_card
brand
string Credit card brand. (present if credit_card)
holder
string Credit card holder name. (present if credit_card)
last4
string Credit card last 4 digits. (present if credit_card)
code
string Gift card code (masked). i.e. AZ*8G (present if gift_card)
Shipment:
status
string required Shipment status. paid, scheduled, en_route, delivered, canceled
retailerName
string required Retailer name
customerPlacement
string required standard, back_order or pre_sale
scheduledFor
string Scheduled date for delivery. If the shipment is not scheduled, it's empty.
createdAt
string required Shipment creation date.
updatedAt
string required Shipment last update date.
amounts
ShipmentAmounts required Shipment amounts
deliveryMethod
DeliveryMethod required Delivery method
items
Item[] required Shipment items
ShipmentAmounts:
tax
number required Tax amount
bagFee
number required Bag fee
bottleDeposits
number required Bottle deposits amount
deliveryFee
number required Delivery/Shipping fee
total
number required Total amount
liquidDiscounts
number required Discounts from Liquid
tipShare
number required Order's tip share for this shipment if applicable
subtotal
number required Products subtotal
storeDiscounts
number required Discounts from retailer
DeliveryMethod:
type
string required Delivery method type. on_demand, shipping or pickup
deliveryDetail.deliveryRequestId
string Delivery request id
deliveryDetail.provider
string Delivery provider. i.e. DoorDash, Uber, CartWheel, etc.
pickupDetail.name
string Pickup person's name
pickupDetail.phone
string Pickup person's phone
packages
Package[] Shipped packages. Only present when deliveryMethod type is shipping
Package:
Packages are created only for shipments with shipping delivery method. Packages are created when retailer dispatches a package.
carrier
string Carrier name
trackingUrl
string Tracking URL
trackingNumber
string required Tracking number
status
string Package status.
estimateDeliveryDate
string Estimated delivery date
Items:
id
string required Order Item id
productId
string required Global Identifier for the product
quantity
number required Item quantity
price
number required Item price
amounts.tax
number required Item tax amount
amounts.total
number required Item total amount
amounts.bottleDeposits
number required Item bottle deposits amount
engraving
boolean required Item has engraving?
engravingOptions.line1
string Item engraving message
engravingOptions.line2
string Item engraving message
engravingOptions.line3
string Item engraving message
engravingOptions.line4
string Item engraving message
engravingOptions.image
string Item engraving image URL
variant.name
string required Item variant name
variant.msku
string Item merchant sku
variant.itemSize
string Item variant size
variant.volume
string Item variant volume
engravingLocation
string Product engraving location
Complete Order Schema
Last updated