Installation

Requirements

• CS-Cart and Multi-Vendor 4.17.2 – 4.21.x (tested on CS-Cart 4.17.2, Multi-Vendor 4.17.2 and Multi-Vendor 4.21.2 with PHP 8.3).
• PHP 7.4 – 8.3 (as supported by your CS-Cart version) with the curl and json extensions (standard on CS-Cart hosting).
• A Meta Business portfolio with a pixel (dataset) in Events Manager. You need admin access to the pixel to create a Conversions API access token.
• Optional, recommended: a cron job (see Configuration).

Install the add-on

1. Download kv_meta_conversions_api-<version>.zip from your Kavio Labs or CS-Cart Marketplace account.
2. In the admin panel, open Add-ons → Manage add-ons.
3. Click the gear button, choose Manual installation and upload the archive.
4. Find Server-Side Tracking for Meta Pixel and Conversions API and make sure its status is Active.
5. If the installer warns about another Meta pixel integration, disable it (see FAQ). The core Facebook pixel add-on loads the same pixel without event IDs, so events would be counted twice.
6. On the License tab of the settings, enter your license key and save. If you bought the add-on on the CS-Cart Marketplace and entered the license number in Add-ons → Manage add-ons, you can skip this step. Until a key is verified, the add-on works for 14 days (see License).

The installer creates three tables (cscart_kv_meta_capi_events, cscart_kv_meta_capi_orders, cscart_kv_meta_capi_vendors) and a random catalog feed key. If the GDPR add-on is active, it also adds Meta Pixel and Conversions API to the cookie consent dialog.

Set up Meta Events Manager

These steps take about ten minutes. Meta renames menu items from time to time, but the flow stays the same.

1. Find or create the pixel (dataset)

1. Open Meta Events Manager and select your business portfolio.
2. In the left menu click Data sources.
3. Select your pixel. To create one, click Connect data, choose Web, name the dataset and click Create. When Meta offers setup options, choose to set it up manually. Do not use a partner integration, because this add-on is the integration.
4. Open the Settings tab and copy the Pixel ID (also called Dataset ID). It is a number of 15 or 16 digits.
5. In CS-Cart, open the add-on settings, General tab, and paste it into Pixel ID (dataset ID). Save.

2. Create a Conversions API access token

1. In Events Manager, still on the pixel’s Settings tab, scroll to Conversions API.
2. Under Set up manually, click Generate access token and confirm.
3. Copy the token right away. Meta shows it only once.
4. In CS-Cart, paste it into Conversions API access token and save.

The token belongs to the pixel and does not expire unless you revoke it. Treat it like a password.

3. Test before you go live

1. In Events Manager, open the Test events tab of the pixel and copy the test code (for example TEST12345).
2. In CS-Cart, enter it as Test event code and save.
3. On the General tab click Send a test event. A green message confirms that Meta accepted the event, and a PageView appears in Test events under Server.
4. Open your storefront in another browser, accept the marketing cookies, view a product and add it to the cart. In Test events you should see each event twice, once from Browser and once from Server, marked as Deduplicated.
5. Optional: place a test order with an offline payment method. Purchase arrives from the browser on the thank-you page and from the server when the order reaches a purchase status.
6. Clear the Test event code and save. While it is set, server events go to Test events only and are not used for reporting or ads.

4. Check the results after go-live

• Overview tab: browser and server events should both show traffic within an hour.
• Event match quality (Overview → click an event): with advanced matching on, purchases usually reach “Good” or “Great”. Logged-in customers and checkout data contribute email, phone, name and address.
• Diagnostics tab: Meta lists problems such as missing deduplication or wrong parameters here. With this add-on, browser and server events share event_id and event_name, which is what Meta checks.

5. Connect the catalog (optional, for Advantage+ catalog ads)

1. Open Commerce Manager and select or create a catalog (type E-commerce).
2. Go to Catalog → Data sources → Add items → Data feed and choose Scheduled feed.
3. Paste the CSV or XML URL from the add-on’s Catalog feed tab, choose a daily schedule and the currency of the feed.
4. In Events Manager, open the catalog’s Events settings and connect your pixel to the catalog. Meta then matches content_ids from ViewContent, AddToCart and Purchase to the catalog items. The add-on uses the same IDs in both places.

Update

1. In Add-ons → Manage add-ons, upload the new package with Manual installation.
2. CS-Cart sees that the add-on is already installed and offers two ways:
   • Use the dangerous way (tick I know the risks… first) replaces the add-on files and keeps all add-on data. Choose this one. Despite its name, it is the normal way to upgrade this add-on.
   • Use the safe way uninstalls the add-on first. That deletes the settings, the event log and the vendor pixels, then installs the new version from scratch.
3. Open any page of the admin panel. On that first page view the add-on completes the upgrade by itself. It adds any new database tables and columns, new settings (with their default values), new language variables and e-mail templates. It also updates the version shown in Add-ons → Manage add-ons. Existing data and setting values are kept.

When files are uploaded over an installed add-on, CS-Cart resets the add-on’s language variables to the texts in the package. If you edited them in Administration → Languages → Translations, apply your edits again.

If you bought the add-on on the CS-Cart Marketplace, you can also upgrade it in Administration → Upgrade center. Steps 2 and 3 then happen automatically. The Upgrade center closes the storefront while it works. Reopen the storefront afterwards; the e-mail the Upgrade center sends links to the right page.

Upgrading to 1.1.0: this version adds the license check. After the upgrade the add-on keeps working for 14 days; enter your license key on the License tab of the settings within that time.

See the CHANGELOG for what changed in each version.

Uninstall

Open Add-ons → Manage add-ons, click the add-on’s gear button and choose Uninstall. This removes the settings, language variables, the three tables (event log, order context, vendor pixels) and the consent service in the GDPR cookie dialog. The _fbp, _fbc and kv_meta_consent cookies already in visitors’ browsers expire on their own.