Ecommerce Attribution API - User Guide

1. Document Purpose

This guide provides business, functional and technical context to help API consumers understand and integrate the API. It complements the OpenAPI specification (specs/openapi.yaml, version 1.0.5).

2. Target Audience

Profile	Role
Product Owner	Understand the business scope and value of the API
Developer	Implement and integrate the API
QA / Architect	Validate expected behaviors and technical compliance
Customer Connect API (CCA)	Support API consumers during onboarding and integration

3. API Overview

3.1 Business Context

The API qualifies incoming ecommerce traffic against a referential of attribution levers and determines which marketing channel should be credited for a conversion. It compares up to three sources of attribution and keeps the most valuable one:

Source	Origin	Description
Current lever	Request body	currentSourceId and currentMerchantId of the current visit
Web cookie	Cookie header or body	affcookie, encrypted attribution from previous web visits
Mobile app cookie	Request body	affcookieApp, encrypted attribution stored by the app

Lever categories (higher wins):

Category	Meaning
5	Premium partnerships
4	High-value acquisition (SEO, SEM, paid search)
3	Marketing relationships (email, CRM)
2	Low-value channels (direct access)
1	Non-qualified or errors

Selection rules:

1. All sources have different categories: the source with the maximum category wins.
2. All sources have the same category: the current visit is kept.
3. Current visit has the same category as the web cookie, or as the app cookie: the current visit is kept.
4. Web cookie and app cookie are equal and there is no current visit: the web attribution is kept.
5. Legacy two-way comparison (web only): current wins if its category is greater than or equal to the web one.

3.2 Main Features

• Qualify a visit from currentSourceId / currentMerchantId.
• Merge it with the web and mobile attribution history.
• Return the winning attribution (outputBestVisit) and the refreshed encrypted cookie.
• Set the affcookie and trCookie cookies for web consumers.

3.3 Known Limitations

• A single operation is exposed (POST); there is no read-only lookup of an existing attribution.
• Cookies are valid 30 days (expiresIn = 2592000). After that, the customer is treated as a new visitor.
• affcookieApp is input-only: it is never set as an HTTP cookie. Mobile apps must store the returned affcookie value and send it back as affcookieApp.
• Cookie values are encrypted and opaque; consumers must not parse or build them.
• The gateway does not validate the request body (validateMessageBody: false) but rejects unknown query parameters.

4. Access & Security

4.1 Access Requirements

Requirement	Provided by Accor	Consumer Action Required
API key	✅	🔲 Request via onboarding

4.2 Authentication & Headers

• Auth method: API key.
• Required header: x-api-key: <your key>
• Optional header: Cookie (web), carrying affcookie and trCookie.
• Content type: application/json.

5. API Behavior

5.1 Traceability & Telemetry

Error responses carry a requestId correlation identifier. Provide it to the support team when reporting an issue.

5.2 Health Check

No dedicated health check endpoint is exposed.

6. Endpoints

POST /referential/v1/best-visit/cookie-attribution

Description: qualifies the incoming traffic and returns the best attribution.

Environments

Environment	Base URL
Production	https://api.accor.com
Pre-production	https://pre-api.accor.com
Test	https://rec-api.accor.com

Request body (all fields optional, {} is accepted)

Field	Type	Description
affcookie	string, nullable	Encrypted web attribution cookie. Usually read automatically from the HttpOnly Cookie header; backend consumers may pass it explicitly
currentSourceId	string, nullable	Source of the current visit
currentMerchantId	string, nullable	Merchant or campaign of the current visit
affcookieApp	string, nullable	Mobile application attribution cookie

Response body (200)

Field	Description
currentVisit	Attribution of the current traffic source: sourceId, merchantId, leverLabel, leverCategory, leverCode
outputBestVisit	The winning attribution. Use it for conversion tracking, reporting, partner invoicing and BI
affcookie	Encrypted cookie, same value as in Set-Cookie. Mobile apps store it as affcookieApp
expiresIn	Cookie lifetime in seconds (2592000 = 30 days)

Response headers (web): Set-Cookie for affcookie (HttpOnly, Secure, SameSite=None, 30 days) and trCookie (Base64, readable by client-side scripts).

Special lever codes: LNQ = non-qualified lever, LEQ = error qualified. Default attribution when nothing is provided: AH / AH, category 1.

7. Usage Examples

Web visitor with campaign parameters

curl -X POST 'https://rec-api.accor.com/referential/v1/best-visit/cookie-attribution' \
  -H 'x-api-key: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: affcookie=<encrypted-value>' \
  -d '{"currentSourceId": "googleads", "currentMerchantId": "campaign-summer-2026"}'

{
  "currentVisit": {
    "sourceId": "googleads",
    "merchantId": "googleads",
    "leverLabel": "Search Engine Acquisition",
    "leverCategory": 4,
    "leverCode": "L004"
  },
  "outputBestVisit": {
    "sourceId": "googleads",
    "merchantId": "googleads",
    "leverLabel": "Search Engine Acquisition",
    "leverCategory": 4,
    "leverCode": "L004"
  },
  "affcookie": "uOF4UzTi0/YwzHEkYoy96MYY1oUQmC85c0/Bu0kYIPQ=",
  "expiresIn": 2592000
}

Mobile application

{ "affcookieApp": "uOF4UzTi0/YwzHEkYoy96MYY1oUQmC85c0/Bu0kYIPQ=" }

Store the affcookie of the response and send it as affcookieApp on the next call.

Cross-platform user (web + mobile)

{
  "currentSourceId": "email-campaign",
  "currentMerchantId": "email-campaign",
  "affcookieApp": "uOF4UzTi0/YwzHEkYoy96MYY1oUQmC85c0/Bu0kYIPQ="
}

Previous attribution retained

Previous visit from Google Ads (category 4), current visit direct (category 2): currentVisit is the direct lever, but outputBestVisit stays googleads.

First-time visitor with no data

Send {}. The response contains the default attribution AH (category 1, LNQ) in both currentVisit and outputBestVisit.

8. Error Codes

Errors use the ErrorResponse format: title, status, detail, requestId.

HTTP Code	Title	Description	Recommended Action
400	Invalid Input	Request parameters failed validation (for example non-string currentSourceId)	Check input types
404	Service Not Found	Invalid URL or unsupported operation	Use POST /referential/v1/best-visit/cookie-attribution
500	Internal Server Error	Unexpected backend issue (secret manager, encryption/decryption, database)	Retry, then contact support with the requestId

Missing or invalid API keys are rejected by the API gateway before reaching the service.