Widget APIs (REST & JavaScript)

The Bird widget exposes a small JavaScript API on your storefront so you can read what the customer selected, react to changes, and control the widget. It works on the standard Liquid theme install; headless storefronts can use the same API too.

You can paste any snippet below into your browser’s developer console on a page where the widget is loaded.

REST API

For server-side and third-party integrations (mobile apps, other Shopify apps), see the REST API reference: https://picdel.birdchime.com/api-docs

JavaScript API

Everything lives on a single global, window.BirdApp, available once the widget’s SDK loads. It has four members:

• config — bootstrap config (set for you on the Liquid install)
• ready — a promise you await before using the SDK
• sdk — the widget’s SDK instance
• widget — widget controls: hide, remount, isMounted

Await ready to get the SDK, then call anything on it:

const sdk = await window.BirdApp.ready;

Read the customer’s selection

sdk.selections.current returns the current selection, or null if nothing is chosen yet.

const selection = sdk.selections.current;
console.log(selection?.method, selection?.date, selection?.time);

The most useful fields:

To react to changes instead of reading once, use sdk.subscribe() — the callback runs immediately, then on every change, and returns a function to stop listening.

const unsubscribe = sdk.subscribe((state) => {
  console.log(state.selection, state.isComplete);
});

Check whether checkout can proceed

sdk.selections.canCheckout() returns { canProceed, reason }.

const { canProceed, reason } = sdk.selections.canCheckout();

When canProceed is false, reason is one of:

• selection_incomplete
• minimum_order_value_not_met
• cart_ineligible
• schedule_conflict
• not_ready
• saving
• save_failed

Control the widget

The widget mounts itself on the Liquid install. To manage it:

• window.BirdApp.widget.isMounted() — whether the widget is on the page
• window.BirdApp.widget.hide() — hide the mounted widget
• window.BirdApp.widget.remount() — re-render (e.g. after a theme AJAX redraw)

Custom events

The widget dispatches bird:* DOM events — selection changes, checkout attempts, and mount/unmount — that you can listen for:

window.addEventListener('bird:selection:changed', ({ detail }) => {
  console.log(detail.selection);
});

See Listen for Widget State Changes with Custom Events for the full list, payloads, and targets.

Headless / custom storefronts

On a headless storefront the same API applies, with two additions — you mount the widget and feed it the cart yourself:

await window.BirdApp.ready;
const handle = await window.BirdApp.widget.mount(el); // → { destroy(), isMounted() }
window.BirdApp.sdk.setCart(cart);                     // your Storefront cart, as-is

On headless, only bird:selection:changed fires — gate your checkout button with sdk.selections.canCheckout().canProceed. Full setup: Integrating the Bird Widget in a Shopify Headless Storefront.

---

Legacy widget (V1)

The snippets below apply only to the older (V1) widget, which exposes a global called BirdSDK. If your store runs the current widget, use the window.BirdApp API above instead — the BirdSDK global is not available there.

You can run the following in the developer console when the legacy widget is installed in your theme.

Get the current selection made by the customer in the widget

BirdSDK.session.getState('selections')

Whether to show widget or not

BirdSDK.helpers.shouldHideWidget()

Check postal code eligibility

BirdSDK.helpers.checkPostcodeEligibility('V6Z 3C1').then((data) => console.log(data))

Clear data recorded by Bird app for the cart

BirdSDK.helpers.clearCartSelections()

Get the checkout parameters

BirdSDK.helpers.getCheckoutParams()

---

Related Articles

• Listen for Widget State Changes with Custom Events
• Integrating the Bird Widget in a Shopify Headless Storefront
• How to Manually Add the Widget Code to Your Cart Page
• Can I place the date picker on the product page instead of the cart?