Revenue

Related events: order.attributed

Endpoints

GET/v1/brands/{brand}/attribution
GET/v1/brands/{brand}/correlation
GET/v1/brands/{brand}/subscriptions
GET/v1/brands/{brand}/traffic
GET/v1/brands/{brand}/orders

The Attribution object

Attributes

objectstring
attribution
brandstring
The brand the object belongs to (br_…).
marketstring
Market code (ISO country, e.g. FR).
periodstring
currencystringnullable
fromstringnullable
tostring
aiobjectnullable
Show child attributes
- ordersstring
- revenuestring
- average_basketstring
- share_of_revenuestring
- share_of_ordersstring
- previous_ordersstring
- previous_revenuestring
- revenue_changestring
storeobjectnullable
Show child attributes
- ordersstring
- revenuestring
- average_basketstring
surfacesarray of object
productsarray of object
first_touchobjectnullable
Orders the Skoup pixel joined to their visit: the buyer's first AI contact.
Show child attributes
- window_daysstring
- ordersstring
- ai_ordersstring
- ai_sharestring
- ai_revenuestring
- surfacesarray of object
livemodeboolean
true for live data, false for the test-mode sandbox.

The Attribution object


{
  "object": "attribution",
  "brand": "br_034CyfRFSXUqzrbzV6MAfZ",
  "market": "FR",
  "period": "90d",
  "currency": "EUR",
  "from": "string",
  "to": "string",
  "ai": {
    "orders": "string",
    "revenue": "string",
    "average_basket": "string",
    "share_of_revenue": "string",
    "share_of_orders": "string",
    "previous_orders": "string",
    "previous_revenue": "string",
    "revenue_change": "string"
  },
  "store": {
    "orders": "string",
    "revenue": "string",
    "average_basket": "string"
  },
  "surfaces": [
    {}
  ],
  "products": [
    {}
  ],
  "first_touch": {
    "window_days": "string",
    "orders": "string",
    "ai_orders": "string",
    "ai_share": "string",
    "ai_revenue": "string",
    "surfaces": [
      {}
    ]
  },
  "livemode": true
}

The Order object

Attributes

idstring
Unique identifier of the object (prefixed, opaque).
objectstring
order
sourceenum
The store an order was received from. Shopify today (orders/create webhook); WooCommerce / PrestaShop land here with their plugins.
Possible values: shopify
order_numberstringnullable
ordered_atstring
currencystring
subtotalstringnullable
totalstring
items_countinteger
countrystringnullable
ai_surfacestringnullable
Key of the AI surface the order is attributed to (chatgpt, claude, gemini, perplexity…), null = not attributed.
attribution_signalenumnullable
Which of the store's origin fields proved the AI surface of an order. NULL on the order = no AI signal (the referrer host is still kept). | | |---| | referrer <br/> The session's referrer is an assistant's domain. | | utm <br/> The landing URL carries a utm_source naming an assistant (ChatGPT tags its links). | | landing_ref <br/> Shopify's landing_site_ref (?ref=) names an assistant. |
Possible values: referrer · utm · landing_ref
referrer_hoststringnullable
landing_pathstringnullable
landing_productstringnullable
utm_sourcestringnullable
utm_mediumstringnullable
utm_campaignstringnullable
linesarray of object
Show child attributes
- productstringnullable
  Null when the line matches no product of the catalogue.
- titlestring
- skustringnullable
- quantityinteger
- unit_pricestringnullable
- totalstring
livemodeboolean
true for live data, false for the test-mode sandbox.
createdinteger
Time at which the object was created (unix timestamp, seconds).

The Order object


{
  "id": "ord_031DIivuBKog78mwjgnaYz",
  "object": "order",
  "source": "shopify",
  "order_number": "#1042",
  "ordered_at": "2026-09-23T09:12:44Z",
  "currency": "EUR",
  "subtotal": "2399.00",
  "total": "2399.00",
  "items_count": 1,
  "country": "FR",
  "ai_surface": "chatgpt",
  "attribution_signal": "referrer",
  "referrer_host": "chatgpt.com",
  "landing_path": "/products/strade-7",
  "landing_product": "prod_031DIivuBKog78mwjgnbd3",
  "utm_source": null,
  "utm_medium": null,
  "utm_campaign": null,
  "lines": [
    {
      "product": "prod_031DIivuBKog78mwjgnbd3",
      "title": "Strade 7",
      "sku": "STR7-M",
      "quantity": 1,
      "unit_price": "2399.00",
      "total": "2399.00"
    }
  ],
  "livemode": true,
  "created": 1790154764
}

The Visibility revenue correlation object

Attributes

objectstring
visibility_revenue_correlation
brandstring
The brand the object belongs to (br_…).
marketstring
Market code (ISO country, e.g. FR).
periodstring
categorystring
currencystringnullable
categoriesarray of object
weeksarray of object
fixesarray of object
livemodeboolean
true for live data, false for the test-mode sandbox.

The Visibility revenue correlation object


{
  "object": "visibility_revenue_correlation",
  "brand": "br_034CyfRFSXUqzrbzV6MAfZ",
  "market": "FR",
  "period": "90d",
  "category": "string",
  "currency": "EUR",
  "categories": [
    {}
  ],
  "weeks": [
    {}
  ],
  "fixes": [
    {}
  ],
  "livemode": true
}

The Ai subscriptions object

Attributes

objectstring
ai_subscriptions
brandstring
The brand the object belongs to (br_…).
marketstring
Market code (ISO country, e.g. FR).
periodstring
fromstringnullable
tostringnullable
last_synced_atstring
currencystring
newobjectnullable
Show child attributes
- subscriptionsstring
- mrrstring
- previous_subscriptionsstring
aiobjectnullable
Show child attributes
- subscriptionsstring
- mrrstring
- share_of_subscriptionsstring
- share_of_mrrstring
- previous_subscriptionsstring
tracked_sharestring
surfacesarray of object
weeksarray of object
livemodeboolean
true for live data, false for the test-mode sandbox.

The Ai subscriptions object


{
  "object": "ai_subscriptions",
  "brand": "br_034CyfRFSXUqzrbzV6MAfZ",
  "market": "FR",
  "period": "90d",
  "from": "string",
  "to": "string",
  "last_synced_at": "2026-09-21T02:40:00Z",
  "currency": "EUR",
  "new": {
    "subscriptions": "string",
    "mrr": "string",
    "previous_subscriptions": "string"
  },
  "ai": {
    "subscriptions": "string",
    "mrr": "string",
    "share_of_subscriptions": "string",
    "share_of_mrr": "string",
    "previous_subscriptions": "string"
  },
  "tracked_share": "string",
  "surfaces": [
    {}
  ],
  "weeks": [
    {}
  ],
  "livemode": true
}

The Ai traffic object

Attributes

objectstring
ai_traffic
brandstring
The brand the object belongs to (br_…).
marketstring
Market code (ISO country, e.g. FR).
periodstring
fromstringnullable
tostringnullable
last_hit_atstring
conversion_metricenumnullable
Possible values: transactions · key_events
aiobjectnullable
Show child attributes
- sessionsstring
- transactionsstring
- key_eventsstring
- conversion_ratestring
- share_of_sessionsstring
- previous_sessionsstring
- sessions_changestring
siteobjectnullable
Show child attributes
- sessionsstring
- transactionsstring
- key_eventsstring
- conversion_ratestring
surfacesarray of object
weeksarray of object
first_touchobjectnullable
Show child attributes
- window_daysstring
- conversionsstring
- ai_conversionsstring
- ai_sharestring
- surfacesarray of object
livemodeboolean
true for live data, false for the test-mode sandbox.

The Ai traffic object


{
  "object": "ai_traffic",
  "brand": "br_034CyfRFSXUqzrbzV6MAfZ",
  "market": "FR",
  "period": "90d",
  "from": "string",
  "to": "string",
  "last_hit_at": "2026-09-21T02:40:00Z",
  "conversion_metric": "transactions",
  "ai": {
    "sessions": "string",
    "transactions": "string",
    "key_events": "string",
    "conversion_rate": "string",
    "share_of_sessions": "string",
    "previous_sessions": "string",
    "sessions_change": "string"
  },
  "site": {
    "sessions": "string",
    "transactions": "string",
    "key_events": "string",
    "conversion_rate": "string"
  },
  "surfaces": [
    {}
  ],
  "weeks": [
    {}
  ],
  "first_touch": {
    "window_days": "string",
    "conversions": "string",
    "ai_conversions": "string",
    "ai_share": "string",
    "surfaces": [
      {}
    ]
  },
  "livemode": true
}

Retrieve the AI attribution

GET/v1/brands/{brand}/attribution

Orders and revenue attributed to AI surfaces (ChatGPT, Claude, Gemini, Perplexity…) vs the whole store on a market over a period, by surface and by product — the figures of the Revenue screen. Attribution is last-touch, read from the store’s orders (referrer, utm_source, ref). Totals are null before the first order.

Parameters

brandstringrequired
Brand id (br_…).

Returns

Returns the attribution object. Raises an error if something goes wrong.

curl


curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/attribution \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/attribution', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
  },
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('GET', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/attribution', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.get(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/attribution",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "object": "attribution",
  "brand": "br_034CyfRFSXUqzrbzV6MAfZ",
  "market": "FR",
  "period": "90d",
  "currency": "EUR",
  "from": "string",
  "to": "string",
  "ai": {
    "orders": "string",
    "revenue": "string",
    "average_basket": "string",
    "share_of_revenue": "string",
    "share_of_orders": "string",
    "previous_orders": "string",
    "previous_revenue": "string",
    "revenue_change": "string"
  },
  "store": {
    "orders": "string",
    "revenue": "string",
    "average_basket": "string"
  },
  "surfaces": [
    {}
  ],
  "products": [
    {}
  ],
  "first_touch": {
    "window_days": "string",
    "orders": "string",
    "ai_orders": "string",
    "ai_share": "string",
    "ai_revenue": "string",
    "surfaces": [
      {}
    ]
  },
  "livemode": true
}

Retrieve the visibility ↔ revenue correlation

GET/v1/brands/{brand}/correlation

AI visibility and AI-attributed revenue side by side, week by week, with the fixes published each week — for the whole brand or one catalogue category. Visibility is given raw per model (hits / runs) plus the all-models share. weeks is empty until the store sent a first order.

Parameters

brandstringrequired
Brand id (br_…).
categorystring

Returns

Returns the visibility_revenue_correlation object. Raises an error if something goes wrong.

curl


curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/correlation \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/correlation', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
  },
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('GET', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/correlation', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.get(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/correlation",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "object": "visibility_revenue_correlation",
  "brand": "br_034CyfRFSXUqzrbzV6MAfZ",
  "market": "FR",
  "period": "90d",
  "category": "string",
  "currency": "EUR",
  "categories": [
    {}
  ],
  "weeks": [
    {}
  ],
  "fixes": [
    {}
  ],
  "livemode": true
}

Retrieve the AI subscriptions

GET/v1/brands/{brand}/subscriptions

New subscriptions and new MRR of a SaaS brand on a market over a period, read from its Stripe, and the part the AI assistants brought — as the brand records it in the customer’s or the subscription’s metadata (referrer, utm_source, landing_url). With the Growth plan or above, weeks puts the weekly AI visibility (raw counts per model) next to the new MRR. The blocks are null until Stripe is connected and synced; SaaS brands only.

Parameters

brandstringrequired
Brand id (br_…).

Returns

Returns the ai_subscriptions object. Raises an error if something goes wrong.

curl


curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/subscriptions \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/subscriptions', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
  },
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('GET', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/subscriptions', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.get(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/subscriptions",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "object": "ai_subscriptions",
  "brand": "br_034CyfRFSXUqzrbzV6MAfZ",
  "market": "FR",
  "period": "90d",
  "from": "string",
  "to": "string",
  "last_synced_at": "2026-09-21T02:40:00Z",
  "currency": "EUR",
  "new": {
    "subscriptions": "string",
    "mrr": "string",
    "previous_subscriptions": "string"
  },
  "ai": {
    "subscriptions": "string",
    "mrr": "string",
    "share_of_subscriptions": "string",
    "share_of_mrr": "string",
    "previous_subscriptions": "string"
  },
  "tracked_share": "string",
  "surfaces": [
    {}
  ],
  "weeks": [
    {}
  ],
  "livemode": true
}

Retrieve the AI traffic

GET/v1/brands/{brand}/traffic

Sessions and conversions the AI assistants (ChatGPT, Claude, Gemini, Perplexity…) send to the site, per surface and per week, vs the whole site — measured by the Skoup script installed on it, the figures of the « AI traffic » screen — and the conversions whose first touch was an assistant. The blocks are null until the script brought a visit.

Parameters

brandstringrequired
Brand id (br_…).

Returns

Returns the ai_traffic object. Raises an error if something goes wrong.

curl


curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/traffic \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/traffic', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
  },
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('GET', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/traffic', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.get(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/traffic",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "object": "ai_traffic",
  "brand": "br_034CyfRFSXUqzrbzV6MAfZ",
  "market": "FR",
  "period": "90d",
  "from": "string",
  "to": "string",
  "last_hit_at": "2026-09-21T02:40:00Z",
  "conversion_metric": "transactions",
  "ai": {
    "sessions": "string",
    "transactions": "string",
    "key_events": "string",
    "conversion_rate": "string",
    "share_of_sessions": "string",
    "previous_sessions": "string",
    "sessions_change": "string"
  },
  "site": {
    "sessions": "string",
    "transactions": "string",
    "key_events": "string",
    "conversion_rate": "string"
  },
  "surfaces": [
    {}
  ],
  "weeks": [
    {}
  ],
  "first_touch": {
    "window_days": "string",
    "conversions": "string",
    "ai_conversions": "string",
    "ai_share": "string",
    "surfaces": [
      {}
    ]
  },
  "livemode": true
}

List AI-attributed orders

GET/v1/brands/{brand}/orders

The store orders attributed to an AI surface, newest first. Test orders are excluded; no customer data is ever returned.

Parameters

brandstringrequired
Brand id (br_…).
surfacestring
countrystring
limitinteger
Number of objects to return, between 1 and 100 (default 20).
starting_afterstring
Cursor: the id of the last object of the previous page.

Returns

A dictionary with a data property holding up to limit order objects, newest first, and has_more telling whether another page exists. Raises an error if something goes wrong.

curl


curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/orders?limit=3 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/orders?limit=3', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
  },
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('GET', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/orders?limit=3', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.get(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/orders?limit=3",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "object": "list",
  "url": "/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/orders",
  "has_more": false,
  "data": [
    {
      "id": "ord_031DIivuBKog78mwjgnaYz",
      "object": "order",
      "source": "shopify",
      "order_number": "#1042",
      "ordered_at": "2026-09-23T09:12:44Z",
      "currency": "EUR",
      "subtotal": "2399.00",
      "total": "2399.00",
      "items_count": 1,
      "country": "FR",
      "ai_surface": "chatgpt",
      "attribution_signal": "referrer",
      "referrer_host": "chatgpt.com",
      "landing_path": "/products/strade-7",
      "landing_product": "prod_031DIivuBKog78mwjgnbd3",
      "utm_source": null,
      "utm_medium": null,
      "utm_campaign": null,
      "lines": [
        {
          "product": "prod_031DIivuBKog78mwjgnbd3",
          "title": "Strade 7",
          "sku": "STR7-M",
          "quantity": 1,
          "unit_price": "2399.00",
          "total": "2399.00"
        }
      ],
      "livemode": true,
      "created": 1790154764
    }
  ]
}