> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asva-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Attribution Events API: POST /api/report Reference

> Log AI commerce attribution events server-side and pull session, checkout, and revenue data by domain, date range, and AI surface.

The Attribution API serves two purposes: logging events from your server-side checkout handlers (highest-confidence attribution, because you know the session was AI-initiated), and pulling AI commerce metrics for your domain programmatically. Together these two capabilities give you a complete picture of which AI surfaces are driving discovery, checkout, and revenue — without depending solely on browser-side signals that can be blocked or misclassified. All calls require authentication — see [Authentication](/api-reference/authentication).

***

## Log an attribution event

```
POST https://asva-ai.com/api/report
```

Call this from your server when a UCP or ACP checkout is initiated or completed. Fire it asynchronously — attribution logging must never block or delay the customer's checkout response.

### Request parameters

<ParamField body="event" type="string" required>
  The event type. See the event types table below for valid values.
</ParamField>

<ParamField body="domain" type="string" required>
  Your store domain. Example: `"yourstore.com"`
</ParamField>

<ParamField body="session_id" type="string" required>
  A session identifier from your system — typically your checkout ID or order ID.
</ParamField>

<ParamField body="source" type="string" required>
  The protocol that initiated the session: `"ucp"` or `"acp"`.
</ParamField>

<ParamField body="ai_surface" type="string">
  The specific AI surface that triggered this event, if known. Examples: `"google_ai_mode"`, `"chatgpt"`, `"perplexity"`.
</ParamField>

<ParamField body="properties" type="object">
  Additional event data. Common fields:

  * `product_id` — the product involved
  * `variant_id` — the specific variant selected
  * `value` — order value in smallest currency unit (cents or paise)
  * `currency` — ISO 4217 currency code
</ParamField>

<ParamField body="timestamp" type="string">
  ISO 8601 timestamp. Defaults to the current time if omitted.
</ParamField>

### Event types

| Event                   | When to fire                                                |
| ----------------------- | ----------------------------------------------------------- |
| `ai_checkout_initiated` | UCP or ACP checkout session created                         |
| `ai_checkout_completed` | Order confirmed and paid                                    |
| `ai_checkout_failed`    | Checkout failed — payment declined or out of stock          |
| `ai_product_viewed`     | Product viewed via AI surface (when detectable server-side) |

**Example request:**

```json theme={null}
{
  "event": "ai_checkout_initiated",
  "domain": "yourstore.com",
  "session_id": "sess_xyz123",
  "source": "ucp",
  "ai_surface": "google_ai_mode",
  "properties": {
    "product_id": "prod_123",
    "variant_id": "var_123_10_black",
    "value": 12999,
    "currency": "USD"
  },
  "timestamp": "2026-04-10T11:05:00Z"
}
```

### Response fields

<ResponseField name="event_id" type="string">
  Unique identifier for this logged event.
</ResponseField>

<ResponseField name="status" type="string">
  Confirmation that the event was recorded. Value is always `"recorded"` on success.
</ResponseField>

<ResponseField name="session_classified" type="boolean">
  Whether Asva was able to classify the session to a specific AI surface.
</ResponseField>

<ResponseField name="ai_source" type="string">
  The AI surface Asva attributed this session to, based on your `ai_surface` field and its own signal analysis.
</ResponseField>

<ResponseField name="confidence" type="number">
  Attribution confidence score from 0 to 1. Values above 0.8 are high-confidence classifications.
</ResponseField>

**Example response:**

```json theme={null}
{
  "event_id": "evt_abc123",
  "status": "recorded",
  "session_classified": true,
  "ai_source": "google_ai_mode",
  "confidence": 0.95
}
```

### Integration examples

Add attribution logging to your UCP and ACP checkout handlers. Always fire asynchronously — do not `await` the Asva call:

<CodeGroup>
  ```javascript Node.js theme={null}
  app.post('/ucp/checkout', async (req, res) => {
    const checkout = await createCheckout(req.body)

    // Log to Asva (fire and forget — don't await)
    fetch('https://asva-ai.com/api/report', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.ASVA_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        event: 'ai_checkout_initiated',
        domain: 'yourstore.com',
        session_id: checkout.id,
        source: 'ucp',
        properties: {
          value: checkout.total_cents,
          currency: checkout.currency
        }
      })
    }).catch(console.error) // swallow errors; don't block checkout

    res.json(checkout)
  })
  ```

  ```python Python theme={null}
  import requests
  import threading

  def log_attribution(checkout):
      try:
          requests.post(
              'https://asva-ai.com/api/report',
              headers={'Authorization': f'Bearer {ASVA_API_KEY}'},
              json={
                  'event': 'ai_checkout_initiated',
                  'domain': 'yourstore.com',
                  'session_id': checkout['id'],
                  'source': 'ucp',
                  'properties': {
                      'value': checkout['total_cents'],
                      'currency': checkout['currency']
                  }
              },
              timeout=2  # don't block the main request
          )
      except Exception:
          pass  # attribution failure should never block checkout

  # In your checkout handler:
  threading.Thread(target=log_attribution, args=(checkout,)).start()
  ```
</CodeGroup>

<Warning>
  Never `await` the attribution API call inside a checkout handler. If the Asva API is slow or unavailable, your customers' checkouts must not be affected.
</Warning>

***

## Pull attribution data

```
GET https://asva-ai.com/api/report
```

Retrieve AI commerce metrics for a domain. Use this to build reporting dashboards, pull data into BI tools, or run multi-client reports for agencies.

### Query parameters

<ParamField query="domain" type="string" required>
  Domain to query. Example: `"yourstore.com"`
</ParamField>

<ParamField query="start" type="string" required>
  Start date in ISO 8601 date format. Example: `"2026-03-01"`
</ParamField>

<ParamField query="end" type="string" required>
  End date in ISO 8601 date format. Example: `"2026-04-01"`
</ParamField>

<ParamField query="granularity" type="string">
  Time granularity for the `daily` array: `"day"` (default), `"week"`, or `"month"`.
</ParamField>

**Example request:**

```
GET https://asva-ai.com/api/report?domain=yourstore.com&start=2026-03-01&end=2026-04-01&granularity=day
```

### Response fields

<ResponseField name="domain" type="string">
  The domain queried.
</ResponseField>

<ResponseField name="period" type="object">
  The date range of the report, with `start` and `end` fields.
</ResponseField>

<ResponseField name="summary" type="object">
  Aggregated metrics for the full period.

  <ResponseField name="summary.ai_sessions" type="integer">
    Total sessions attributed to an AI surface.
  </ResponseField>

  <ResponseField name="summary.ai_checkouts" type="integer">
    Total checkout sessions initiated from an AI surface.
  </ResponseField>

  <ResponseField name="summary.ai_orders" type="integer">
    Total orders completed from an AI surface.
  </ResponseField>

  <ResponseField name="summary.ai_revenue_cents" type="integer">
    Total revenue from AI-attributed orders, in smallest currency unit.
  </ResponseField>

  <ResponseField name="summary.ai_conversion_rate" type="number">
    Orders divided by sessions, as a decimal. `0.131` = 13.1%.
  </ResponseField>

  <ResponseField name="summary.avg_order_value_cents" type="integer">
    Average order value from AI-attributed orders, in smallest currency unit.
  </ResponseField>
</ResponseField>

<ResponseField name="by_surface" type="object">
  Sessions and orders broken down by AI surface. Keys include `google_ai_mode`, `chatgpt`, `perplexity`, and `other_ai`.
</ResponseField>

<ResponseField name="daily" type="array">
  Day-by-day (or week/month) breakdown with `date`, `sessions`, `checkouts`, `orders`, and `revenue_cents` per period.
</ResponseField>

**Example response:**

```json theme={null}
{
  "domain": "yourstore.com",
  "period": {
    "start": "2026-03-01",
    "end": "2026-04-01"
  },
  "summary": {
    "ai_sessions": 1842,
    "ai_checkouts": 293,
    "ai_orders": 241,
    "ai_revenue_cents": 3124599,
    "ai_conversion_rate": 0.131,
    "avg_order_value_cents": 12966
  },
  "by_surface": {
    "google_ai_mode": { "sessions": 1102, "orders": 149 },
    "chatgpt": { "sessions": 487, "orders": 67 },
    "perplexity": { "sessions": 201, "orders": 18 },
    "other_ai": { "sessions": 52, "orders": 7 }
  },
  "daily": [
    {
      "date": "2026-03-01",
      "sessions": 61,
      "checkouts": 9,
      "orders": 8,
      "revenue_cents": 103932
    }
  ]
}
```

### Code examples

<CodeGroup>
  ```typescript TypeScript theme={null}
  const params = new URLSearchParams({
    domain: 'yourstore.com',
    start: '2026-03-01',
    end: '2026-04-01',
    granularity: 'day'
  })

  const data = await fetch(`https://asva-ai.com/api/report?${params}`, {
    headers: { Authorization: `Bearer ${process.env.ASVA_API_KEY}` }
  }).then(r => r.json())

  console.log(`AI Revenue: $${(data.summary.ai_revenue_cents / 100).toFixed(2)}`)
  console.log(`AI Conversion Rate: ${(data.summary.ai_conversion_rate * 100).toFixed(1)}%`)
  ```

  ```python Python theme={null}
  import requests

  r = requests.get(
      'https://asva-ai.com/api/report',
      headers={'Authorization': f'Bearer {ASVA_API_KEY}'},
      params={
          'domain': 'yourstore.com',
          'start': '2026-03-01',
          'end': '2026-04-01',
          'granularity': 'day'
      }
  )
  data = r.json()
  print(f"AI Revenue: ${data['summary']['ai_revenue_cents'] / 100:.2f}")
  ```
</CodeGroup>

***

## Related

* [Dark Traffic Detection](/attribution/dark-traffic) — how Asva identifies AI sessions
* [GA4 Integration](/attribution/ga4-integration) — connect attribution data to your GA4 reports
* [Attribution Model](/attribution/model) — how confidence scoring works