Fulfillment & errors

Fulfillment & reconciliation

Fulfill and reconcile through LedgerBee webhooks, not the client redirect or the checkoutConfirmed browser event. The bound subscription fires subscription.started / subscription.assigned (and every later subscription webhook) carrying partnerReferenceId — the clientReferenceId you passed at provision — so you can match our subscription to your order. Subscribe to those topics and key your fulfillment on partnerReferenceId. See Webhooks for registering an endpoint, verifying the Standard-Webhooks signature, and the delivery-envelope shape.

Recover a missed webhook. If a delivery is lost (your endpoint was down, you never subscribed yet, a backfill), resolve our subscription from your own order id over the public API: GET /v1/subscriptions?partnerReferenceId=<your clientReferenceId>. The subscription read responses now carry partnerReferenceId, and the list accepts it as a filter — so the join key is reachable without replaying the webhook. (Requires the subscriptions-read scope; see the list-subscriptions operation.)

Anonymous purchases and in-portal changes. A purely anonymous (magic-link) purchase still fires the same subscription webhooks, but with partnerReferenceId: null — you get the customerId and the stable subscriptionId, not your own order id. To tie a purchase back to your record, pass a clientReferenceId when you mint the token — either bound or vouched. A vouched checkout also echoes it on the customer-created webhook (see event types), so a customer created at confirm carries your order id from the moment it exists. An upgrade or downgrade the buyer makes inside the portal arrives as a structural-change subscription webhook (transitionType: plan_replaced) on that same stable subscriptionId — see the event types — so you follow one subscription across plan changes.

The ledgerbee:embed:checkoutConfirmed browser event AND the returnUrl redirect are UX-only — use them to remove the iframe, show a thank-you, or hand the buyer back to your app, never as a fulfillment trigger. The webhook is the source of truth. Three reasons:

• The browser event can be lost. A browser that closes mid-redirect drops it, and nothing replays it.
• ?checkout=pending means "inbox sent", not "subscribed". An anonymous checkout has only mailed a magic link at that point; the subscription does not exist until the buyer clicks it.
• ?subscriptionId= arrives only on CONFIRMED. For an anonymous buyer that is a later, separate call to your page, after they verify — see when your page is called for which rails call you once and which call you twice.

Errors & failure states

Operator prerequisites (configured in LedgerBee → Settings → Portal → Embedding)

• The plan has a public vanity URL and is published + allowed by a routing rule.
• Your site's origin(s) are on the tenant's partner-origin allowlist. This drives the frame-ancestors policy; the embed refuses to frame on an un-allowlisted origin. Allowlisting is the only LedgerBee setup on your side. Loading the iframe and exchanging postMessage events with it are not governed by CORS, and the checkout's own requests run from inside the frame to the portal API, whose policy already permits the portal origin — nothing there needs configuring by you. Requests your own page makes directly, such as the fetchBindToken provider calling your backend, follow ordinary CORS rules and are yours to configure. A development server may be allowlisted over plain http, for the hosts localhost, 127.0.0.1, and [::1] only.
• "Allow in-frame checkout" is on if you want target=inline or any item-pinned checkout.