Tapfiliate server-side GTM tag template

The Tapfiliate Server Tag template does affiliate tracking from a GTM server container. Rather than making API calls from the browser, it sends conversion and customer data straight to the Tapfiliate REST API from your server.

This template only works in a server-side container. It will not run in a web container.

• Four operation types: Create Conversion, Update Conversion, Create Customer and Update Customer
• Sends requests server-side to https://api.tapfiliate.com/1.7/pb/, keeping your API token out of client-side code
• Forwards User-Agent and client IP (X-Forwarded-For, X-Real-IP) from the original request for accurate attribution
• Three attribution methods with a clear priority: Coupon, then Click ID, then Referral Code
• Accepts optional JSON metadata for custom fields such as subscription plan or customer lifetime value
• Handles conversion status updates, Approved or Disapproved, for commission workflows

Your token authenticates every request. Find it in the Tapfiliate dashboard under Settings, API Keys. Enter it in the tag field, or reference a server-side GTM variable, which is preferable once you have more than one tag.

Create Conversion. The common one. Registers a sale, lead or signup through a POST to https://api.tapfiliate.com/1.7/pb/con/c/.

Update Conversion. Approves or disapproves a conversion you created earlier, for instance after fulfilment or a refund. POST to https://api.tapfiliate.com/1.7/pb/con/u/.

Create Customer. Registers a customer and links them to an affiliate for recurring commission. POST to https://api.tapfiliate.com/1.7/pb/cus/c/.

Update Customer. Updates an existing customer, for example to change attribution or add metadata. POST to https://api.tapfiliate.com/1.7/pb/cus/u/.

When several attribution fields are filled, Tapfiliate works down this order:

• Coupon, matched against affiliate coupon codes configured in Tapfiliate
• Click ID, the Tapfiliate click identifier, usually stored in a cookie
• Referral Code, the affiliate's code, usually passed as a URL parameter

One method is enough, but supplying several gives Tapfiliate fallbacks.

The Meta Data field takes a JSON string for custom attributes used in reporting or commission rules:

{"product_category": "subscription",
 "plan_duration": "annual",
 "is_first_purchase": true}

Separately, the template reads the incoming request and forwards the User-Agent and the client IP (X-Forwarded-For or X-Real-IP) to Tapfiliate, which uses them for fraud detection and geo-targeting. That needs no configuration.

Your server container has to be receiving events first: a GA4 or custom client parsing incoming requests, a web container sending to the sGTM transport URL, and purchase events carrying transaction ID, value and coupon.

• Create a tag using the Tapfiliate Server Tag template.
• Set Operation Type to Create Conversion and enter your API Token.
• Map Transaction ID to {{Event - transaction_id}}.
• Map Conversion Value to {{Event - value}} and Currency to {{Event - currency}}.
• Map Coupon to {{Event - coupon}} where available.
• Trigger on a custom event matching purchase from your GA4 client, then save and publish.

For programmes needing manual approval, add a second tag with Operation Type Update Conversion. That one is usually triggered server to server, for example by a webhook from your order management system hitting your sGTM endpoint.

401 Unauthorized. The token is missing or invalid. Check it under Settings, API Keys, and watch for leading or trailing spaces.

Conversions created but not attributed. At least one attribution field has to match a known affiliate. Inspect the payload in sGTM Preview. Usual culprits: a coupon that matches no affiliate, or a missing click ID.

Duplicate conversions. Tapfiliate deduplicates on Transaction ID, so duplicates mean your purchase event fires more than once. Add deduplication in sGTM, for instance a Firestore cache or the event's unique ID.

Conversion value zero or missing. The mapped variable has to resolve to a numeric string. If it comes from GA4, check the value parameter is set in your web container.

Client IP not forwarded. The template reads X-Forwarded-For and X-Real-IP. If a CDN or load balancer strips those, Tapfiliate sees your server IP instead. Configure your infrastructure to preserve them.

Metadata rejected. The field has to hold valid JSON. Single quotes and trailing commas are the usual mistakes. Validate it before pasting.

• Tapfiliate REST API documentation: https://tapfiliate.com/docs/rest/
• Tapfiliate help centre: https://tapfiliate.com/docs/
• Server-side GTM documentation: https://developers.google.com/tag-platform/tag-manager/server-side
• GTM Help Center: https://support.google.com/tagmanager/