Skip to main content

In your app

A controller answers a route on your app: it calls adjustConversionEvent() and returns the answer.

Add the controller

app/Http/Controllers/AdjustConversionEventController.php
The other values are the example’s: take yours from the request, a form or your database.

Add the route

routes/web.php
It acts with your key’s access, so auth lets only your signed-in users reach it.

Call it

Your own page’s form or script sends POST /conversion-event/tenant-42:order:1234:purchase/adjust (a form adds @csrf, as every web route checks it), and gets back its answer as JSON. Test it, below, calls it.
To keep the call in an Action instead, this writes app/Actions/Attract/AdjustConversionEvent.php (an invokable Action that calls adjustConversionEvent()) and its test under tests/Feature/Actions/Attract/ (Pest when your app has it):
Terminal

Call it from the terminal

Terminal
It calls adjustConversionEvent() on your default site and prints its answer as JSON. It writes, so it asks first: add --force to skip the question in a script. See Call any method from the terminal for every argument type. 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

Named arguments, e.g. adjustConversionEvent(eventId: …); leave out the optional ones.
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.
Enums\Action|string
required
Required. retract — it did not happen (full refund, cancellation); final. restate — a new value. One of retract, restate.
?float
Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Required to restate. At least 0.
?string
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
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.
\DateTimeInterface|string|null
Optional. When the change happened. Defaults to now. Format: an ISO 8601 date and time.
An AdjustConversionEventResponse (Fetchski\AttractCmsLaravel\Data\AdjustConversionEventResponse). The event after the adjustment. Read its properties ($adjustConversionEvent->applied): each says whether the site always sends it.
bool
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 Laravel logs and renders the rest (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
Attract::site('acme') named a slug that isn’t under sites in config/fetchski-attract.php.Retried first: No: nothing was sent. Read: getMessage(), $e->slug.
setup
The site’s config entry is wrong: no url, a malformed api_key, a key filed under another slug, or no default site.Retried first: No: nothing was sent. Read: getMessage() (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 in config/fetchski-attract.php for longer.

Test it

It calls the route above with the SDK faked: the fake answers every call with a valid example, so nothing leaves your machine and no config or key is needed. Save it as tests/Feature/AdjustConversionEventTest.php, then run your tests:
tests/Feature/AdjustConversionEventTest.php
Terminal
Answer with your own values: fake conversionEvents.adjustConversionEvent with AdjustConversionEventResponse::factory()->make([...]), the fields you give over a valid example (nested ones too).
tests/Feature/AdjustConversionEventAnswerTest.php

List conversion events (incremental sync)

Attract::conversionEvents()->listConversionEvents()

Get one conversion event

Attract::conversionEvents()->getConversionEvent()

Post a conversion another system saw

Attract::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.