Integration contracts

Integration contracts keep app behavior predictable across merchants and vertical presets.

Booking contract

• Theme settings → Booking: choose Hollow Reserve (recommended) or External scheduler.
• Hollow Reserve defaults the base URL to /pages/booking when blank; External requires Booking base URL.
• Preserve service context with the product handle param (default service=product-handle); specialist and location keys are configurable.
• Hollow Reserve also accepts experience=blueprint-slug and staff= for deep links.
• Book CTAs use dual-path handoff: hollow-reserve:open when a Reserve widget is present, otherwise navigate to the booking URL.
• Events: studio-arcana:quiz:complete, hollow-reserve:open / open-ack / booked; studio-arcana:booking:click is analytics-only.
• Use theme tokens (--sa-*) so embedded UI matches merchant branding.

Service and retail pairing contract

• Service products can expose related aftercare through custom.service_pairing.
• Optional custom.pairing_priority on aftercare SKUs controls Top pick vs Also consider on the product page.
• Aftercare products can map back to treatments with custom.treatment_service.
• Cart surfaces should show either retail upsell or treatment CTA, based on cart composition.

Verification contract

• Test in all vertical dev stores.
• Verify no console errors with and without app blocks.
• Verify fallback experiences when metafields are absent.
• Merchant-facing setup for metafields and metaobjects is documented in the Arcanum docs hub (/docs) alongside this developer page.