AdonisJSIn your app
A function makes the call on the client it is given, so your code passes the real one and a test passes a fake.Add the function
src/attract/create-external-conversion-event.ts
Call it
A script makes the client once and calls the function:A route handler, a job or a queue worker calls it the same way.
scripts/create-external-conversion-event.ts
Terminal
match, strongest first (visitor ID, the fk_at token, _gcl_au, a click ID, hashed email / phone), and copies that visitor’s attribution onto the event. join.by in the answer says which matched. The producer’s own click IDs win over the visitor record’s; its browser IDs only fill gaps.
Consent. The producer’s consent flags govern what is sent about the fact (omitted flags are granted). A denial trims what is sent — no contact details or browser data, Google receives CONSENT_DENIED — but the conversion is always stored and delivered.
Browser context. Send the customer’s client (IP, user agent) and page.url as captured when they booked; with them the fact reaches Meta as a website event (de-duplicated against the pixel), without them as system_generated.
Idempotent on eventId. Posting the same fact again returns the stored event with created: false; the same ID with different content is a 409. Retry freely.
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.
Required parameters
Required parameters
One object, e.g.
createExternalConversionEvent({ eventId }); leave out the optional fields.Required. 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. Matches ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$. At most 128 characters.Required. A Conversion’s id or key (
GET /conversion/definitions); it must have a “Reported by another system” trigger. At most 128 characters.Optional parameters
Optional parameters
Optional. When it happened (not in the future). Defaults to now. Format: an ISO 8601 date and time.
Optional. Rounded to cents. Defaults to the Conversion’s value. At least 0.
Optional. Leave it out (or pass
null) and it isn’t sent: the site’s default applies. ISO 4217 code of value, e.g. USD. Matches ^[A-Z]{3}$.Optional. Leave it out (or pass
null) and it isn’t sent: the site’s default applies. What the CMS may join the fact to a visitor with, tried strongest first: visitorId, token (fk_at), gclAu, a click ID, then emailSha256 / phoneSha256. Hashes also travel with the conversion to the platforms (see UserDataHashes for the normalization).Optional. The customer’s ad-data consent as the producer knows it. Each flag defaults to the US-friendly value when omitted. A denial trims what is sent (no contact details or browser data; Google receives CONSENT_DENIED); the conversion itself is always stored and delivered.
Optional. Leave it out (or pass
null) and it isn’t sent: the site’s default applies. The customer’s browser as captured WHEN THEY BOOKED (not the server confirming later). With a user agent and a page URL the fact reaches Meta as a website event; without, as system_generated. Kept only until delivery is finished, never returned.Returns
Returns
A
CreateExternalConversionEventResponse. The stored event. created is false when this event ID was already stored with the same content. Read its properties (createExternalConversionEvent.created): each says whether the site always sends it.Errors
Errors
Nothing to catch: the SDK retries what is safe, and throws the rest as the classes below; catch only what you want to react to (see Errors and testing).
The request is not valid.
data.errors lists each problem with the path of the parameter or body field it concerns.Retried first: No. Read: errors (field → messages), siteMessage.The API key is missing, malformed, unknown, disabled, expired or archived (
invalid), or a request that must be signed — by the route, or by the key’s own signing mode — has a missing, stale or wrong signature (an upload signs its SHA-256, declared in X-Fetchski-Content-SHA256, in the body’s place) (unauthorized).Retried first: No. Read: siteMessage, errorName, data.The API key lacks the scope this route needs (the message names it), or the key is used from an address outside its allowlist.Retried first: No. Read:
siteMessage, errorName, data.Nothing with this identifier — or the caller may not use the Data API at all (anonymous visitors and non-admin sessions get 404 so the API is not advertised). A write while conversion tracking is switched off also answers 404.Retried first: No. Read:
siteMessage, errorName, data.The identifier was already used with different content (an event ID re-posted with a changed fact, an adjustment ID re-used), or the event is retracted.Retried first: No. Read:
siteMessage, errorName, data.The key used up its reads- or writes-per-minute limit (set per key; defaults 600 / 120). Still, after the client’s own waits and retries.Retried first: Yes: the client waits
Retry-After (1 s when absent; over 60 s it gives up at once) and retries, up to retries times (2 by default). Read: retryAfter (seconds, or null), siteMessage.The site failed (or something in front of it did). Its logs say why.Retried first: No: a write may have landed. Read:
siteMessage, errorName, data.No answer: DNS, a refused connection, TLS, or the timeout (15 s per attempt by default).Retried first: Only when nothing reached the site (
neverConnected()); never after a timeout, when it may have landed. Read: reason, neverConnected.The client refused to send it (e.g. a path segment of
..); the site never saw it.Retried first: No. Read: reason (what to change).Any other status, or a success whose JSON doesn’t match this SDK version’s types (update the SDK).Retried first: No. Read:
reason, status.sites.forSite('acme') named a slug your sites (createSiteClients()) don’t have.Retried first: No: nothing was sent. Read: message, slug.Behavior
- Access: an API key with
conversions:write— or its group masterads:all, oradmin:all— or a signed-in user holding theconversion-events:writepermission. Anonymous callers get 404. - Rate limit: the key’s own writes-per-minute limit, set when the key is created (default 120); over it, 429 with
Retry-After. The client waits and retries for you; you seeRateLimitedonly if that runs out. - Retries: a write is sent again only after a 429 (refused before it acted) or when it never reached the site. After a timeout or a 5xx it may have landed: check before you send it again.
- Timeout: 15 s per attempt by default; raise
timeout(milliseconds) on the client for longer.
Test it
It calls the function above with a fake client: the fake answers every call with a valid example, so nothing leaves your machine and no settings or key are needed. Run it withnode --test.
tests/conversionEvents-createExternalConversionEvent.test.ts
conversionEvents.createExternalConversionEvent with factories.CreateExternalConversionEventResponse({...}), the fields you give over a valid example (nested ones too).
tests/conversionEvents-createExternalConversionEvent-answer.test.ts
Related
List conversion events (incremental sync)
site.conversionEvents().listConversionEvents()Get one conversion event
site.conversionEvents().getConversionEvent()Retract or restate a conversion event
site.conversionEvents().adjustConversionEvent()POST /conversion-event/external
The endpoint this calls, in the API reference: the HTTP request and answer, and every rule the site checks.