Skip to main content

In 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/adjust-conversion-event.ts
The other values are the example’s: take yours from the request, a form or your database.

Call it

A script makes the client once and calls the function:
scripts/adjust-conversion-event.ts
Terminal
A route handler, a job or a queue worker calls it the same way.
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. 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

One object, e.g. adjustConversionEvent({ eventId }); leave out the optional fields.
string
required
Required. The event ID. Matches ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$. At most 128 characters.
string
required
Required. Minted by the caller; a retry sends the same ID. Re-using it with different content is a 409. Matches ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$. At most 128 characters.
Action
required
Required. retract — it did not happen (full refund, cancellation); final. restate — a new value. One of retract, restate.
number | null | undefined
Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Required to restate. At least 0.
string | null | undefined
Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. ISO 4217 code of value (restate only). Matches ^[A-Z]{3}$.
string | null | undefined
Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Why, in your words (a refund, a cancellation). At most 500 characters.
Date | string | null | undefined
Optional. When the change happened. Defaults to now. Format: an ISO 8601 date and time.
An AdjustConversionEventResponse. The event after the adjustment. Read its properties (adjustConversionEvent.applied): each says whether the site always sends it.
boolean
Always sent. False when this adjustment ID was already applied.
ConversionEvent
Always sent. A ConversionEvent. 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.
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).
400
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.
401
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.
403
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.
404
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.
409
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.
429
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.
5xx
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
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.
not sent
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
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.
setup
sites.forSite('acme') named a slug your sites (createSiteClients()) don’t have.Retried first: No: nothing was sent. Read: message, slug.
setup
The client’s settings are wrong: no FETCHSKI_ATTRACT_URL (or baseUrl), or a malformed API key.Retried first: No: nothing was sent. Read: message (what to fix).

Behavior

  • 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.
  • 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 see RateLimited only 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 with node --test.
tests/conversionEvents-adjustConversionEvent.test.ts
Answer with your own values: fake conversionEvents.adjustConversionEvent with factories.AdjustConversionEventResponse({...}), the fields you give over a valid example (nested ones too).
tests/conversionEvents-adjustConversionEvent-answer.test.ts

List conversion events (incremental sync)

site.conversionEvents().listConversionEvents()

Get one conversion event

site.conversionEvents().getConversionEvent()

Post a conversion another system saw

site.conversionEvents().createExternalConversionEvent()

POST /conversion-event/{eventId}/adjust

The endpoint this calls, in the API reference: the HTTP request and answer, and every rule the site checks.