Skip to main content
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

​
event
string
required
The event type. See the event types table below for valid values.
​
domain
string
required
Your store domain. Example: "yourstore.com"
​
session_id
string
required
A session identifier from your system — typically your checkout ID or order ID.
​
source
string
required
The protocol that initiated the session: "ucp" or "acp".
​
ai_surface
string
The specific AI surface that triggered this event, if known. Examples: "google_ai_mode", "chatgpt", "perplexity".
​
properties
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
​
timestamp
string
ISO 8601 timestamp. Defaults to the current time if omitted.

​
Event types

EventWhen to fire
ai_checkout_initiatedUCP or ACP checkout session created
ai_checkout_completedOrder confirmed and paid
ai_checkout_failedCheckout failed — payment declined or out of stock
ai_product_viewedProduct 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

​
event_id
string
Unique identifier for this logged event.
​
status
string
Confirmation that the event was recorded. Value is always "recorded" on success.
​
session_classified
boolean
Whether Asva was able to classify the session to a specific AI surface.
​
ai_source
string
The AI surface Asva attributed this session to, based on your ai_surface field and its own signal analysis.
​
confidence
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)
})
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

​
domain
string
required
Domain to query. Example: "yourstore.com"
​
start
string
required
Start date in ISO 8601 date format. Example: "2026-03-01"
​
end
string
required
End date in ISO 8601 date format. Example: "2026-04-01"
​
granularity
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

​
domain
string
The domain queried.
​
period
object
The date range of the report, with start and end fields.
​
summary
object
Aggregated metrics for the full period.
​
summary.ai_sessions
integer
Total sessions attributed to an AI surface.
​
summary.ai_checkouts
integer
Total checkout sessions initiated from an AI surface.
​
summary.ai_orders
integer
Total orders completed from an AI surface.
​
summary.ai_revenue_cents
integer
Total revenue from AI-attributed orders, in smallest currency unit.
​
summary.ai_conversion_rate
number
Orders divided by sessions, as a decimal. 0.131 = 13.1%.
​
summary.avg_order_value_cents
integer
Average order value from AI-attributed orders, in smallest currency unit.
​
by_surface
object
Sessions and orders broken down by AI surface. Keys include google_ai_mode, chatgpt, perplexity, and other_ai.
​
daily
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)}%`)