> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.id.me/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.id.me/_mcp/server.

# Conversion Reporting

> Attribute completed orders back to IDMe verification events using the button widget and conversion tracking SDK.

Conversion reporting lets you attribute completed orders back to IDMe verification events. When enabled, the button widget mints a unique identifier when the button is rendered (or clicked, for popup flows), passes it through the verification flow as `conversion_tracking_id`, and stores it in a first-party cookie so you can include it with conversion events on your order confirmation page.

#### Enable tracking on the button

Add `data-conversion-tracking="true"` to your button widget:

**`Example`**

```html Example
<span
  id="idme-wallet-button"
  data-scope="military,responder,student,teacher"
  data-client-id="[YOUR_CLIENT_ID]"
  data-redirect="[YOUR_REDIRECT_URI]"
  data-response="code"
  data-display="popup"
  data-conversion-tracking="true">
</span>
<script src="https://s3.amazonaws.com/idme/developer/idme-buttons/assets-v2/js/idme-wallet-button.js"></script>
```

**Consent gating.** If you need to defer tracking until the user has accepted cookies, set `data-conversion-tracking` to the name of a global function that returns a boolean. The widget calls it at bind time and fails closed (no tracking) if the function is missing, throws, or returns anything other than `true`.

**`Consent-gated example`**

```html Consent-gated example
<span
  id="idme-wallet-button"
  ...
  data-conversion-tracking="hasMarketingConsent">
</span>
<script>
  window.hasMarketingConsent = function () {
    return window.MyCmp && window.MyCmp.consent("marketing") === true;
  };
</script>
```

#### Send conversion events

On your order confirmation or thank-you page, include the conversion reporting SDK and call `idmeConversion.track()`:

```html
<script
  src="https://s3.amazonaws.com/idme/developer/idme-buttons/assets-v2/js/idme-conversion-tracking.js"
  data-app-id="[YOUR_APP_ID]">
</script>
<script>
  idmeConversion.track("Order Completed", {
    orderId: "ORD-123",
    total: 149.99,
    revenue: 139.99,
    currency: "USD",
    products: [
      { sku: "SKU-001", name: "Widget", price: 49.99, quantity: 3 }
    ]
  });
</script>
```

The SDK reads the `idme_ctid` cookie that was set when the user clicked the button, attaches it to the event as `conversionTrackingId`, and posts the envelope to IDMe. If no cookie is present (e.g., the user did not arrive via a tracked IDMe button), the call is a safe no-op.

> **Best practice**
>
> Only include `idme-conversion-tracking.js` on confirmation/thank-you pages. The button widget handles cookie creation on pages where the button itself is rendered.

## Event shape

The SDK wraps your call in an envelope that matches the `Order Completed` v1 schema. You only supply the event name and `properties`; the SDK fills in `eventId`, `timestamp`, `context`, and the conversion ID.

| Field                                    | Required | Notes                                                                                                                |
| ---------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `event`                                  | Yes      | Must be `"Order Completed"`.                                                                                         |
| `properties.orderId`                     | Yes      | Stable across retries so downstream systems can dedupe.                                                              |
| `properties.total`                       | No       | Order total **including** shipping and tax (after discount).                                                         |
| `properties.revenue`                     | No       | Order revenue **excluding** shipping and tax. Typically the conversion value used by analytics.                      |
| `properties.shipping`, `tax`, `discount` | No       | Numbers.                                                                                                             |
| `properties.currency`                    | No       | ISO 4217 three-letter code (e.g., `USD`, `EUR`). Uppercase.                                                          |
| `properties.coupon`, `affiliation`       | No       | Strings.                                                                                                             |
| `properties.products`                    | No       | Array of line items. Common fields: `productId`, `sku`, `name`, `brand`, `category`, `variant`, `price`, `quantity`. |

Additional properties are accepted and forwarded.