Embedding the eligibility widget

Ratify's buyer-eligibility widget is a drop-in script for your storefront. It renders a small "Can I have this shipped?" card — ship-to state, order volume, a required 21+ attestation — and answers with a citation-backed shipping verdict from the Ratify API. The bundle is dependency-free vanilla JavaScript served from embed.getratify.ai/widget.js, so it works without a framework: anywhere you can add a script tag and a placeholder div. Supported browsers: the last two versions of Chrome, Safari, Firefox, and Edge; iOS Safari 16+; Android Chrome 110+.

Before you install

You need two things, and today both go through support:

1. Your tenant public key — the multi-line PEM issued when your account is provisioned. If you don't have it, email support@getratify.ai.
2. Origin provisioning — your site's origin(s) added to your tenant's allowlist. The embed surface is closed by default; see "Allow your site's origin" below.

Install

Paste the snippet where you want the widget to render. Keep the PEM exactly as issued — the multi-line form is correct, and the widget normalizes it before calling the API.

<script
  src="https://embed.getratify.ai/widget.js"
  data-pub-key="-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEA...your tenant pub-key PEM here...
-----END PUBLIC KEY-----"
  data-ship-from="NY"
  data-api-base-url="https://api.getratify.ai"
  data-product-type="wine"
  defer
></script>
<div id="ratify-eligibility-check"></div>

Attributes:

• data-pub-key (required) — your tenant public key PEM, pasted as issued. The key is public by design, so it is safe to ship in your page source.
• data-ship-from (required) — the two-letter code of the state your orders ship from. The widget does not render without it.
• data-api-base-url (optional) — defaults to https://api.getratify.ai.
• data-product-type (optional) — defaults to wine.
• data-container (optional) — CSS selector for the mount point; defaults to #ratify-eligibility-check.

Allow your site's origin

Ratify keeps a per-tenant allowlist of the exact origins that may call the buyer API from a browser, and it is closed by default: until your origins are provisioned, the API refuses widget requests from your site. Provisioning is currently an operator step handled by the Ratify team — email support@getratify.ai with the origins to allow. There is no self-serve surface for this today.

Send the exact browser origin of every page that will host the widget, in the form scheme://host — no path, no trailing slash:

• https://winery.com and https://www.winery.com are different origins; include both if you are not sure which one browsers land on.
• Each subdomain is its own origin (for example a separate https://shop.winery.com checkout). Wildcards are not supported.
• http:// and https:// are different origins.
• Include a staging origin if you want to test there first.

What the widget shows

The card renders a ship-to state dropdown, a volume slider, and a 21+ age-attestation checkbox; the check button stays disabled until the buyer attests. On submit the widget calls the eligibility API and renders one of three verdicts:

• Permitted — "Shipping to … is permitted." When the destination requires it, an adult-signature note is added: "Adult signature (21+, photo ID) required at delivery."
• Not permitted — "Shipping to … is not permitted," with a remediation note when one is available.
• Incomplete rule data — when Ratify cannot serve a verdict at full confidence, the widget says so ("Rule data for … is incomplete — please contact the winery to confirm") instead of guessing.

Every verdict carries its citation: the publisher, the last-verified date, a quote preview, and a link to the archived statute snapshot when one exists. After a permitted verdict the buyer can also open a cart preview ("Preview tax + cart for this delivery"), which shows an estimated tax figure with its own citations.

The advisory line

Every result the widget renders — eligibility verdicts and cart previews alike — closes with the same advisory line:

"Compliance intelligence, not legal advice. Verify the cited sources before acting."

The line is compiled into the widget itself and always renders; it is not configurable and cannot be removed or reworded by an API response.

Support

Email support@getratify.ai for your public key, origin provisioning, or install help — see /support for response times. If the widget renders but every check fails, the most common cause is an unprovisioned or mismatched origin: confirm that the exact origin in your browser's address bar is on your allowlist.