Scripts

Manage reusable custom scripts and assign them to sites and path patterns.

Audience: Technical marketing and frontend operations teams using custom client-side extensions.

Critical: Storefront runtime loads active scripts through /api/v1/public/sites/:siteKey/scripts and path-based matching rules.

Integrations Client API Reference: API Endpoints

Who This Page Is For

Use this page when you need to create and govern reusable script assets, assign them to specific site paths, and verify runtime delivery behavior.

Quick Start (2-5 Minutes)

Create script asset

Create script in organization gallery.

POST /api/v1/scripts

Assign script to site

Attach script to site with pathPattern and matchType.

POST /api/v1/sites/:siteId/scripts

Inspect site assignments

List all script bindings for a site.

GET /api/v1/sites/:siteId/scripts

Adjust assignment behavior

Patch path matching or activation fields as needed.

PATCH /api/v1/sites/:siteId/scripts/:id

Validate storefront response

Fetch active scripts for a concrete page path.

GET /api/v1/public/sites/:siteKey/scripts?path=/products/headphones

Script endpoints

POST   /api/v1/scripts
PATCH  /api/v1/scripts/:id
DELETE /api/v1/scripts/:id
GET    /api/v1/scripts
GET    /api/v1/scripts/:id
POST   /api/v1/sites/:siteId/scripts
GET    /api/v1/sites/:siteId/scripts
PATCH  /api/v1/sites/:siteId/scripts/:id
DELETE /api/v1/sites/:siteId/scripts/:id
GET    /api/v1/public/sites/:siteKey/scripts

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`name`	Required	`string`	Script create/update	Script label shown in gallery and assignment UI.
`content`	Required	`string`	Script create/update	JavaScript source executed on matched pages.
`scriptId`	Required	`uuid`	Site assignment create	Reference to gallery script being assigned.
`pathPattern`	Optional	`string`	Site assignment matching	URL path pattern for script eligibility.
`matchType`	Optional	`prefix \| exact \| regex (service-dependent)`	Site assignment matching	Pattern evaluation behavior for path matching.

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Create reusable script once	POST /api/v1/scripts	Centralized script library for organization.
Bind script to one site	POST /api/v1/sites/:siteId/scripts	Site-scoped activation with path controls.
Change matching behavior safely	PATCH /api/v1/sites/:siteId/scripts/:id	Avoids deleting/recreating assignments.
Remove script from one site only	DELETE /api/v1/sites/:siteId/scripts/:id	Unbinds without deleting gallery asset.
Confirm storefront runtime payload	GET /api/v1/public/sites/:siteKey/scripts?path=...	Shows scripts actually delivered for route.

Common Errors and Fixes

Script exists but does not run on page

Cause: Assignment pathPattern does not match requested path.

Fix: Adjust pathPattern/matchType and retest with public scripts endpoint.

Script runs on too many pages

Cause: Pattern is too broad (for example root prefix only).

Fix: Narrow path pattern and use stricter matchType where supported.

Cannot assign script

Cause: Invalid scriptId or insufficient permission for script activation.

Fix: Validate script exists and role has script activation permission.

Unexpected runtime script order

Cause: Multiple active assignments overlap same path.

Fix: Consolidate overlapping assignments and document execution expectations.

Production Checklist

All scripts are versioned and have clear ownership.Required
Path matching rules are tested on representative storefront URLs.Required
Site assignments are reviewed to avoid duplicate overlapping scripts.Required
Public scripts endpoint validated on production domain origin.Required
Rollback path exists via assignment patch/delete workflow.Required