Ecommerce Attribution API - User Guide

Overview

The Ecommerce Attribution API qualifies incoming ecommerce traffic against a referential of attribution levers and determines which marketing channel should be credited for conversions.

Current Version: 1.0.7

---

Target Audience

Role	Purpose
Product Owner	Understand business scope and value
Developer	Implement and integrate the API
QA / Architect	Validate behaviors and technical compliance
Customer Connect API	Support consumers during onboarding

---

Business Model

Attribution Sources

The API compares up to three sources of attribution to determine the winner:

Source	Origin	Description
Current Lever	Request body	currentSourceId and currentMerchantId from 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 mobile app

Lever Categories

Traffic sources are classified by strategic value (higher wins):

Category	Description	Examples
5	Premium partnerships	Strategic partners
4	High-value acquisition	SEO, SEM, paid search
3	Marketing relationships	Email campaigns, CRM
2	Low-value channels	Direct access
1	Non-qualified	Default, errors

Selection Algorithm

1. All sources have different categories → Source with maximum category wins
2. All sources have same category → Current visit is kept
3. Current = Web category OR Current = App category → Current visit is kept
4. Web = App (no current) → Web attribution is kept
5. Legacy (2-way comparison) → Current wins if category ≥ Web

---

API Access

Authentication

Method: API Key

Required Header:

apikey: <your-api-key>

Content Type:

Content-Type: application/json

Environments

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

---

POST Endpoint

Endpoint Details

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

Qualifies incoming traffic and returns the best attribution.

Request Body

All fields are optional. Empty request {} is accepted.

Field	Type	Description
affcookie	string \| null	Encrypted web attribution cookie (usually read from Cookie header)
currentSourceId	string \| null	Source identifier of current visit
currentMerchantId	string \| null	Merchant/campaign identifier of current visit
affcookieApp	string \| null	Mobile application attribution cookie

Response Body (200 OK)

Field	Type	Description
currentVisit	AttributionValue	Attribution of current traffic source
outputBestVisit	AttributionValue	Winner - Use for tracking, reporting, BI
affcookie	string	Encrypted cookie value (same as Set-Cookie header)
expiresIn	number	Cookie lifetime in seconds (default: 2592000 = 30 days)

AttributionValue Structure:

{
  sourceId: string;
  merchantId: string;
  leverLabel: string;
  leverCategory: number; // 1-5
  leverCode: string;
}

Response Headers

For web consumers, the API sets cookies:

• affcookie: HttpOnly, Secure, SameSite=None, 30 days
• trCookie: Base64-encoded, readable by client scripts

Note: affcookieApp is never set as a cookie. Mobile apps must store the affcookie value from the response and send it back as affcookieApp in future requests.

---

Usage Examples

Example 1: Web Visitor with Campaign Parameters

Request:

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

Response:

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

Example 2: Mobile Application

Request:

curl -X POST 'https://rec-api.accor.com/referential/v1/best-visit/cookie-attribution' \
  -H 'apikey: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "affcookieApp": "uOF4UzTi0/YwzHEkYoy96MYY1oUQmC85c0/Bu0kYIPQ="
  }'

Important: Mobile apps must store the affcookie from the response and send it as affcookieApp on the next call.

Example 3: Cross-Platform User (Web + Mobile)

Request:

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

The API performs three-way comparison between current visit, web cookie (if present in header), and mobile app cookie.

Example 4: Attribution Retained

Scenario: Previous visit from Google Ads (category 4), current visit direct (category 2)

Response:

• currentVisit → Direct lever (category 2)
• outputBestVisit → Google Ads (category 4) - retained

Example 5: First-Time Visitor

Request:

{}

Response: Default attribution AH (category 1, lever code LNQ) in both currentVisit and outputBestVisit.

---

Error Handling

All errors follow the ErrorResponse format:

{
  title: string;
  status: string;
  detail: string;
  requestId?: string;
}

Error Codes

HTTP Code	Title	Cause	Action
400	Invalid Input	Request validation failed (e.g., invalid types)	Check input parameter types
404	Service Not Found	Invalid URL or unsupported operation	Verify endpoint path
500	Internal Server Error	Backend issue (encryption, secrets, database)	Retry, then contact support with requestId

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

---

Important Notes

Limitations

• Single Operation: Only POST is available. No read-only lookup.
• Cookie Expiration: 30 days. After expiry, customer is treated as new visitor.
• Mobile Cookie Storage: affcookieApp is input-only. Apps must store affcookie from response.
• Cookie Opacity: Values are encrypted. Do not parse or build them manually.
• Gateway Validation: Request body is not validated by gateway (validateMessageBody: false), but unknown query parameters are rejected.

Special Lever Codes

• LNQ - Non-qualified lever
• LEQ - Error qualified
• AH - Default attribution (category 1)

Traceability

All error responses include a requestId correlation identifier. Provide it to support when reporting issues.

---

Additional Resources

• OpenAPI Specification: specs/openapi.yaml (version 1.0.7)
• Support: Contact Customer Connect API team for onboarding and integration support