Add analytics and ad tags to your storefront

A tag is a small piece of code from an analytics or advertising platform. It tells the platform which visits and sales came from its own ads, so you can measure what the ads earn. Your storefront loads a tag for each platform whose ID you save, and for no other.

Every tag is an ID. You copy it from the platform, paste it into one field and save. The IDs are public: they appear in the source of every storefront page, so they are not secrets, and this page never asks for a password or an API key.

• You need the Owner or Admin role in the organization.
• You need an account on each platform you want to use, with its tag or pixel already created.
• Your storefront must be served by Coritan. A site you build yourself on the Organization API reads the same IDs from the Storefront API and loads the tags itself.

In the dashboard, open your organization, then "Settings", then "Tags and pixels". The page has one card for each platform, with a badge that says "On" when an ID is saved and "Off" when it is not. A member below the Admin role sees the saved IDs and nothing to press.

1. Paste each platform's ID into its card. The field shows an example of the shape the ID has.
2. Select "Clear" on a card to empty that platform's fields.
3. Select "Save changes" on the card. Each card saves on its own, and "Discard" puts the card back as it was.

The staff console has the same editor at /staff/settings?tab=marketing: the "Settings" page and its "Marketing" tab. Its "Tags and pixels" section has one panel for each platform, and a single "Save tags" button saves every panel at once. It is open to the Admin and Owner roles only. Platform staff also set the tags for any organization in the admin console.

Each ID is checked as you save. A wrong one is refused with a sentence that names the field, such as Meta pixel id must be 8 to 20 digits, and nothing is saved. Saving what is already stored changes nothing. A change reaches new page loads within a minute, and the audit log records it as settings.tags.updated with the IDs before and after. You can also set the tags with the API.

View the source of a storefront page. A script in the head sets window.__ctTags to the IDs you saved, with the consent settings after them, and a platform you left empty is missing from it. The platform's own library then loads once the visitor interacts with the page and allows the platform's kind of cookie.

Google Analytics 4 also has a "Debug mode" switch, which is off by default. Turn it on while you test, and off again afterwards.

Labels and event IDs belong to the ID above them. You cannot save Google Ads labels without a conversion ID, or X event IDs without a pixel ID.

Two settings in Google Analytics keep the numbers honest. Both are under Admin, then Data streams, then your web stream.

1. Open "Enhanced measurement", then the settings of "Page views", and show the advanced settings. Turn off "Page changes based on browser history events". The storefront sends its own page view when a visitor moves to another page, and with this switch on, Google Analytics counts each move twice.
2. Open "Configure tag settings", show all settings, and open "List unwanted referrals". Add stripe.com and paypal.com, and the address of any other payment page your customers pass through, such as paynow.gg. Without them, a customer who comes back from paying shows as a visit from the payment page, and the sale is credited to it instead of to the ad.

To check it, turn on "Debug mode", open your storefront in a new tab, and open DebugView under Admin in Google Analytics. Your visit and each page you open appear there. Turn "Debug mode" off when you are done.

Each platform has its own test tool. Open your storefront in a browser window, accept marketing cookies when the banner asks, then look in the platform:

• Google Ads and Google Tag Manager: use Tag Assistant, which lists the tags a page loaded. For Tag Manager, use the container's preview mode.
• Meta: the "Test events" tab in Events Manager shows the events from your site while you browse it.
• TikTok: the test events view in Events Manager lists the events the pixel received.
• Microsoft Advertising: the UET tag's status page shows whether the tag is active, and the UET Tag Helper browser extension shows each hit.
• Reddit and X: use the platform's pixel helper browser extension, or the events page in its ads manager.

If a tag shows nothing, work down Troubleshooting.

Besides each page view, the storefront tells the tags what a visitor does on the way to buying. Every event uses the name Google Analytics 4 gives it, and the tag for each other platform turns it into that platform's own event. An event reaches a platform only when its tag is on and the visitor allows its kind of cookie. Google Analytics 4 hears every event, with its consent set as the visitor chose. Google Ads counts purchase, sign_up and generate_lead as conversions when its card has a label for them.

Each item has item_id (the plan's slug or the product's ID), item_name, item_category (the game or product family), item_variant (the location the buyer chose, or the billing period), price, quantity and, in a list, item_list_name and index. A price is the amount the page showed, in the currency the customer pays in. Currencies are never added together.

The transaction_id of a purchase is the invoice number, and the event ID is purchase: followed by the invoice number, such as purchase:INV-000042. A platform that receives the same sale from another source can use the event ID to count it once.

• A browser sends the purchase of an invoice once. It remembers that in the browser's local storage, so a reload, a second tab or a return visit sends nothing more.
• Only the browser that paid sends it. The invoice page counts a browser as the payer when it showed that invoice unpaid, or when the visitor comes back from the payment page with paid=1 in the address and the invoice is confirmed paid. An address alone never counts.
• A paid invoice opened from an email link sends nothing, because that browser did not pay.
• An order that costs nothing is a lead, never a purchase.

After a visitor signs in or signs up, the storefront gives the tags the customer ID before it sends login or sign_up. Google Analytics 4 gets it as a SHA-256 hash in user_id, only when the visitor allows analytics. Meta, TikTok and Reddit get the hash of the ID and of the email, only when the visitor allows marketing. No platform gets a raw ID. For Google Ads enhanced conversions, a purchase or sign_up also passes the customer's email to the Google tag when the page already holds the address and the visitor allows marketing, and that tag hashes it before it leaves the browser.

The storefront's /staff, /admin and /dashboard pages send none, and neither does any page on a host that is not the storefront's own.

1. Turn on "Debug mode" in the Google Analytics 4 card, as described under Set up Google Analytics 4.
2. Open your storefront in a new tab, accept analytics when the banner asks, and open DebugView under Admin in Google Analytics.
3. Open a plan list, choose a plan, change a field of its order form and place the order. DebugView shows view_item_list, select_item, view_item and begin_checkout as they happen, each with its parameters.
4. Choose a way to pay on the invoice page. DebugView shows add_payment_info. Pay the invoice, and it shows purchase with the invoice number as its transaction ID.
5. To see a purchase again, pay a new invoice. The same invoice never sends a second purchase from the same browser.

In Meta's "Test events" tab, a purchase appears as Purchase with the event ID, and the TikTok test events view lists it as CompletePayment. Turn "Debug mode" off when you have finished.

Ad tags load only after a visitor allows marketing cookies. The storefront asks, and remembers the answer for six months in the _ct_consent cookie. The cookies the storefront's own tracker sets are listed under What the tracker records.

• In the EEA, the UK and Switzerland, a banner asks first. Until the visitor chooses, analytics and marketing are both off, and no tag loads. The banner offers "Accept all", "Reject all" and a way to choose analytics and marketing separately.
• Everywhere else, both are on until the visitor says otherwise, and a short notice with an "Opt out" link tells them so.
• A browser that sends Global Privacy Control counts as saying no to marketing everywhere, whatever the banner says.
• A "Cookie settings" link in the storefront's footer lets a visitor change their mind.

The banner links to your privacy page, which is the "Privacy policy URL" in your organization's branding settings, or /privacy when there is none. Name the platforms you use in that policy.

• Tags load on your storefront's own hostnames only. A test copy of the site on another address sends nothing.
• Tags never load on the storefront's /staff and /admin pages, and those pages allow no advertising hosts.
• The storefront allows connections only to the hosts of the platforms you save. A platform that you load through a Google Tag Manager container also needs its own ID here, so that the page allows its hosts.
• A brand that set Google Analytics before tags existed keeps working. The Google Analytics 4 card shows a note, and the first save moves the ID into the new settings.

Meta pixel id must be 8 to 20 digits

Each platform names the shape its ID has. Copy the ID again from the platform, without spaces around it. The sentence and the field in the API answer say which input to fix.

Add the Google Ads conversion id before its conversion labels

Save the conversion ID with the labels, or remove the labels.

Add the X pixel id before its event ids

Save the pixel ID with the event IDs, or remove the event IDs.

A tag shows no visits

Check, in this order: the panel says "On" and you saved it; a minute has passed; you opened the storefront on its own address; you accepted marketing cookies, or you are outside the EEA, the UK and Switzerland and did not opt out; and no browser extension or privacy setting blocks the platform.

The same sale counts twice in Google Analytics

Turn off "Page changes based on browser history events" as described under Set up Google Analytics 4.

Sales are credited to Stripe or PayPal

Add the payment pages to the list of unwanted referrals, as described under Set up Google Analytics 4.

An owner or admin reads and replaces the tags with an access token, sent as Authorization: Bearer $CORITAN_TOKEN. Any member can read them with GET /api/v1/orgs/{org_slug}/tags. PUT takes the whole tags object: a platform you leave out is turned off.

curl -X PUT "https://api.coritan.com/api/v1/orgs/acme/tags" \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tags": {"ga4": {"measurement_id": "G-ABC123DEF4"}, "meta": {"pixel_id": "123456789012345"}}}'

The answer has the saved tags, the platforms an editor can draw in kinds (each with its fields, a label, a hint, a pattern and an example), the consent settings, legacy_google_analytics and, after a PUT, changed: the platforms that differ from before.

{
  "tags": {
    "ga4": { "measurement_id": "G-ABC123DEF4", "debug": false },
    "meta": { "pixel_id": "123456789012345" }
  },
  "consent": { "banner": true, "privacy_path": "/privacy" },
  "legacy_google_analytics": false,
  "changed": ["ga4", "meta"]
}

IDs are trimmed, and each is checked against its platform's shape: Google Analytics 4 G- then 6 to 20 letters or digits, Google Ads AW- then 6 to 14 digits, Meta 8 to 20 digits, TikTok 10 to 32 letters or digits, Microsoft 6 to 12 digits, Reddit 6 to 40 letters, digits, dashes or underscores, X 4 to 12 lowercase letters or digits, Tag Manager GTM- then 4 to 10 letters or digits. A platform with no ID is left out. Keys the API does not know are dropped.

A bad ID answers 422 with detail, the sentence to show, and field, the input it belongs to:

{ "detail": "Meta pixel id must be 8 to 20 digits", "field": "meta.pixel_id" }

Staff console members with the Admin role use the same two routes under /api/v1/orgs/{org_slug}/staff/marketing/tags, which also refuse a read from any other role. The older google_analytics field of PATCH /api/v1/orgs/{org_slug}/settings still works: it sets the Google Analytics 4 entry of tags.

• Change organization settings
• Read your storefront's traffic
• Build a storefront on the Organization API
• Read the organization audit log

• Read your storefront's traffic to compare Google Analytics with what Coritan counts on its own.
• Name the platforms in your privacy policy, through the privacy policy URL in your branding.