Configure events for Criteo Offline Sales

Criteo Offline Sales lets your brand send in-store (offline) transactions to Criteo for retail media attribution and targeting. Criteo uses these transactions to attribute in-store sales back to the ads it served, and to inform ad targeting. Amperity sends one transaction line item per row, identifying each shopper by a hashed email address, a customer ID, or a retailer visitor ID.

Send offline sales to Criteo to attribute in-store purchases back to the ads that Criteo served, and to inform ad targeting. Amperity sends transaction data at the line-item level: each row returned by your query is one product within a purchase, grouped by transaction and then by shopper, and sent to Criteo’s offline sales ingestion service.

Amperity hashes email addresses before sending them; raw email addresses never leave Amperity. A shopper can also be identified by a customer ID or a retailer visitor ID. At least one identifier is required on every row.

Beta

The Criteo Offline Sales connector is currently in beta. Contact your Amperity representative to learn more.

Important

Amperity cannot confirm that Criteo received or attributed your transactions. Criteo accepts any request it can read and reports acceptance the same way whether or not the configured account is correct. A successful connection test and a run that reports no failed rows both mean only that Criteo accepted the request — not that the sales were attributed. Confirm that events landed with your Criteo Account Strategist using Criteo’s own reporting after your first send.

Get details

Review the following details before configuring credentials for Criteo and before configuring Amperity to send offline sales to Criteo.

Credential settings Account ID Required The Criteo Account ID that offline sales are reported against, provided by your Criteo Account Strategist and sent with every event. Criteo must enable this account for offline sales ingestion before it can receive transactions, and issues a separate sandbox account for testing. This value is not masked, so that you can read it back and confirm it matches the account your Criteo Account Strategist issued. Log label Required A label that identifies your traffic in Criteo’s request logs, agreed with your Criteo Account Strategist — for example, mybrand_offlinesales. Criteo’s onboarding materials may call this value the API key. It is not a secret and does not authenticate the request; Criteo uses it only to group and troubleshoot your calls.

Query results A query returns one row per transaction line item, with the columns described in Offline sales fields. Each row must include a transaction ID, a timestamp, a product ID, a price, a quantity, and at least one shopper identifier.

Configure credentials

Configure credentials for Criteo before adding a destination.

An individual with access to Criteo should use SnapPass to securely share “Criteo Account ID and log label” details with the individual who configures Amperity.

To configure credentials for Criteo Offline Sales

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Credentials settings dialog box, do the following: From the Plugin dropdown, select Criteo Offline Sales. Note Amperity provides more than one Criteo connector. Select Criteo Offline Sales to send in-store transactions for retail media attribution. Criteo and Criteo Retail Media are separate connectors that send audience segments. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination.
	The settings that are available for a credential vary by credential type. For the “criteo-offline-sales” credential type, configure settings, and then click Save. Account ID Required The Criteo Account ID that offline sales are reported against, provided by your Criteo Account Strategist and sent with every event. Criteo must enable this account for offline sales ingestion before it can receive transactions, and issues a separate sandbox account for testing. This value is not masked, so that you can read it back and confirm it matches the account your Criteo Account Strategist issued. Log label Required A label that identifies your traffic in Criteo’s request logs, agreed with your Criteo Account Strategist — for example, mybrand_offlinesales. Criteo’s onboarding materials may call this value the API key. It is not a secret and does not authenticate the request; Criteo uses it only to group and troubleshoot your calls. Your Criteo Account Strategist provides the Account ID and the log label when they enable your account for offline sales ingestion.

Add destination

Use a sandbox to configure a destination for Criteo. Before promoting your changes, send a sample audience, and then verify the results in Criteo. After verifying the end-to-end workflow, push the destination from the sandbox to production.

To add a destination

	Open the Destinations tab to configure a destination for Criteo. Click the Add Destination button to open the Destination dialog box. Enter the name of the destination and a description. For example: “Criteo offline sales” and “Send in-store transactions to Criteo.”.
	Credentials allow Amperity to connect to Criteo. The credential type is set automatically. You may use an existing credential or you may add a new one. Select an existing credential from the Credential dropdown. – or – Select Create a new credential from the Credential dropdown. This opens the Credential dialog box.
	In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow limited access to PII for this destination. Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.
	After configuring this destination users may use orchestrations to send query results Criteo.
	Validate the audience with Criteo by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by Criteo. Send the sample audience to Criteo and verify the sample audience is correct in Criteo. Make adjustments if necessary. Only send full audiences after validation is complete.

Build a query

Use a query to build a combination of data — typically from the Unified Itemized Transactions and Customer 360 tables — that returns one row per transaction line item to send to Criteo. Each row must include a transaction ID, a timestamp, a product ID, a price, a quantity, and at least one shopper identifier: a hashed email address, a customer ID, or a retailer visitor ID. You can also include a currency code and a store ID.

Review the Offline sales fields section for the columns your query must and may return, and the How shoppers and transactions are matched section for how line items are grouped into transactions and shoppers.

Note

Criteo attributes offline sales only within two days of the transaction. Amperity enforces this window and skips rows outside it — reported as failed with the reason — so late-arriving in-store data cannot be backfilled through this connector. Any delay between an in-store sale and it reaching Amperity reduces this window.

Note

Criteo deduplicates transactions on their transaction ID, so re-sending a transaction does not count it twice. Bound your query to recent transactions so each orchestration sends new sales rather than re-sending history.

Bound the query to recent transactions — within Criteo’s two-day attribution window — and exclude returns and cancellations so that only completed sales are sent. A query that returns a collection of recent purchase line items for use in Criteo is similar to:

SELECT
  uit.order_id AS transaction_id
  ,uit.order_datetime AS timestamp
  ,uit.product_id AS product_id
  ,uit.unit_revenue AS price
  ,uit.item_quantity AS quantity
  ,uit.currency AS currency
  ,c360.email AS email
FROM Unified_Itemized_Transactions uit
LEFT JOIN Customer_360 c360 ON uit.amperity_id = c360.amperity_id
WHERE uit.order_datetime > (CURRENT_TIMESTAMP - interval '1' day)
AND COALESCE(uit.is_return, false) = false
AND COALESCE(uit.is_cancellation, false) = false

How shoppers and transactions are matched

Criteo’s ingestion format carries one shopper per request, with that shopper’s transactions nested beneath, and each transaction’s line items nested under that. Amperity reassembles the flat rows your query returns into that shape: line items are grouped into transactions, and transactions are grouped by shopper, so one request is sent per shopper. Throughput is therefore measured in shoppers, not rows — a send covering many purchases by a few thousand shoppers is a few thousand requests.

Each shopper is grouped by their strongest available identifier, in this order:

• email — the only identifier that keys into Criteo’s identity graph. Amperity normalizes and hashes the address before sending.

• customer_id — the identifier of a signed-in shopper, stable across their logged-in sessions but meaningful only within your business.

• retailer_visitor_id — an identifier for an unrecognized shopper, persistent only on the same device, so the weakest of the three.

Amperity sends every identifier a shopper’s rows agree on, not only the strongest one, because Criteo matches on whichever it recognizes. Where a shopper’s rows carry two genuinely different values for the same identifier, that identifier is omitted rather than a value being chosen at random. Where line items within one transaction disagree on timestamp, currency, or store ID, one value is used rather than the transaction being rejected.

Data validation

Amperity validates each row before grouping it and drops rows that cannot be sent, so that one invalid line item does not sink a shopper’s whole request. Dropped rows are reported as failed with the reason. A row is dropped when:

• Every shopper identifier — email, customer_id, and retailer_visitor_id — is empty.

• transaction_id is empty.

• timestamp is empty or cannot be read. A timestamp may be a full date and time, a date on its own (treated as midnight UTC), or an epoch second count.

• timestamp is more than two days in the past, outside Criteo’s attribution window. Criteo would accept the row and then discard it downstream without reporting it, so Amperity skips it instead.

• price is not a number.

• quantity is not a whole number.

Offline sales fields

The following table describes each column Amperity sends to Criteo. A query must return columns with the same name as listed in the “Amperity name” column; Amperity maps them to the Criteo fields automatically. Column names are matched without regard to capitalization.

Amperity name	Criteo field	Description
transaction_id	id	Required The transaction identifier. Criteo deduplicates on this value.
timestamp	timestamp	Required When the transaction occurred. Accepts a full date and time, a date on its own (treated as midnight UTC), or an epoch second count. Values that cannot be read, or that are more than two days old, are dropped.
product_id	item.id	Required The product identifier for this line item, matching your product catalog.
price	item.price	Required The unit price for this line item. A non-numeric value is dropped.
quantity	item.quantity	Required The number of units purchased for this line item. A non-whole-number value is dropped.
email	id.email	Optional An email address. Amperity normalizes and hashes the address before sending; the raw address is never sent. At least one of email, customer_id, or retailer_visitor_id is required.
customer_id	customer_id	Optional The identifier of a signed-in shopper. At least one of email, customer_id, or retailer_visitor_id is required.
retailer_visitor_id	retailer_visitor_id	Optional An identifier for an unrecognized shopper, persistent only on the same device. At least one of email, customer_id, or retailer_visitor_id is required.
currency	currency	Optional A three-letter ISO 4217 currency code for the transaction.
store_id	store_id	Optional The store the sale happened in.

Workflow actions

A workflow will occasionally show an error that describes what prevented a workflow from completing successfully. These first appear as alerts in the notifications pane. The alert describes the error, and then links to the Workflows tab.

Open the Workflows page to review a list of workflow actions, choose an action to resolve the workflow error, and then follow the steps that are shown.

	You may receive a notifications error for a configured Criteo destination. This appears as an alert in the notifications pane on the Destinations tab. If you receive a notification error, review the details, and then click the View Workflow link to open this notification error in the Workflows page.
	On the Workflows page, review the individual steps to determine which steps have errors that require your attention, and then click Show Resolutions to review the list of workflow actions generated for this error.
	A list of individual workflow actions are shown. Review the list to identify which action you should take. Some workflow actions are common across workflows and will often be available, such as retrying a specific task within a workflow or restarting a workflow. These types of actions can often resolve an error. In certain cases, actions are specific and are shown when certain conditions exist in your tenant. These types of actions typically must be resolved and may require steps that must be done upstream or downstream from your Amperity workflow. Amperity provides a series of workflow actions that can help resolve specific issues that may arise with Criteo, including: Invalid credentials
	Select a workflow action from the list of actions, and then review the steps for resolving that error. After you have completed the steps in the workflow action, click Continue to rerun the workflow.

Note

A submission that Criteo rejects, or that cannot be delivered, is reported as failed rows with Criteo’s own message or the delivery error. The ingestion endpoint does not authenticate, and Criteo does not validate the account, so a wrong log label or Account ID produces no error in Amperity — such problems surface only in Criteo’s reporting. See Get details.

Invalid credentials

The credentials that are defined in Amperity are invalid.

To resolve this error, verify that the credentials required by this workflow are valid.

1. Open the Credentials page.

2. Review the details for the credentials used with this workflow. Update the credentials for Criteo if required.

3. Return to the workflow action, and then click Resolve to retry this workflow.