Conversion Events

Retract or restate a conversion event

retract — the conversion did not happen after all (a full refund, a cancellation); final, and an event not yet delivered is no longer sent. restate — a new value (a partial refund, an edit); an event not yet delivered goes out with it.

Recorded on the event (adjustments, status, adjustedValue) and visible to every reader. A platform that already received the event from the server is told where it can be (delivery.<platform>.adjustment): Google Ads gets the event again at its new value, a retraction as 0 (Google keeps counting it); Google Analytics gets a refund for a purchase lowered or retracted. Meta, TikTok, Google Tag Manager and browser-only rows cannot be told: their adjustment reads unsupported, with what to do instead.

A 409 also answers when the event is being sent to a platform at that moment and the adjustment would queue a send: send it again a minute later with the same adjustmentId.

Idempotent on adjustmentId. A retry returns the event with applied: false; re-using the ID with different content, or adjusting a retracted event, is a 409.

Access: an API key with conversions:write — or its group master ads:all, or admin:all — or a signed-in user holding the conversion-events:write permission. Anonymous callers get 404.

Signed: every API key must sign this request (X-Fetchski-Timestamp + X-Fetchski-Signature, see the headers below), whatever its own signing mode. Signed-in users in the CMS need no signature. Signing requests shows how, from the API and both SDKs.

Rate limit: the key’s own writes-per-minute limit, set when the key is created (default 120); over it, 429 with Retry-After.

POST

conversion-event

{eventId}

adjust

cURL

curl --request POST \
  --url https://{host}/api/v1/conversion-event/{eventId}/adjust \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "adjustmentId": "tenant-42:order:1234:refund:1",
  "action": "restate"
}
'

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const adjustConversionEvent = await site.conversionEvents().adjustConversionEvent({ eventId: 'tenant-42:order:1234:purchase', adjustmentId: 'tenant-42:order:1234:refund:1', action: 'retract' });

use Fetchski\AttractCmsLaravel\Facades\Attract;

$adjustConversionEvent = Attract::conversionEvents()->adjustConversionEvent(eventId: 'tenant-42:order:1234:purchase', adjustmentId: 'tenant-42:order:1234:refund:1', action: 'retract');

{
  "applied": true,
  "event": {
    "eventId": "b8f2c1de-4f5a-4c1e-9a53-0d6f2b7c1e9a",
    "conversion": {
      "id": "ckq1w2e3r4t5y6u7i8o9p0",
      "key": "quote-request",
      "title": "Quote request"
    },
    "trigger": {
      "type": "form",
      "ref": "ckformid123"
    },
    "source": "browser",
    "occurredAt": "2026-09-21T15:04:05.000Z",
    "recordedAt": "2026-09-21T15:04:05.412Z",
    "updatedAt": "2026-09-21T15:04:07.020Z",
    "page": {
      "url": "https://example.com/contact?gclid=Cj0KCQjw",
      "path": "/contact",
      "referrer": "https://www.google.com"
    },
    "visitorId": "0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c",
    "attribution": {
      "firstTouch": {
        "at": "2026-09-20T09:12:00.000Z",
        "path": "/",
        "landingUrl": "https://example.com/?gclid=Cj0KCQjw",
        "referrerOrigin": "https://www.google.com",
        "adPlatforms": [
          "google"
        ],
        "campaign": {
          "utm_source": "google",
          "utm_campaign": "spring-sale"
        },
        "clickIds": {
          "gclid": "Cj0KCQjw"
        }
      },
      "adPlatforms": [
        "google"
      ],
      "campaign": {
        "utm_source": "google",
        "utm_campaign": "spring-sale"
      },
      "clickIds": {
        "gclid": "Cj0KCQjw"
      },
      "browserIds": {
        "_gcl_au": "1.1.1234567890.1790000000"
      },
      "provenance": {
        "gclid": "ourRecord",
        "_gcl_au": "platformCookie"
      }
    },
    "consent": {
      "categories": {
        "analytics": true,
        "marketing": true
      },
      "mode": "lenient",
      "country": "US",
      "gpc": false,
      "policyVersion": 7
    },
    "value": 50,
    "currency": "USD",
    "userData": {
      "emailSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
      "phoneSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
      "phoneDigitsSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"
    },
    "submissionId": "ck9submission1",
    "delivery": {
      "google-ads": {
        "browser": "sent",
        "server": {
          "status": "sent",
          "attempts": 1,
          "sentAt": "2026-09-21T15:04:07.001Z",
          "lastAttemptAt": "2026-09-21T15:04:07.001Z"
        }
      },
      "ga4": {
        "browser": "sent",
        "server": {
          "status": "n/a",
          "attempts": 0
        }
      }
    },
    "status": "active",
    "adjustments": []
  }
}

{
  "name": "invalid",
  "message": "The query is not valid.",
  "data": {
    "errors": [
      {
        "name": "invalid",
        "code": 400,
        "path": "limit",
        "message": "A whole number from 1 to 500.",
        "data": {}
      }
    ]
  }
}

{
  "name": "unauthorized",
  "message": "X-Fetchski-Signature does not match this request.",
  "data": {}
}

{
  "name": "forbidden",
  "message": "This API key lacks the required scope: conversions:read.",
  "data": {}
}

{
  "name": "notfound",
  "message": "No event with this ID.",
  "data": {}
}

{
  "name": "conflict",
  "message": "An event with this ID is already stored with different content.",
  "data": {
    "eventId": "tenant-42:order:1234:purchase"
  }
}

{
  "name": "tooManyRequests",
  "message": "This API key’s rate limit is used up for this minute.",
  "data": {
    "retryAfter": 12
  }
}

Authorizations

Authorization

string

header

required

Paste your API key as the CMS showed it: fsk_<site>_<key id>_<secret> (issued under API Keys). ApiKey in front of it works too. Leave it empty to read as the public.

Scopes

conversions:write

Headers

X-Fetchski-Timestamp

string

Required for API keys. The Unix time in seconds when the request was signed; it must be within 5 minutes of the server clock.

Pattern: ^[0-9]{9,11}$

X-Fetchski-Signature

string

Required for API keys. v1= + the lower-case hex HMAC-SHA256, keyed with the API key’s signing secret (fss_…, shown once when the key is created or rotated), of <timestamp>.<METHOD>.<path including query>.<raw request body> — e.g. 1790000000.POST./api/v1/conversion-event/external.{"eventId":…}. Several comma-separated v1= values are accepted.

Pattern: ^v1=[0-9a-f]{64}(,\s*v1=[0-9a-f]{64})*$

Path Parameters

eventId

string

required

The event ID. Opaque, unique per site, stable. The CMS mints a UUID for events it originates; another system mints its own (e.g. tenant-42:order:1234:purchase). Forwarded unchanged to every ad platform as its de-duplication key.

Maximum string length: 128

Pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$

Example:

"tenant-42:order:1234:purchase"

Body

application/json

adjustmentId

string

required

Minted by the caller; a retry sends the same ID. Re-using it with different content is a 409.

Maximum string length: 128

Pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$

Example:

"tenant-42:order:1234:refund:1"

action

enum<string>

required

retract — it did not happen (full refund, cancellation); final. restate — a new value.

Available options:

retract,

restate

value

number

Required to restate.

Required range: x >= 0

currency

string

ISO 4217 code of value (restate only).

Pattern: ^[A-Z]{3}$

reason

string

Why, in your words (a refund, a cancellation).

Maximum string length: 500

occurredAt

string<date-time>

When the change happened. Defaults to now.

Response

The event after the adjustment.

applied

boolean

required

False when this adjustment ID was already applied.

event

object

required

One conversion occurrence. Fields the visitor’s consent did not allow are ABSENT, not empty. Never returned: the visitor’s IP address and user agent, outbox lease and retry bookkeeping.

Show child attributes

Example:

{
  "eventId": "b8f2c1de-4f5a-4c1e-9a53-0d6f2b7c1e9a",
  "conversion": {
    "id": "ckq1w2e3r4t5y6u7i8o9p0",
    "key": "quote-request",
    "title": "Quote request"
  },
  "trigger": { "type": "form", "ref": "ckformid123" },
  "source": "browser",
  "occurredAt": "2026-09-21T15:04:05.000Z",
  "recordedAt": "2026-09-21T15:04:05.412Z",
  "updatedAt": "2026-09-21T15:04:07.020Z",
  "page": {
    "url": "https://example.com/contact?gclid=Cj0KCQjw",
    "path": "/contact",
    "referrer": "https://www.google.com"
  },
  "visitorId": "0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c",
  "attribution": {
    "firstTouch": {
      "at": "2026-09-20T09:12:00.000Z",
      "path": "/",
      "landingUrl": "https://example.com/?gclid=Cj0KCQjw",
      "referrerOrigin": "https://www.google.com",
      "adPlatforms": ["google"],
      "campaign": {
        "utm_source": "google",
        "utm_campaign": "spring-sale"
      },
      "clickIds": { "gclid": "Cj0KCQjw" }
    },
    "adPlatforms": ["google"],
    "campaign": {
      "utm_source": "google",
      "utm_campaign": "spring-sale"
    },
    "clickIds": { "gclid": "Cj0KCQjw" },
    "browserIds": { "_gcl_au": "1.1.1234567890.1790000000" },
    "provenance": {
      "gclid": "ourRecord",
      "_gcl_au": "platformCookie"
    }
  },
  "consent": {
    "categories": { "analytics": true, "marketing": true },
    "mode": "lenient",
    "country": "US",
    "gpc": false,
    "policyVersion": 7
  },
  "value": 50,
  "currency": "USD",
  "userData": {
    "emailSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
    "phoneSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
    "phoneDigitsSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"
  },
  "submissionId": "ck9submission1",
  "delivery": {
    "google-ads": {
      "browser": "sent",
      "server": {
        "status": "sent",
        "attempts": 1,
        "sentAt": "2026-09-21T15:04:07.001Z",
        "lastAttemptAt": "2026-09-21T15:04:07.001Z"
      }
    },
    "ga4": {
      "browser": "sent",
      "server": { "status": "n/a", "attempts": 0 }
    }
  },
  "status": "active",
  "adjustments": []
}

cURL

curl --request POST \
  --url https://{host}/api/v1/conversion-event/{eventId}/adjust \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "adjustmentId": "tenant-42:order:1234:refund:1",
  "action": "restate"
}
'

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const adjustConversionEvent = await site.conversionEvents().adjustConversionEvent({ eventId: 'tenant-42:order:1234:purchase', adjustmentId: 'tenant-42:order:1234:refund:1', action: 'retract' });

use Fetchski\AttractCmsLaravel\Facades\Attract;

$adjustConversionEvent = Attract::conversionEvents()->adjustConversionEvent(eventId: 'tenant-42:order:1234:purchase', adjustmentId: 'tenant-42:order:1234:refund:1', action: 'retract');

{
  "applied": true,
  "event": {
    "eventId": "b8f2c1de-4f5a-4c1e-9a53-0d6f2b7c1e9a",
    "conversion": {
      "id": "ckq1w2e3r4t5y6u7i8o9p0",
      "key": "quote-request",
      "title": "Quote request"
    },
    "trigger": {
      "type": "form",
      "ref": "ckformid123"
    },
    "source": "browser",
    "occurredAt": "2026-09-21T15:04:05.000Z",
    "recordedAt": "2026-09-21T15:04:05.412Z",
    "updatedAt": "2026-09-21T15:04:07.020Z",
    "page": {
      "url": "https://example.com/contact?gclid=Cj0KCQjw",
      "path": "/contact",
      "referrer": "https://www.google.com"
    },
    "visitorId": "0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c",
    "attribution": {
      "firstTouch": {
        "at": "2026-09-20T09:12:00.000Z",
        "path": "/",
        "landingUrl": "https://example.com/?gclid=Cj0KCQjw",
        "referrerOrigin": "https://www.google.com",
        "adPlatforms": [
          "google"
        ],
        "campaign": {
          "utm_source": "google",
          "utm_campaign": "spring-sale"
        },
        "clickIds": {
          "gclid": "Cj0KCQjw"
        }
      },
      "adPlatforms": [
        "google"
      ],
      "campaign": {
        "utm_source": "google",
        "utm_campaign": "spring-sale"
      },
      "clickIds": {
        "gclid": "Cj0KCQjw"
      },
      "browserIds": {
        "_gcl_au": "1.1.1234567890.1790000000"
      },
      "provenance": {
        "gclid": "ourRecord",
        "_gcl_au": "platformCookie"
      }
    },
    "consent": {
      "categories": {
        "analytics": true,
        "marketing": true
      },
      "mode": "lenient",
      "country": "US",
      "gpc": false,
      "policyVersion": 7
    },
    "value": 50,
    "currency": "USD",
    "userData": {
      "emailSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
      "phoneSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514",
      "phoneDigitsSha256": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"
    },
    "submissionId": "ck9submission1",
    "delivery": {
      "google-ads": {
        "browser": "sent",
        "server": {
          "status": "sent",
          "attempts": 1,
          "sentAt": "2026-09-21T15:04:07.001Z",
          "lastAttemptAt": "2026-09-21T15:04:07.001Z"
        }
      },
      "ga4": {
        "browser": "sent",
        "server": {
          "status": "n/a",
          "attempts": 0
        }
      }
    },
    "status": "active",
    "adjustments": []
  }
}

{
  "name": "invalid",
  "message": "The query is not valid.",
  "data": {
    "errors": [
      {
        "name": "invalid",
        "code": 400,
        "path": "limit",
        "message": "A whole number from 1 to 500.",
        "data": {}
      }
    ]
  }
}

{
  "name": "unauthorized",
  "message": "X-Fetchski-Signature does not match this request.",
  "data": {}
}

{
  "name": "forbidden",
  "message": "This API key lacks the required scope: conversions:read.",
  "data": {}
}

{
  "name": "notfound",
  "message": "No event with this ID.",
  "data": {}
}

{
  "name": "conflict",
  "message": "An event with this ID is already stored with different content.",
  "data": {
    "eventId": "tenant-42:order:1234:purchase"
  }
}

{
  "name": "tooManyRequests",
  "message": "This API key’s rate limit is used up for this minute.",
  "data": {
    "retryAfter": 12
  }
}

Get started

How the API works

Pages & Site

Content

Media

Forms

Ads & Conversions

Analytics

Signing in (people)

Retract or restate a conversion event

Authorizations

Scopes

Headers

Path Parameters

Body

Response