Download the PHP package axitrace/php-sdk without Composer

AxiTrace PHP SDK

Official PHP SDK for the AxiTrace event tracking API. Track page views, e-commerce events, form submissions, and more.

Requirements

• PHP 7.4 or higher
• ext-json
• ext-curl
• Guzzle HTTP client 7.0+

Installation

Install via Composer:

Quick Start

Configuration

Basic Configuration

Advanced Configuration

Configuration from Environment

Authentication

The SDK uses API key authentication. Your secret key should start with:

• sk_live_ for production
• sk_test_ for testing

Keep your secret key secure and never expose it in client-side code.

Events

All events are sent using $axiTrace->events()->send($event).

Custom Event

Merchant-defined custom events go through a DEDICATED endpoint (POST /v1/custom-events) and require PRE-REGISTRATION: the event key must be defined in the workspace's Custom Events registry (AxiTrace admin panel, workspace Settings, Advanced) BEFORE it can be sent. An unknown name is rejected by the ingestion with HTTP 400 and the stable message prefix unknown custom event: <name>.

The endpoint is the ONLY /v1 endpoint with event_id deduplication: sending the same event_id twice is answered 202 duplicate, so the event is safe to retry. Pass your own event_id (any non-empty string, at most 100 characters) to make retries idempotent.

The key pattern is [a-z][a-z0-9_]{0,39} (lowercase letters, numbers and underscores, starting with a letter, GA4-compatible). Note that the once_per_page_view throttle behaves as unlimited for server callers; the server applies only once_per_session and every_n_seconds.

Page View

Product View

Add to Cart

Remove from Cart

Begin Checkout

Add Shipping Info

Add Payment Info

Transaction (Purchase)

Or, using the AxiTrace facade (recommended - it also applies visitor identifiers and attribution data automatically):

Buyer match keys (Event Match Quality)

If your shop holds the buyer's billing or shipping details, pass them - this is the single largest available improvement to Purchase Event Match Quality:

Pass plain text - hashing happens server-side (Meta CAPI fn/ln/ct/st/zp/ country, TikTok first_name/last_name/city/state/zip_code/country). camelCase spellings are accepted too (firstName, lastName, postalCode, zipCode, province). Empty and whitespace-only values are dropped rather than sent as blank match keys.

Requires SDK 1.5.0 or newer; older versions silently ignored everything except email.

Products and eventSalt

Two things caused the most support time for real integrations, so the SDK now guards against both locally, before any HTTP call is made:

1. finalUnitPrice shape. Write it as a bare number - 'finalUnitPrice' => 279.99 - the SDK normalizes it into {amount: 279.99, currency: <transaction currency>} for you. An already-shaped ['amount' => 279.99, 'currency' => 'USD'] also works if a line item needs a different currency. Anything that cannot be coerced to a number throws a ValidationException immediately, with the field path, what was received, and a correct example - instead of an opaque 400 Invalid JSON from the API.
2. quantity as a numeric string. 'quantity' => '2' (common when the value comes from $_POST or a CSV import) is cast to an int automatically.

You can also pass AxiTrace\Model\Product instances instead of arrays - sku falls back to the item ID, name, finalUnitPrice and quantity are read from the model:

eventSalt is the deduplication guard for /v1/transaction - unlike the browser /track endpoint, this endpoint performs no server-side dedup. If a call can ever be retried (a payment webhook firing twice, a job retrying after a timeout), set eventSalt to something stable across retries - the order ID is the recommended value. Omitting it behaves exactly as before (no eventSalt sent).

Subscribe

Start Trial

Search

Form Submit

View Item List

Select Item

User Identification

The SDK supports multiple user identification methods:

At least one identifier is required for all events.

Ad click ids and browser ids

Inside a web request the SDK reads the ad identifiers itself when it is created, and sends them in the params of every event:

The JavaScript SDK keeps a click id from the landing page URL in a first-party cookie, so a conversion sent from a later request (a form POST, a checkout step) still carries the click that brought the visitor. A click id in the current URL wins over the cookie, and a click older than the window above is not sent. The platforms' own cookies are read only when neither the URL nor the AxiTrace cookie has the click id, and never written. A value you pass yourself, in the event params or through setAttributionParams(), wins over both.

Sending events outside a web request (queue, cron, webhook)

transaction() and every other AxiTrace facade method resolve the visitor via getVisitorId()/getSessionId(), which fall back to reading the vt_vid/vt_sid cookies through CookieHelper. Outside a normal web request - a queue worker, a cron job, a payment webhook handler run from the CLI - $_COOKIE is empty. The event is still accepted by the API (HTTP 200), but it ships with no client identifier, no session ID, and your server's IP/user agent instead of the visitor's. Nothing errors - the conversion is just silently unattributed and never linked back to the visitor's session.

The fix is withContext(): capture the visitor's vt_vid/vt_sid cookies, IP, and user agent at the point the visitor is actually on your site (e.g. store them on the order/payment record at checkout), then replay them before sending the event from the queue/cron job:

The ad click ids and browser ids (see "Ad click ids and browser ids" above) are not there either. Store $axiTrace->getAttributionParams() on the order during the visitor's request and pass it to setAttributionParams() in the job, before sending the event.

Dating a late transaction: recorded_at

A transaction sent later than the order was placed - from a queue that was backed up, a cron job that re-sends failed deliveries, a backfill - is dated at the moment it reaches AxiTrace unless you say otherwise, so it lands on the wrong day in reports and reaches the ad platforms as a fresh conversion. Pass the time the order was placed (SDK 1.8.0+):

• It is sent as recordedAt in UTC with millisecond precision; a time in the future is replaced by the server's clock. An unreadable string throws ValidationException before any request.
• Meta accepts conversions up to 7 days old. An older order is still recorded in AxiTrace and forwarded to platforms that accept older conversions (Google Ads: 90 days), but not to Meta.
• Keep event_salt set to your order id: a re-sent order that already arrived within the last 30 days is then ignored instead of counted twice.

withContext() accepts (all optional): clientId (or customId as an alias), sessionId, ip, userAgent, consent. It applies the corresponding set*() calls and returns $this for chaining. See examples/queue-transaction.php for a full runnable example.

Profit tracking: cost fields and refunds

When profit tracking is enabled for your workspace, AxiTrace computes the profit of every order and reports POAS (profit on ad spend) next to ROAS. Send what each order cost you and AxiTrace uses it instead of the cost rules set in the admin panel (SDK 1.9.0+). Every field is optional: a transaction without them is sent exactly as before.

• Costs must be in the revenue currency and at least 0; anything else throws ValidationException before any request is made.
• Costs are accepted only with your secret key, which this SDK always uses. Never send them from a browser: AxiTrace drops cost fields that arrive without the secret key.
• unitCost and externalId travel only with a transaction. Product::toArray(), used by cart and catalog events, never includes them.

Refunds and cancellations

Send a refund or a cancellation of an order you sent before. It reduces that order's profit and POAS; revenue and ROAS reports do not change.

Leave the lines out for a refund that returns no products, such as a goodwill or shipping refund. The same request can be built with AxiTrace\Model\Event\RefundEvent (addLine(), setCancellation(), setRefundedAt()) and sent with $axiTrace->track($event). Refunds go to POST /v1/refund, which accepts only the secret key.

Cookie consent

If your site asks visitors for cookie consent, tell AxiTrace what they decided. Pass the state through withContext() and it travels as params.consent on every event you send afterwards:

Accepted values, and nothing else:

Any other value throws AxiTrace\Exception\ValidationException:

Omitting the consent key sends no params.consent at all, which the server reads as an unknown state. Consent is remembered on the SDK instance, so set it before the first event of the request and every later event carries it.

Facebook Conversion API Integration

Track events for Facebook CAPI:

Customer Data

Add customer data for enhanced tracking:

Phone number

phone is one of the client identifiers the ingestion API reads for CAPI/CRM matching - but it must be set on the client identity, not the generic params bag. For TransactionEvent and FormSubmitEvent (the events that carry a client identity), use setClientPhone():

AbstractEvent::setPhone() still exists and still works exactly as before (it writes params.phone), but it is deprecated for this purpose - the API does not read params.phone for identity matching, only client.phone. It remains available for events that don't carry a client identity and for backward compatibility.

Error Handling

Product Model

The Product model supports all standard e-commerce fields:

Creating Products from Arrays

Batch Sending

Send multiple events at once:

Examples

See the examples/ directory for complete usage examples:

• basic-usage.php - Page views and product views
• ecommerce-tracking.php - Full e-commerce flow, including a transaction with eventSalt and correctly-shaped products
• form-tracking.php - Forms, subscriptions, trials, and search
• catalog-tracking.php - Item lists, selecting an item, and removing from cart
• queue-transaction.php - Sending a transaction from a queue/cron job with withContext()

Testing

Run the test suite:

Run integration tests (requires API key):

License

MIT License. See LICENSE file for details.

Support

• Documentation: https://axitrace.com/docs
• Issues: https://github.com/axitrace/axitrace-php-sdk/issues