Skip to main content
iZoneo.co.uk Zoneo Group
V1 Technical documentation
Clicks and performance Contact Zoneo

API contract V1

We recommend the server-to-server API. JavaScript is an optional fallback analytics method and works only after analytics consent has been granted.

API contract V1 Link to section API contract V1

We recommend the server-to-server API. JavaScript is an optional fallback analytics method and works only after analytics consent has been granted.

Orders, revenue and derived metrics are shown only while conversion tracking is active. They are analytics-only and do not change CPC billing.

schema_version

1.0

payload_contract

order_v1

Content-Type

application/json

request_limit

64 KiB

How to connect measurement Link to section How to connect measurement

We recommend the server-to-server API. JavaScript is an optional fallback analytics method and works only after analytics consent has been granted.

  1. 1 Save the zclid parameter from the destination URL with the basket or order for 30 days.
  2. 2 On the server, create a stable HMAC-SHA-256 hash of the internal order ID using a separate key. Do not send the raw ID or personal data.
  3. 3 After creating the order, send JSON to the API and sign the exact request body with the integration secret key.
  4. 4 For payment, cancellation and cumulative refunds, reuse the same zclid and order_id_hash. Keep the final totals and item lines unchanged.

The integration secret key is shown only once. Save it in the secret manager on the shop’s server.

Recommended: server-to-server API Link to section Recommended: server-to-server API

The shop’s server sends verified orders, status changes and refunds directly to Zoneo. Never place the secret key in the browser.

POST https://izoneo.co.uk/api/v1/conversions
Sandbox https://izoneo.co.uk/api/v1/conversions/sandbox

On the server, create a stable HMAC-SHA-256 hash of the internal order ID using a separate key. Do not send the raw ID or personal data.

order_id_hash · PHP 

$orderIdHash = hash_hmac(
    'sha256',
    "zoneo-order-v1\n".$internalOrderId,
    $_ENV['ZONEO_ORDER_HASH_KEY'],
);

Request example Link to section Request example

After creating the order, send JSON to the API and sign the exact request body with the integration secret key.

order_v1 · JSON 

{
    "schema_version": "1.0",
    "zclid": "018fb72a-7d8e-7c3c-a4da-f37ce07ad739",
    "order_id_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "currency": "GBP",
    "occurred_at": "2026-08-31T12:34:56Z",
    "status": "placed",
    "refund_amount_minor": 0,
    "totals": {
        "items_gross_minor": 14000,
        "discount_minor": 1500,
        "shipping_gross_minor": 390,
        "fees_gross_minor": 100,
        "tax_minor": 2165,
        "order_total_gross_minor": 12990
    },
    "items": [
        {
            "merchant_item_id": "ITEM_ID_FROM_FEED",
            "item_group_id": "MODEL-10",
            "variant_id": "size:42",
            "name": "PRODUCT_NAME",
            "gtin": "8581234567890",
            "quantity": 2,
            "unit_price_gross_minor": 7000,
            "line_total_gross_minor": 14000
        }
    ],
    "order_locale": "en-gb",
    "expected_delivery_date": "2026-09-03"
}
order_v1 · JSON
JSON Required fields V1
schema_version ✓ = "1.0"
zclid ✓ UUID
order_id_hash ✓ HMAC-SHA-256 · [a-f0-9]{64}
currency ✓ ISO 4217 · GBP
occurred_at ✓ ISO 8601 · UTC
status ✓ placed | paid | cancelled | partially_refunded | refunded
refund_amount_minor ✓ integer ≥ 0 · Σ · monotonic
totals ✓ object · integer · gross
items ✓ array[1..100]
order_locale — BCP 47
expected_delivery_date — YYYY-MM-DD
order_v1 · items[]
items[] Required fields V1
merchant_item_id ✓ feed.ITEM_ID · stable
quantity ✓ integer · 1..1000
unit_price_gross_minor ✓ integer ≥ 0
line_total_gross_minor ✓ unit_price_gross_minor × quantity
item_group_id — string
variant_id — string
name — string · PRODUCT_NAME · PII = 0
gtin — [0-9]{8,14}

totals · GBP · integer 

totals.items_gross_minor = sum(items[].line_total_gross_minor)

totals.order_total_gross_minor = totals.items_gross_minor - totals.discount_minor + totals.shipping_gross_minor + totals.fees_gross_minor

line_total_gross_minor = unit_price_gross_minor × quantity

Canonical signature Link to section Canonical signature

If you have not saved the original secret key, select Restore secret key and securely save the new key immediately.

HTTP · HMAC-SHA-256
HTTP V1
Content-Type application/json
X-Zoneo-Integration-ID zci_...
X-Zoneo-Timestamp Unix · UTC
X-Zoneo-Nonce CSPRNG · unique · len ≥ 16
Idempotency-Key order:{hash}:{status}
X-Zoneo-Signature v1=HMAC_SHA256_HEX

HMAC-SHA-256 · canonical request 

UPPERCASE_HTTP_METHOD
/exact/request/path
unix_timestamp
nonce
idempotency_key
sha256_hex_of_exact_raw_body

body_hash = SHA256(raw_body)
signature = HMAC_SHA256(api_secret, canonical_request)
X-Zoneo-Signature = "v1=" + lowercase_hex(signature)

S2S · PHP 

<?php

$path = '/api/v1/conversions';
$body = json_encode($payload, JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
$timestamp = time();
$nonce = bin2hex(random_bytes(16));
$idempotencyKey = 'order:'.$orderIdHash.':'.$payload['status'];
$canonical = implode("\n", [
    'POST',
    $path,
    (string) $timestamp,
    $nonce,
    $idempotencyKey,
    hash('sha256', $body),
]);
$signature = hash_hmac('sha256', $canonical, $_ENV['ZONEO_API_SECRET']);

$headers = [
    'Content-Type: application/json',
    'X-Zoneo-Integration-ID: '.$_ENV['ZONEO_INTEGRATION_ID'],
    'X-Zoneo-Timestamp: '.$timestamp,
    'X-Zoneo-Nonce: '.$nonce,
    'Idempotency-Key: '.$idempotencyKey,
    'X-Zoneo-Signature: v1='.$signature,
];

$curl = curl_init('https://izoneo.co.uk/api/v1/conversions');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_TIMEOUT => 10,
]);
$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

Placed → Refunded Link to section Placed → Refunded

For payment, cancellation and cumulative refunds, reuse the same zclid and order_id_hash. Keep the final totals and item lines unchanged.

Placed · placed Paid · paid Cancelled · cancelled Partially refunded · partially_refunded Refunded · refunded

order_v1 · lifecycle 

placed -> paid | cancelled | partially_refunded | refunded
paid -> partially_refunded | refunded
partially_refunded -> refunded
cancelled, refunded -> terminal

0 <= refund_amount_minor <= totals.order_total_gross_minor
new_refund_amount_minor >= previous_refund_amount_minor

Idempotency-Key · retry 

nonce₁ != nonce₂
retry = nonce₂ + Idempotency-Key₁ + SHA256(JSON₁)
Idempotency-Key₁ + SHA256(JSON₁) -> HTTP 200
Idempotency-Key₁ + SHA256(JSON₂) -> HTTP 409 idempotency_conflict

Sandbox V1 Link to section Sandbox V1

Paste a V1 JSON payload to validate its fields, totals and feed item matching without creating an order or affecting billing.

POST https://izoneo.co.uk/api/v1/conversions/sandbox
persisted = false billing_impact = false

Optional JavaScript measurement Link to section Optional JavaScript measurement

The library stores zclid after consent and sends only the initial placed event from the thank-you page. Send later states securely by S2S.

Consent is disabled by default. The consent function must return true only after valid user analytics consent has been granted.

Loading and initialisation 

<script src="https://izoneo.co.uk/integrations/zoneo-conversion-v1.js"></script>
<script>
const zoneo = window.ZoneoConversions.init({
  integrationId: 'zci_...',
  apiBase: 'https://izoneo.co.uk/api/v1/conversions',
  consent: () => analyticsConsent === true
})

zoneo.track({
  order_id_hash: 'SERVER_HMAC_SHA256',
  currency: 'GBP',
  occurred_at: new Date().toISOString(),
  status: 'placed',
  totals: {
    items_gross_minor: 12990,
    discount_minor: 0,
    shipping_gross_minor: 0,
    fees_gross_minor: 0,
    tax_minor: 2165,
    order_total_gross_minor: 12990
  },
  items: [{
    merchant_item_id: 'ITEM_ID_FROM_FEED',
    quantity: 1,
    unit_price_gross_minor: 12990,
    line_total_gross_minor: 12990
  }]
})
</script>

Integration health Link to section Integration health

Accepted and rejected events during the last 7 days.

201 · created = true
200 · idempotent = true | deduplicated = true
4xx · error.code

HTTP 201 · JSON 

{
    "data": {
        "conversion_reference": "6bfca33e-3ac7-48dc-a733-c1f313853269",
        "status": "placed",
        "source": "s2s",
        "verification": "hmac_current",
        "schema_version": "1.0",
        "payload_contract": "order_v1",
        "totals": {
            "items_gross_minor": 14000,
            "discount_minor": 1500,
            "shipping_gross_minor": 390,
            "fees_gross_minor": 100,
            "tax_minor": 2165,
            "order_total_gross_minor": 12990
        },
        "refund_amount_minor": 0,
        "net_revenue_minor": 12990,
        "items": {
            "count": 1,
            "quantity_total": 2,
            "matched_count": 1,
            "match_status": "complete"
        },
        "totals_reconciled": true,
        "warnings": [],
        "currency": "GBP",
        "created": true,
        "idempotent": false,
        "deduplicated": false,
        "provisional": false,
        "billing_impact": false
    }
}

HTTP 4xx · JSON 

{
    "error": {
        "code": "order_total_mismatch",
        "field": "totals.order_total_gross_minor",
        "details": {
            "expected_minor": 12990,
            "received_minor": 13000
        }
    }
}
invalid_signature stale_timestamp replayed_nonce pii_not_allowed items_total_mismatch order_total_mismatch currency_mismatch click_not_eligible store_or_market_mismatch not_last_zoneo_click attribution_window_expired invalid_state_transition order_definition_conflict refund_amount_decreased order_attribution_conflict

Privacy policy Link to section Privacy policy

Latest analytics-only orders received by Zoneo. Raw order IDs and personal data are never displayed.

On the server, create a stable HMAC-SHA-256 hash of the internal order ID using a separate key. Do not send the raw ID or personal data.

Orders, revenue and derived metrics are shown only while conversion tracking is active. They are analytics-only and do not change CPC billing.

How to connect measurement

We recommend the server-to-server API. JavaScript is an optional fallback analytics method and works only after analytics consent has been granted.

Clicks and performance Back to top