TikTok Events API on Magento 2: server-side setup and the event-name churn

TikTok stopped documenting CompletePayment and PlaceAnOrder, so the weltpixel/module-ga4-tiktokss addon added Purchase in v1.15.7 while keeping the older names available for continuity. The setup itself has not moved: it requires the GA4 PRO extension, a configured client-side TikTok pixel, a pixel ID, and an Events API access key.

TL;DR

The TikTok Events API is one of the calmer server-side integrations to run on Magento 2. There is no version drama, because no versioned Events API exists to begin with, and TikTok's April 2026 standard-events page lists 20 standard events [1]. What has moved is naming. TikTok quietly stopped documenting the purchase-side event names that Magento setups were built on, which left merchants with a live configuration referencing a name that no longer appears in TikTok's own documentation. The addon's answer was to add Purchase and keep the older names sendable. This article walks that history in order, covers the two optional parameters TikTok's parameter page picked up in March 2026, and shows the three places you can prove it works.

Key Takeaways

• TikTok removed CompletePayment and PlaceAnOrder from its documentation. The addon added Purchase in v1.15.7 and can still send the older names to keep a data series continuous [2].
• CompletePayment was added earlier, in v1.14.19, because certain Ads configurations may require it [2]. Both facts are true at once, which is why the purchase-side naming is a decision you make deliberately.
• TikTok's parameters page, updated March 2026, lists two optional additions: attribution_share and customer_type (new versus returning). value is required for ROAS and value-based optimization, and currency is required for ROAS [1].
• TikTok has never versioned the Events API, so any guide naming a version is describing something that does not exist [1].
• The addon is the TikTok Events API addon for Google Analytics 4 PRO (weltpixel/module-ga4-tiktokss), released November 14, 2024, and it needs the GA4 PRO extension plus a client-side TikTok pixel already configured [2].
• Verification lives in three places you already control: test mode, the tiktok-api.log file, and the admin payload log viewer.
• Installation has been Composer-only since v1.16.0 (January 7, 2026) [2]. Instructions that tell you to copy files into app/code describe a path that no longer applies.

The event-name churn, in order

An integration guide tends to present an event list as if the list were a fixed property of the platform. TikTok's purchase-side naming has been anything but fixed, and the order of changes is the part worth having in front of you.

Read that table twice and the awkward middle row is the whole story. A name the addon had deliberately added, because certain Ads configurations may require it [2], stopped appearing in TikTok's documentation. The addon did not respond by ripping out the old names, which would have put a hard break in every merchant's historical series. It added the new name alongside.

So if you are looking at a Magento admin screen with a purchase-side event name that you cannot find on TikTok's help site, you have not misconfigured anything. You are looking at the older half of a transition.

One practical consequence: the event list printed in the addon's configuration documentation is behind the changelog. The changelog is the newer record, and the admin UI on your own installation is newer still. Treat any event list you read anywhere, this article included, as documented as of v1.17.0, and confirm the current set in your admin before you build reporting on top of it.

Which purchase event should you be sending?

Ask TikTok what it currently documents and the answer is Purchase. Ask what your existing campaigns are optimizing against and the answer might still be CompletePayment.

The criteria that decide it:

• If your TikTok campaigns are new, or you are rebuilding optimization events anyway, use Purchase. It is the name TikTok documents now, and there is no reason to inherit a deprecated one.
• If you have live campaigns optimizing against CompletePayment and a conversion history TikTok is using for optimization, changing the name resets that. The continuity option exists precisely for this case.
• If a specific Ads configuration in your account explicitly asks for CompletePayment, that requirement wins over documentation tidiness until TikTok's own interface stops asking for it.

There is a version of this question I cannot answer for you from documentation: whether TikTok's optimization treats a renamed event as continuous with its predecessor. TikTok has not published that, and I am not going to guess at it in an article. Test it on one campaign before you do it on all of them.

What TikTok added to the parameter list in March 2026

TikTok's April 2026 standard-events page lists 20 standard events [1], and the endpoint consolidation that reshaped the API happened back in November 2023 [1]. Against that stability, the March 2026 parameters-page update is the fresh material.

Two optional parameters appeared:

attribution_share is an optional parameter TikTok added in its March 2026 parameters update.

customer_type distinguishes new from returning customers. That one maps directly onto something Magento already knows at order time, and it is the parameter most likely to change how you read a TikTok report, because new-customer acquisition cost and blended cost are different numbers that often get compared as if they were the same one.

Both are TikTok-side parameters; the addon's documentation does not describe sending them.

Two requirements sit alongside them, and both are easy to miss because they are conditional. value is required if you want ROAS reporting or value-based optimization. currency is required for ROAS [1]. A Purchase event without them still arrives. It just cannot be optimized against in the way you probably assumed it could.

This is where the grand-total settings in the GA4 PRO configuration start to matter, since they decide whether the value you send includes tax and shipping. Send a value that excludes both and TikTok's ROAS will be consistently lower than your Magento sales report, and the gap will look like a tracking bug rather than a settings choice. Our write-up on which ecommerce events the Google Analytics 4 extension tracks covers the event and value model the addons inherit.

How do the pixel and the Events API avoid double counting?

Two facts here, and they belong apart.

TikTok's own recommendation is to run the pixel and the Events API together and rely on deduplication for the overlap [1]. That is TikTok's documented position, and it is the reason the addon requires a client-side pixel as a prerequisite rather than replacing it.

Our addon documentation says TikTok Ads Manager should have built-in functionality to avoid data duplication, and it does not document an event_id implementation, so treat the pairing as something to confirm against your own order volume in TikTok Ads Manager rather than something a feature list guarantees.

If you switch on the option to send the same events via the frontend as well, that confirmation step is not optional homework. It is how you find out whether one order is being counted once or twice, and it takes one day of order data to answer.

Setup, and the three places you can prove it works

The configuration itself is short, which is why the history comes first.

The addon requires Google Analytics 4 PRO (the addon's product page currently states v1.17.0; the original minimum documented was v1.14.9) [2], plus a client-side TikTok pixel that is already configured.

The pixel ID comes from TikTok Ads Manager under Tools, then Events, then Data Sources. The Events API access key is the second value you need. Both go into the addon's configuration in the Magento admin, along with the customer-group filter if you exclude wholesale or staff groups, and multi-property settings if you report into more than one TikTok asset [2].

Then prove it, in this order:

Test mode. Switch it on, paste the test code, and place an order. This answers "did anything leave the server at all" in about two minutes, without contaminating live data.

tiktok-api.log. The addon writes requests and responses to it. An authentication failure, a rejected payload, and silence all look different from each other in a log file, whereas from the TikTok interface they can all look like nothing happened.

The admin payload log viewer. Payloads are readable from the Magento admin, not only over SSH. On a managed host with no shell access, that is the difference between debugging this yourself and filing a ticket with your host.

Run all three once. After that, the log file alone usually tells you what you need.

Orders that leave an excluded status later get picked up and pushed by cron, the shared behavior across the addon family. If an order shows up in TikTok hours after it was placed, that is the catch-up working, not a delay to investigate.

Has the match data actually improved?

Yes, across several dated releases [2].

Version 1.14.19 added email and phone to server-side events when those values are available. Version 1.16.1 persisted hashed email, phone, and address so that returning customers carry identifiers on later events instead of arriving as strangers each visit. Separate fixes handled two failure modes that are invisible until you look for them: reading the visitor's real IP when the store sits behind a CDN, since the CDN's own IP is worthless for matching, and correcting the user agent on cron-pushed events.

I am not printing a match-quality target here. The scores that circulate as "the number you should hit" are not published as thresholds by TikTok, and repeating one would be inventing a benchmark.

What your Magento version has to do with any of this

Less than you would expect for the server-side events, and more than you would expect for the pixel next to them.

Server-side sends do not touch the browser, so Content Security Policy changes cannot stop them. The client-side pixel is a different matter. Payment pages have run CSP in restrict mode since Magento 2.4.7 for PCI DSS 4.0 (other pages stay in report-only mode), 2.4.8 added region1.analytics.google.com to the allowed list when Google Analytics is enabled, and 2.4.9, released May 12, 2026, made the Google Analytics module's CSP whitelist independent of the Adwords module [3]. If a browser event stops firing right after an upgrade, start with CSP.

There is a patching detail worth flagging, because it is recent. Adobe now ships monthly isolated security patches between the numbered -pN releases. They are security-only, non-cumulative, and sequential, which means the August 11, 2026 critical patch requires the July 2026 patch first [4]. Our guide on updating Magento 2 and installing the latest security patches covers the mechanics.

The extension family's documented Magento range is 2.3.0 through 2.4.9, and as of GA4 PRO v1.17.3 (August 3, 2026) the documented ceiling is 2.4.9 with PHP 8.5 [5]. Our earlier walkthrough, How to integrate Magento 2 with the TikTok Pixel Events API, is still the fuller tour of the admin screens, but two things in it have aged: the compatibility range stops at 2.4.7-p3, and the install step describes copying files into app/code. Installation has been Composer-only since v1.16.0 [2].

FAQ

Is there a version of the TikTok Events API I should be targeting?

No. TikTok has never versioned the Events API, so there is no v2 or v3 to target [1]. The endpoint consolidation that people sometimes remember as a version change happened in November 2023 and is long settled.

Do I still need the client-side TikTok pixel?

Yes. The addon requires a configured client-side pixel as a prerequisite and adds server-side sending alongside it [2]. TikTok also recommends running both together with deduplication [1].

Why does my admin show an event name I cannot find in TikTok's documentation?

Because TikTok removed CompletePayment and PlaceAnOrder from its docs while the addon kept them sendable for continuity, and added Purchase in v1.15.7 [2]. Your configuration is on the older half of that transition, not broken.

Which events does the addon send server-side?

As documented as of v1.17.0, coverage spans purchase, the payment and checkout steps, cart and wishlist additions, search, and content views. The configuration documentation lags the changelog on the purchase-side names, so confirm the current list in your own admin rather than from any published list.

Do I need to send value and currency on every event?

Only if you want the reporting that depends on them. value is required for ROAS reporting and value-based optimization, and currency is required for ROAS [1]. Events without them are accepted and simply cannot support those two things.

If you are running Magento 2 and want TikTok server-side events handled inside the Magento admin rather than in a separate tagging server, the Google Analytics 4 PRO extension with server-side tracking is the base the TikTok Events API addon installs on top of.

Before you change anything else, open your addon configuration and write down which purchase-side event name it is currently sending. Every decision above depends on that one string, and it is easy to never check.

Sources

1. TikTok Ads Manager Help Center, Events API documentation: the "Events API parameters" page (updated March 2026, covering attribution_share, customer_type, and the value and currency requirements), the "Standard events" reference (20 standard events, April 2026), and the "Pixel and Events API" guidance recommending both be run together with deduplication.
2. WeltPixel TikTok Events API Addon for Google Analytics 4 PRO, user guide and changelog, v1.17.0, May 18, 2026 (addon released November 14, 2024). https://weltpixel.com/products/tiktok-pixel-server-side-addon
3. Adobe Experience League, Adobe Commerce 2.4.9 release notes (released May 12, 2026) and 2.4.8 release notes (released April 8, 2025). https://experienceleague.adobe.com/en/docs/commerce-operations/release/notes/adobe-commerce/2-4-9
4. Adobe security bulletin APSB26-92 (August 11, 2026) and Adobe Commerce knowledge base article ka-40380 on isolated security patches.
5. WeltPixel Google Analytics 4 PRO extension for Magento 2, user guide and changelog, as of v1.17.3 (August 3, 2026). https://weltpixel.com/products/magento-2-google-analytics-4-ga4-extension-with-gtm-server-side-tracking