Facebook CAPI Server-Side Integration for osCommerce Purchases | Facebook CAPI Server-Side for osCommerce Purchases

Use Case:
You’re running Meta (Facebook/Instagram) ads for your osCommerce store and want to:

Improve Purchase attribution
Send events server-to-server
Respect privacy and consent
Reduce reliance on client-side pixels

✅ Prerequisites

Tool	Purpose
Facebook Business Manager	Access to Pixel & CAPI Token
GTM Web Container	To send event data from client
GTM Server Container	To send Purchase data to Meta
Access to osCommerce	For injecting dataLayer code

🚀 Step-by-Step Implementation

🔹 1. Get Your Facebook CAPI Access Token

Go to Facebook Events Manager
Select your Pixel > Settings
Scroll to “Conversions API” > Generate Access Token
Copy and store the token securely

🔹 2. Set Up GTM Server-Side (sGTM)

Create a Server container in GTM
Deploy it via Google Cloud App Engine or Cloud Run

gcloud app deploy

Note your sGTM endpoint (e.g., https://gtm.yourdomain.com)

🔹 3. Add GTM Web Container to osCommerce

Paste the GTM Web snippet into:

<head>: /includes/template_top.php
<body>: noscript iframe after opening <body>

🔹 4. Inject Purchase Event on `checkout_success.php`

osCommerce PHP Template Code:

<?php
$order_query = tep_db_query("SELECT orders_id, order_total FROM " . TABLE_ORDERS . " WHERE customers_id = '" . (int)$customer_id . "' ORDER BY orders_id DESC LIMIT 1");
$order = tep_db_fetch_array($order_query);
$order_id = $order['orders_id'];
$order_total = $order['order_total'];
$customer_email = $order['customers_email_address'];
?>
<script>
window.dataLayer = window.dataLayer || [];
dataLayer.push({
  event: 'purchase',
  transaction_id: '<?= $order_id ?>',
  value: <?= $order_total ?>,
  currency: 'USD',
  email: '<?= $customer_email ?>'
});
</script>

🔹 5. Create Web GTM Tag to Send Purchase to sGTM

a. Trigger:

Custom Event = purchase

b. Tag: HTTP Request

Tag Type: Custom Tag → HTTP Request
URL: https://gtm.yourdomain.com/collect

Payload Template:

{
  "event_name": "Purchase",
  "transaction_id": "{{DLV - transaction_id}}",
  "value": {{DLV - value}},
  "currency": "{{DLV - currency}}",
  "email": "{{DLV - email}}",
  "user_agent": "{{User-Agent}}",
  "ip_override": "{{Client IP}}"
}

🔹 6. Configure sGTM to Handle Facebook CAPI

a. Create Variables in sGTM:

event_name
transaction_id
value
currency
email
user_agent
ip_override

🔹 7. Create a Tag Template or Custom HTML Tag in sGTM

const sendHttpRequest = require('sendHttpRequest');
const log = require('logToConsole');
const JSON = require('JSON');

const access_token = 'YOUR_FACEBOOK_ACCESS_TOKEN';
const pixel_id = 'YOUR_PIXEL_ID';

const event_id = data.transaction_id || 'txn_' + Math.random().toString(36).substr(2, 10);
const event_name = data.event_name;
const event_time = Math.floor(Date.now() / 1000);

const payload = {
  data: [{
    event_name: event_name,
    event_time: event_time,
    event_id: event_id,
    action_source: 'website',
    user_data: {
      em: [data.email ? sha256(data.email.trim().toLowerCase()) : ''],
      client_ip_address: data.ip_override,
      client_user_agent: data.user_agent
    },
    custom_data: {
      currency: data.currency,
      value: data.value,
      order_id: data.transaction_id
    }
  }]
};

sendHttpRequest(
  `https://graph.facebook.com/v18.0/${pixel_id}/events?access_token=${access_token}`,
  {
    method: 'POST',
    headers: {'Content-Type': 'application/json'}
  },
  JSON.stringify(payload)
);

log("Sent FB CAPI event: " + event_name);

Include a sha256 hashing function in template if required.

🔹 8. Hashing Email with SHA-256

In sGTM, add this email hashing function:

function sha256(str) {
  return Utilities.computeDigest(Utilities.DigestAlgorithm.SHA_256, str, Utilities.Charset.UTF_8)
    .map(b => ('0' + (b & 0xFF).toString(16)).slice(-2))
    .join('');
}

Alternatively, hash emails in GTM Web before sending to sGTM using Custom JavaScript Variable.

🔹 9. Enable Debugging in Events Manager

Append this to the CAPI URL temporarily:

&test_event_code=TEST123

Example:

https://graph.facebook.com/v18.0/123456789/events?access_token=xyz&test_event_code=TEST123

See test events appear in Events Manager under “Test Events”.

🔹 10. Deduplicate Events (Optional but Recommended)

Send the same event_id from both client-side and server-side implementations.

In your Pixel base code tag:

fbq('track', 'Purchase', {
  value: 199.99,
  currency: 'USD',
  eventID: 'txn_ABC123'
});

Send same event_id in sGTM.

📊 Final Testing Checklist

✅ Facebook Pixel Helper (Chrome Extension)
✅ Meta Events Manager > Test Events
✅ Verify Purchase events show parameters
✅ Confirm no duplication in attribution reports

🔐 Compliance & Privacy

Hash all PII (e.g., email) before sending to Meta
Respect user consent using Consent Mode or custom consent triggers
Avoid sending raw data without opt-in

📌 Summary

Step	Action
1	Get FB Access Token
2	Set up GTM Web + sGTM
3	Inject purchase `dataLayer` in osCommerce
4	Forward data to sGTM using HTTP Tag
5	Process purchase event using FB CAPI
6	Test and validate
7	Optionally deduplicate client & server events