CoverPort API and SDK are in beta. Endpoints and the embed may change without notice, and sales should be reconciled in the developer portal. Report problems to support@coverport.io.
CargoLabs Docs

Events

What the SDK tells your page, and when.

The SDK surfaces two callbacks. Under the hood they are driven by postMessage events from the hosted flow; if you use the direct iframe path you will handle those messages yourself.

onComplete(sale)

Fires exactly once, when Stripe reports the checkout paid. Certificates are issued shortly after; confirm them server-side before you rely on the sale. Amounts are in cents (amountTotalCents); amountTotal is a deprecated alias with the same cents value, kept for SDK 0.1.x code. Neither is ever sent as 0 when the amount is unknown: it is null. The modal stays open on the confirmation screen; the buyer closes it when they are done, and onClose does not fire afterwards.

coverport.mount('#insure-btn', {
  key: 'pk_live_…',
  onComplete: async (sale) => {
    await fetch('/api/insurance/record', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        purchaseId: sale.purchaseId, // Stripe PaymentIntent id, pi_…
        checkoutSessionId: sale.checkoutSessionId, // cs_…
        amountTotalCents: sale.amountTotalCents, // cents: 12500 is $125.00; null if unknown
        currency: sale.currency,
        testMode: sale.testMode,
        shipmentId: currentShipment.id, // your own correlation id
      }),
    });
  },
});

Client events are a signal, not the source of truth

onComplete runs in the buyer's browser and can be lost if the tab closes, and anyone can call your record endpoint with made-up values. Treat it as a hint to update your UI and to record a correlation id. Before you rely on a sale for billing or fulfilment, confirm it from your server: GET /api/purchases?paymentIntentId=<sale.purchaseId> returns the purchase once its certificates are issued. See Purchases and certificates.

onClose()

Fires when the modal is dismissed without a completed sale. Any of these trigger it:

  • The close button in the corner of the modal
  • A click on the backdrop
  • The Escape key
  • The hosted flow sending a close message (for example, a "No thanks" action inside the flow)
  • handle.destroy() while a modal is open

Use it to resume whatever the buyer was doing, or to log abandonment.

Ordering guarantees

ScenarioCallbacks
Buyer completes purchase, then closes modalonComplete only
Buyer closes modal before payingonClose only
open() called while a modal is showingOld modal is removed silently, no onClose; new modal opens
destroy() on a handle with an open modalonClose (unless a sale had already completed)

On this page