Attribution Events API: POST /api/report Reference

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.

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

string

required

The event type. See the event types table below for valid values.

string

required

Your store domain. Example: "yourstore.com"

string

required

A session identifier from your system — typically your checkout ID or order ID.

string

required

The protocol that initiated the session: "ucp" or "acp".

string

The specific AI surface that triggered this event, if known. Examples: "google_ai_mode", "chatgpt", "perplexity".

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

string

ISO 8601 timestamp. Defaults to the current time if omitted.

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:

{
  "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

string

Unique identifier for this logged event.

string

Confirmation that the event was recorded. Value is always "recorded" on success.

boolean

Whether Asva was able to classify the session to a specific AI surface.

string

The AI surface Asva attributed this session to, based on your ai_surface field and its own signal analysis.

number

Attribution confidence score from 0 to 1. Values above 0.8 are high-confidence classifications.

Example response:

{
  "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:

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)
})

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()

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.

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

string

required

Domain to query. Example: "yourstore.com"

string

required

Start date in ISO 8601 date format. Example: "2026-03-01"

string

required

End date in ISO 8601 date format. Example: "2026-04-01"

string

Time granularity for the daily array: "day" (default), "week", or "month".

Example request:

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

Response fields

string

The domain queried.

object

The date range of the report, with start and end fields.

object

Aggregated metrics for the full period.

integer

Total sessions attributed to an AI surface.

integer

Total checkout sessions initiated from an AI surface.

integer

Total orders completed from an AI surface.

integer

Total revenue from AI-attributed orders, in smallest currency unit.

number

Orders divided by sessions, as a decimal. 0.131 = 13.1%.

integer

Average order value from AI-attributed orders, in smallest currency unit.

object

Sessions and orders broken down by AI surface. Keys include google_ai_mode, chatgpt, perplexity, and other_ai.

array

Day-by-day (or week/month) breakdown with date, sessions, checkouts, orders, and revenue_cents per period.

Example response:

{
  "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

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)}%`)

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}")

Dark Traffic Detection — how Asva identifies AI sessions
GA4 Integration — connect attribution data to your GA4 reports
Attribution Model — how confidence scoring works

​Log an attribution event

​Request parameters

​Event types

​Response fields

​Integration examples

​Pull attribution data

​Query parameters

​Response fields

​Code examples

​Related

Log an attribution event

Request parameters

Event types

Response fields

Integration examples

Pull attribution data

Query parameters

Response fields

Code examples

Related