Old 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

1. Contact your ReserveBar representative

2. Provide them with your URL/Endpoint for order event subscriptions

3. 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 sent

• secret: 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 paid

• scheduled: Paid order is scheduled

• confirmed: Retailer has received and started processing the order

• delivered: Order is successfully delivered

• canceled: 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

1. Save initial order information on first event

2. Process complete order data with each event

3. Use Orders API as backup for missed events

4. Verify payload integrity using HMAC signature

5. Return success response before complex processing

6. Implement proper error handling and logging

7. Consider implementing retry logic on your end

8. Monitor webhook performance and failures

9. Maintain proper security protocols

10. Keep endpoint documentation updated

Order Object Properties

Order:

Field	Description
number	string required Order number
firstName	string required Customer first name
lastName	string required Customer last name
email	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:

Field	Description
sms	boolean required Marketing opt-in for sms
email	boolean required Marketing opt-in for email

OrderAmounts:

Field	Description
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:

Field	Description
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:

Field	Description
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:

Field	Description
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:

Field	Description
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:

Field	Description
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:

Field	Description
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.

Field	Description
carrier	string Carrier name
trackingUrl	string Tracking URL
trackingNumber	string required Tracking number
status	string Package status.
estimateDeliveryDate	string Estimated delivery date

Items:

Field	Description
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

{
  "paymentMethods": [
    {
      "type": "string",
      "brand": "string",
      "last4": "string",
      "holder": "string",
      "code": "string"
    }
  ],
  "shipments": [
    {
      "status": "string",
      "retailerName": "string",
      "customerPlacement": "string",
      "scheduledFor": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "amounts": {
        "tax": "number",
        "bagFee": "number",
        "bottleDeposits": "number",
        "deliveryFee": "number",
        "total": "number",
        "liquidDiscounts": "number",
        "tipShare": "number",
        "subtotal": "number",
        "storeDiscounts": "number"
      },
      "deliveryMethod": {
        "type": "string",
        "deliveryDetail": {
          "deliveryRequestId": "string",
          "provider": "string"
        },
        "pickupDetail": {
          "name": "string",
          "phone": "string"
        },
        "packages": [
          {
            "carrier": "string",
            "trackingUrl": "string",
            "trackingNumber": "string",
            "labelUrl": "string",
            "status": "string",
            "estimateDeliveryDate": "string"
          }
        ]
      },
      "items": [
        {
          "id": "string",
          "productId": "string",
          "price": "number",
          "quantity": "number",
          "amounts": {
            "tax": "number",
            "total": "number",
            "bottleDeposits": "number"
          },
          "variant": {
            "name": "string",
            "sku": "string",
            "itemSize": "string",
            "volume": "string"
          },
          "engraving": false,
          "engravingOptions": {
            "line1": "string",
            "line2": "string",
            "line3": "string",
            "line4": "string",
            "image": "string"
          },
          "engravingLocation": "string"
        }
      ]
    }
  ],
  "number": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "phone": "string",
  "birthdate": "1980-01-01",
  "status": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "amounts": {
    "tip": "number",
    "tax": "number",
    "total": "number",
    "serviceFee": "number",
    "totalDiscounts": "number"
  },
  "gift": false,
  "shippingAddress": {
    "address1": "string",
    "address2": "string",
    "city": "string",
    "state": "string",
    "postalCode": "string",
    "country": "string",
    "latitude": "number",
    "longitude": "number"
  },
  "billingAddress": {
    "address1": "string",
    "address2": "string",
    "city": "string",
    "state": "string",
    "postalCode": "string",
    "country": "string"
  },
  "marketingOptIn": {
    "sms": false,
    "email": false
  },
  "deliveryNotes": "string",
  "giftDetails": {
    "message": "string",
    "recipient": {
      "phone": "string",
      "email": "string",
      "firstName": "string",
      "lastName": "string"
    }
  }
}