Merchant Implementation Guide

GA4 · Google Ads · Meta (Facebook) · TikTok · Synerise · Criteo · RTB House

1. Introduction

The InPost Pay conversions integration enables automatic forwarding of purchase data from InPost Pay to selected marketing platforms. This allows you to measure the effectiveness of advertising campaigns and optimise budgets.

The system runs as a Google Cloud Function (Gen2) triggered every 4 hours by Cloud Scheduler. Each execution fetches new orders from the InPost Pay API, processes them, and sends purchase events to all enabled integrations.

Supported Platforms

Platform	What is sent	Mode

Platform	What is sent	Mode
Google Analytics 4	`purchase` event (Measurement Protocol)	Optional
Google Ads	Offline Click Conversions (Enhanced)	BigQuery or API
Meta (Facebook)	Purchase event (Conversions API)	Optional
TikTok	Purchase event (Events API v1.3)	Optional
Synerise	transaction.charge (Batch API v4)	Optional
Criteo	transactionConfirmation (Marketing Solutions API)	Optional
RTB House	Purchase event (Events API server-side)	Optional

Each integration is independent — you can enable any combination of platforms. The system guarantees deduplication: every order is sent to a given platform exactly once.

2. Prerequisites

2.1. Google Cloud Project (GCP)

A GCP project with billing enabled is required. The deploy.sh script will automatically enable the required APIs and create resources, but the project itself must already exist.

GCP project with active billing
gcloud CLI (Google Cloud SDK) installed
A logged-in account with roles/owner or roles/editor permissions on the project

2.2. InPost Pay Credentials

You receive these credentials from your InPost Pay account manager:

Parameter	Description

Parameter	Description
`client_id`	Application identifier — provided by InPost
`client_secret`	Application secret key — provided by InPost
Environment mode	`sandbox` (test) or production

2.3. order_additional_parameters

Key step on the Merchant side

For the integration to work, your shop must pass marketing identifiers in the order_additional_parameters field when creating an order in InPost Pay.

Without these parameters, the system will be unable to link purchases to advertising campaigns.

Your e-commerce plugin / backend must read the appropriate cookies/URL parameters and pass them in the array:

Key	Description	Source

Key	Description	Source
`client_id`	GA4 Client ID — required for GA4	Cookie `_ga` (format: GA1.1.XXXXXXX)
`gclid`	Google Click ID — required for Google Ads	URL param `?gclid=...`
`fbclid`	Facebook Click ID — required for Meta CAPI	URL param `?fbclid=...`
`ttclid`	TikTok Click ID — required for TikTok Events API	URL param `?ttclid=...`
`gum_caller_id`	Criteo User ID — optional for Criteo	Cookie `cto_bundle` or Criteo OneTag
`rtb_click_id`	RTB House Click ID — optional for RTB House	URL param or RTB House cookie

Example JSON structure passed when creating an order:

"order_additional_parameters": [
  { "key": "client_id",      "value": "1234567890.9876543210" },
  { "key": "gclid",          "value": "EAIaIQob..." },
  { "key": "fbclid",         "value": "IwAR3x..." },
  { "key": "ttclid",         "value": "E.C.P..." },
  { "key": "gum_caller_id",  "value": "abc123..." },
  { "key": "rtb_click_id",   "value": "xyz789..." }
]

Optional values — if a given parameter is unavailable, simply omit the corresponding key.

For implementation details of order_additional_parameters for specific e-commerce platforms, refer to the dedicated guides:

Direct integration — InPost Pay - Analytics
Magento — InPost Pay - Analytics - Magento
PrestaShop — InPost Pay - Analytics - PrestaShop
WooCommerce — InPost Pay - Analytics - Woocommerce

3. Platform-Specific Configuration

Below you will find instructions for obtaining the data required by each platform. All data is entered interactively when running the deployment script.

3.1. Google Analytics 4 (Measurement Protocol)

Note — Magento plugin with GA4: If your shop uses the Magento plugin with a built-in GA4 integration, do NOT enable GA4 in this integration — it will cause duplication of purchase events.

Required parameters:

Parameter	How to obtain

Parameter	How to obtain
`Measurement ID`	GA4 → Admin → Data Streams → Web → Measurement ID (format: `G-XXXXXXXXXX`)
`API Secret`	GA4 → Admin → Data Streams → Web → Measurement Protocol API Secrets → Create

Required order_additional_parameters key: client_id

3.2. Google Ads (Offline Conversions)

Two modes are available:

Mode A: BigQuery (recommended)

The system writes orders to a BigQuery table. You then configure a native BigQuery import in the Google Ads panel. This mode is simpler and requires no additional OAuth credentials.

Provide a BigQuery dataset name (e.g. inpost_marketing)
The script automatically creates the inpost_purchases table and the inpost_conversions_view view
In Google Ads → Tools → Conversions → Import → Google Cloud / BigQuery
Point to the view: {projekt}.{dataset}.inpost_conversions_view

Mode B: API (direct upload)

The system sends conversions directly via the Google Ads API. Requires OAuth2 and a Developer Token.

Parameter	How to obtain

Parameter	How to obtain
`Customer ID`	Google Ads → account header (format: 123-456-7890)
`Conversion Action ID`	Tools → Conversions → select an action of type Upload clicks → ID from URL
`Developer Token`	Google Ads API Center → API Access → Developer Token
`OAuth Client ID`	Google Cloud Console → APIs & Services → Credentials → OAuth 2.0
`OAuth Client Secret`	Same as above — OAuth client details section
`Refresh Token`	Generate via OAuth2 Playground or a custom script with scope: ads
`Login Customer ID`	Optional — required only for MCC accounts (format: 123-456-7890)

Required order_additional_parameters key: gclid

3.3. Meta / Facebook (Conversions API)

Parameter	How to obtain

Parameter	How to obtain
`Access Token`	Events Manager → Data Sources → Pixel → Settings → Generate Access Token
`Pixel ID`	Events Manager → Data Sources → Pixel ID (number in the header)

Required order_additional_parameters key: fbclid (optional — the system sends events even without fbclid, but matching will be based solely on PII data)

Meta token expiry: The Meta token expires after approximately 60 days. The system will log a 401 error when this happens. You must then generate a new token and update the secret in Google Cloud Secret Manager.

3.4. TikTok (Events API v1.3)

Parameter	How to obtain

Parameter	How to obtain
`Access Token`	TikTok Business Center → Assets → Events → Settings → Events API → Generate Access Token
`Pixel ID`	TikTok Business Center → Assets → Events → Pixel Code (e.g. CXXXXXXXXX)

Required order_additional_parameters key: ttclid

3.5. Synerise (transaction.charge)

Parameter	How to obtain

Parameter	How to obtain
`Workspace API Key`	Synerise → Settings → API Keys → key with API_BATCH_TRANSACTION_CREATE permission
Base URL	Azure EU: api.synerise.com \| Azure USA: api.azu.synerise.com \| GCP: api.geb.synerise.com

Synerise identifies the customer profile by email address (no additional click IDs required). The transaction includes order products with gross and net prices; the metadata carries gclid, fbclid, ttclid, and ga_client_id.

3.6. Criteo Marketing Solutions (Conversions API)

The Criteo integration uses OAuth2 (client_credentials) for authorisation. The token is automatically cached and refreshed.

Parameter	How to obtain

Parameter	How to obtain
`Client ID`	Criteo Management Center → Settings → API Consumers → create or select a consumer → Client ID
`Client Secret`	Same as above — Secret generated when creating the consumer (copy immediately; it cannot be displayed again)
`Account ID`	Criteo Management Center → account header → Account ID (numeric identifier)

Event type sent to Criteo: transactionConfirmation — includes order products, value, currency, and SHA256(email) as identity.

Optional order_additional_parameters key: gum_caller_id — if available, passed as callerUserId in the payload (improves user matching).

API Consumer permissions: The consumer must have the events scope granted in Criteo Management Center → API Consumers → Edit → Permissions.

3.7. RTB House (Events API — server-side)

RTB House requires no token — authentication is handled via taggingHash in the payload. Credentials are obtained exclusively from your RTB House account manager (no public API documentation).

Parameter	How to obtain

Parameter	How to obtain
`Tagging Hash`	From RTB House Account Manager — unique authentication hash for your account
`Partner Key`	From RTB House Account Manager — partner identifier (accountId)
Region	EMEA: `ams` (default) \| US: `us`\| Asia: `asia` — determines the API endpoint

Endpoint depends on region:

Region	Endpoint

Region	Endpoint
EMEA (ams)	`https://creativecdn.com/tags`
US	`https://us-creativecdn.com/tags`
Asia	`https://asia-creativecdn.com/tags`

Event type: purchase — includes products, order value, and SHA256(email) as userId.

Optional order_additional_parameters key: rtb_click_id — if available, passed as clickId in the payload (improves attribution).

No public documentation: RTB House does not provide public docs for the Events API. The parameters described above are based on Tealium and MetaRouter connector documentation and information from RTB House Account Managers

4. Deployment Process

The entire deployment process is automated by the deploy.sh script. The script interactively asks for the required data, creates all GCP resources, and starts the function.

Download cloud-function-ga4.zip from your InPost Pay team.

cloud-function-ga4.zip

4.1. Preparing the Files

Files are provided by the InPost Pay team. Place them in a single directory:

File	Description

File	Description
`main.py`	Core integration logic (Cloud Function)
`deploy.sh`	Deployment script (automated GCP configuration)
`requirements.txt`	Python dependencies

4.2. Running the Deployment

Open a terminal in the directory containing the files
Log in to GCP: gcloud auth login
Run: bash deploy.sh
The script will sequentially ask for: GCP project ID, region, InPost environment, and then credentials for each integration
Wait for completion — the script will create a Service Account, GCS bucket, secrets, the function, and a Cloud Scheduler schedule

4.3. Resources Created Automatically

Resource	Details

Resource	Details
Service Account	sa-inpost-ga4@{project}.iam.gserviceaccount.com with minimal permissions
Bucket GCS	Sync state, lists of sent IDs (auto-deleted after 30 days)
Secret Manager	All API tokens and keys (encrypted at rest)
Cloud Function	Gen2, 2 GiB RAM, timeout 540s, private (no public access)
Cloud Scheduler	Every 4h (CRON: 0 /4 * *), timezone: Europe/Warsaw
BigQuery *	BQ mode only: dataset, inpost_purchases table, inpost_conversions_view view

5. Post-Deployment Verification

5.1. Test Invocation

After deployment, run a manual invocation to confirm the function is working correctly:

gcloud functions call inpost-ga4-integration \
  --region=europe-central2 \
  --data '{"debug": "true"}'

The debug=true parameter enables debug mode for GA4 (event validation via Google) and does not save sent IDs (the function can be invoked multiple times without duplication).

5.2. Checking Logs

Logs are available in Google Cloud Console → Cloud Logging. Filter:

resource.type="cloud_function" resource.labels.function_name="inpost-ga4-integration"

A successful execution looks like this:

Active integrations: GA4=True, GoogleAds=bq, Meta=True, TikTok=False, Synerise=False, Criteo=True, RTB=False
Fetched 47 orders (smart sync from 2026-02-23T12:00:00)
GA4: 42 sent | Meta: 47 sent | BQ: 47 rows saved | Criteo: 47 sent

5.3. Platform-Side Verification

Platform	Where to check

Platform	Where to check
GA4	Realtime → Events → purchase \| DebugView (if debug=true)
Google Ads	Tools → Conversions → Status: Recording conversions
Meta	Events Manager → Overview → Purchase → Server events
TikTok	Events Manager → Web Events → Purchase → Server events
Synerise	Data Management → Transactions → filter by date
Criteo	Criteo Management Center → Events → Event Log → filter by transactionConfirmation
RTB House	Contact your RTB House Account Manager — no public event dashboard available

6. Maintenance and Ongoing Operations

6.1. Token Renewal

Platform	Token validity	What to do

Platform	Token validity	What to do
Meta	~60 days	Generate a new token in Events Manager and update the secret: `gcloud secrets versions add META_ACCESS_TOKEN --data-file=-`
TikTok	Depends on type	Standard token does not expire; if using a short-lived token — renew before expiry
Google Ads API	Refresh Token: ∞	Refresh Token does not expire, but may be revoked (password change, access revocation)
Synerise	Auto-refresh	System automatically renews the JWT every 55 minutes — no action required
GA4	Does not expire	API Secret has no expiry date
Criteo	Auto-refresh (~15 min)	System automatically renews the OAuth token — no action required. If credentials change, update `CRITEO_CLIENT_ID / CRITEO_CLIENT_SECRET` secrets.
RTB House	Does not expire	`Tagging Hash` and `Partner Key` have no expiry. Contact your Account Manager for rotation.

6.2. Updating a Secret

To update a token without redeploying the function

# Example: updating the Meta token
echo "NOWY_TOKEN" | gcloud secrets versions add \
  META_ACCESS_TOKEN --data-file=-

The function will automatically pick up the new secret version on its next execution (:latest).

6.3. Schedule

By default, the function runs every 4 hours. This can be changed in Cloud Console → Cloud Scheduler → run-inpost-ga4-integration → Edit → Frequency.

Frequency	CRON	Notes

Frequency	CRON	Notes

InPost Pay – Marketing Conversions Integration