Skip to main content

​
Shopify Checkout Script

When you connect a Shopify store to Tagada, we inject a small checkout script (internally TgdMapper) into your store’s active theme (layout/theme.liquid). This script rewrites your storefront Buy Now / Checkout buttons so the cart is handed off to a Tagada funnel checkout instead of Shopify’s native checkout.
The script is what makes “buy on Shopify, pay on Tagada” work. Which funnel/step the script is bound to decides which checkout — and therefore which payment routing — your storefront uses. Switching a store from one processor to another often comes down to re-pointing this script at a new funnel.

​
Prerequisites

  • The store must have Shopify connected (OAuth) in the dashboard (Integrations tab).
  • All endpoints require your API key as a Bearer token:
Authorization: Bearer YOUR_API_KEY

​
The four operations

OperationMethod & pathSDK
Read the installed script + its configGET /stores/{storeId}/shopify-scripttagada.shopify.checkScript(storeId)
Install / update the scriptPUT /stores/{storeId}/shopify-scripttagada.shopify.updateScript(storeId, { config })
Remove the scriptDELETE /stores/{storeId}/shopify-scripttagada.shopify.removeScript(storeId)
Audit the theme for conflictsGET /stores/{storeId}/shopify-script/audittagada.shopify.audit(storeId)
There is one script per store. PUT replaces any existing Tagada block in the theme — it does not stack a second one.

​
Read the current script

Find out whether the script is installed and which funnel/step it currently points at. Pass funnelId + stepId to also get conflict detection against a target funnel. 
curl "https://app.tagadapay.com/api/public/v1/stores/store_123/shopify-script?funnelId=funnelv2_new&stepId=step_1" \
  -H "Authorization: Bearer YOUR_API_KEY"

const status = await tagada.shopify.checkScript('store_123', {
  funnelId: 'funnelv2_new',
  stepId: 'step_1',
});

console.log(status.isInjected);        // true
console.log(status.config?.funnelId);  // funnelv2_old  ← currently bound funnel
console.log(status.isConflict);        // true → the store points at a different funnel
Response
{
  "isInjected": true,
  "themeName": "Dawn",
  "shopUrl": "my-shop.myshopify.com",
  "config": { "storeId": "store_123", "funnelId": "funnelv2_old", "stepId": "step_1" },
  "isConflict": true,
  "conflictDetails": { "currentFunnelId": "funnelv2_old", "currentStepId": "step_1" }
}

​
Install or switch the script

Send a partial config — the server fills sensible defaults for anything you omit. The most common use is binding the storefront checkout to a specific funnel/step. 
curl -X PUT https://app.tagadapay.com/api/public/v1/stores/store_123/shopify-script \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "funnelId": "funnelv2_new",
      "stepId": "step_1",
      "shopifyCheckoutSplitRatio": 100
    }
  }'

await tagada.shopify.updateScript('store_123', {
  config: {
    funnelId: 'funnelv2_new',
    stepId: 'step_1',
    shopifyCheckoutSplitRatio: 100, // 0–100: share of checkouts routed to Tagada
  },
});
Response
{ "success": true, "message": "TagadaPay script updated successfully", "themeId": 140363235490 }
Shopify’s Theme API is eventually consistent. Right after a PUT, a checkScript call may briefly still report the old config. Give it a few seconds, then re-read to confirm.

​
Migrating a store to a new processor

Re-pointing the script is exactly how you move a live Shopify store onto a new payment funnel (e.g. a new Stripe-MoR or cascade funnel) without touching the storefront theme by hand:
1

Publish the new funnel

Save and promote the new funnel to its production domain — see Funnel Lifecycle.
2

Check the current binding

checkScript(storeId, { funnelId, stepId }) — confirm isConflict shows the store still points at the old funnel.
3

Switch

updateScript(storeId, { config: { funnelId, stepId } }) — the storefront now routes new carts through the new funnel’s payment flow.
4

Verify

Re-read with checkScript (after a few seconds) and place a test order.

​
Remove the script

Strips all Tagada script blocks (current and legacy v1) from the active theme. The storefront reverts to Shopify’s native checkout. 
curl -X DELETE https://app.tagadapay.com/api/public/v1/stores/store_123/shopify-script \
  -H "Authorization: Bearer YOUR_API_KEY"

await tagada.shopify.removeScript('store_123');

​
Audit the theme

Even with the script installed, a theme can silently bypass or break the integration — a commented-out native button, a hardcoded external redirect, a fetch interceptor, or a leftover legacy script. The audit scans checkout-critical theme files and reports findings by severity. 
curl https://app.tagadapay.com/api/public/v1/stores/store_123/shopify-script/audit \
  -H "Authorization: Bearer YOUR_API_KEY"

const audit = await tagada.shopify.audit('store_123');
if (!audit.isHealthy) {
  for (const f of audit.findings) {
    console.log(`[${f.severity}] ${f.file}: ${f.message}`);
  }
}
Response
{
  "isHealthy": false,
  "summary": { "high": 1, "medium": 0, "low": 0 },
  "filesScanned": 12,
  "shopUrl": "my-shop.myshopify.com",
  "themeName": "Dawn",
  "scannedAt": "2026-07-08T18:00:00.000Z",
  "findings": [
    {
      "ruleId": "hardcoded-external-redirect",
      "severity": "high",
      "file": "snippets/buy-buttons.liquid",
      "line": 42,
      "snippet": "window.location.href = 'https://checkout.example.com'",
      "message": "Buy button redirects to an external checkout, bypassing Tagada.",
      "recommendation": "Remove the hardcoded redirect so the Tagada script can intercept the click."
    }
  ]
}

​
Authentication troubleshooting

Send Authorization: Bearer YOUR_API_KEY with a non-empty, valid key. In shell scripts, an empty variable produces Authorization: Bearer with nothing after it — the same 401 as a missing header. Verify with echo ${#KEY} before calling.
The store has no active Shopify OAuth connection. Connect Shopify in the dashboard (Integrations tab) and retry.
Your API key belongs to a different account than the store’s owner. Use a key from the account that owns storeId.