# SitePack developer documentation

> Docs for building on SitePack: apps that use the REST API, themes, the JavaScript SDK and the SitePack CLI.

## API reference

- [OpenAPI document](https://sitepack.dev/openapi.json): every endpoint of the SitePack API as OpenAPI 3 JSON
- [Getting started](https://sitepack.dev/api-reference/getting-started.md): base URL, OAuth, scopes, rate limits and errors

One Markdown file per section, every endpoint with its parameters, request body and example responses:

### Getting started

- [OAuth](https://sitepack.dev/api-reference/oauth.md): Ask a merchant for consent, Ask a merchant for consent, Exchange a code for a token, Register an MCP connector client, Start device authorization, Inspect a token, …
- [Meta](https://sitepack.dev/api-reference/meta.md): Who am I, List every scope
- [App settings](https://sitepack.dev/api-reference/app-settings.md): Read app settings, Replace app settings
- [Webhooks](https://sitepack.dev/api-reference/webhooks.md): List webhook subscriptions

### Leads & customers

- [Leads](https://sitepack.dev/api-reference/leads.md): List leads, List lead notes, Add a lead note, Get a lead, Update a lead, Delete a lead
- [Customers](https://sitepack.dev/api-reference/customers.md): List customers, Create a customer, Get a customer, Update a customer
- [Comments](https://sitepack.dev/api-reference/comments.md): List comments, Moderate a comment, Delete a comment

### Webshop

- [Products](https://sitepack.dev/api-reference/products.md): List products, Create a product, Set variant stock, Replace variant metafields, Read product stock, List stock changes, …
- [Collections](https://sitepack.dev/api-reference/collections.md): List collections, Create a collection, List collection rules, Replace collection rules, Get a collection, Update a collection, …
- [Orders](https://sitepack.dev/api-reference/orders.md): List orders, Create an order, List order payments, Get an order, Change an order status
- [Discounts](https://sitepack.dev/api-reference/discounts.md): List discount codes, Create a discount code, Get a discount code, Archive a discount code
- [Shipping](https://sitepack.dev/api-reference/shipping.md): List shipping labels, Get a shipping label

### Content

- [Content](https://sitepack.dev/api-reference/content.md): Check a slug is free, List pages, Create a page, Publish a page, Unpublish a page, List page revisions, …
- [Blogs](https://sitepack.dev/api-reference/blogs.md): List blog posts, Create a blog post, Publish a blog post, Unpublish a blog post, Get a blog post, Update a blog post, …
- [Post types](https://sitepack.dev/api-reference/post-types.md): List post types, Get a post type, Get a post type overview page, Update a post type overview page, List post entries, Create a post entry, …
- [Elements](https://sitepack.dev/api-reference/elements.md): List element areas, Get an element area, Replace an element area
- [Navigation](https://sitepack.dev/api-reference/navigation.md): List navigations, Update a navigation item, Delete a navigation item, List navigation items, Add a navigation item, Reorder a navigation
- [Translations](https://sitepack.dev/api-reference/translations.md): List site locales, List what needs translating, Read translation coverage, List an item's translations, Get one locale's translation, Save a translation, …
- [Media](https://sitepack.dev/api-reference/media.md): List media, Get a media item, Update a media item, Delete a media item
- [Categories](https://sitepack.dev/api-reference/categories.md): List categories, Create a category, Get a category, Update a category, Delete a category
- [Tags](https://sitepack.dev/api-reference/tags.md): List tags, Create a tag, Get a tag, Update a tag, Delete a tag
- [Redirects](https://sitepack.dev/api-reference/redirects.md): List redirects, Create a redirect, Get a redirect, Update a redirect, Delete a redirect
- [USPs](https://sitepack.dev/api-reference/usps.md): List USPs, Create a USP, Reorder USPs, Get a USP, Update a USP, Delete a USP
- [Theme](https://sitepack.dev/api-reference/theme.md): List theme layouts, Read theme design settings, Change theme design settings, Read the active theme

### Site

- [Site](https://sitepack.dev/api-reference/site.md): Read the site settings, Update the site settings, Read the social media profiles, Update the social media profiles, Read site statistics
- [Modules](https://sitepack.dev/api-reference/modules.md): List active modules, Read module settings, Update module settings
- [Billing](https://sitepack.dev/api-reference/billing.md): List invoices, List subscriptions
- [Domains](https://sitepack.dev/api-reference/domains.md): Check domain availability, Suggest domain names, Order a domain, List domain holders, List domains, List DNS records, …
- [Mail](https://sitepack.dev/api-reference/mail.md): Read free mailbox slots, List mailboxes, Create a mailbox, Read mailbox usage, Change a mailbox password, Get a mailbox, …

## Docs

- [App Settings](https://sitepack.dev/docs/apps/admin-ui): Almost every app needs a few answers from the merchant: a phone number, an account id, a colour, a switch to turn a feature on. Let SitePack build that settings page for you. You describe the fields in app.json, and SitePack renders the form inside the merchant's admin, stores the answers per site and hands them to your app.
- [API Endpoints](https://sitepack.dev/docs/apps/api-endpoints): Every endpoint an API integration can call, on one page. Each row links to the API Reference, where you find the parameters, the request body and example responses.
- [API Integrations](https://sitepack.dev/docs/apps/api-integrations): An API integration is an app that runs on your own server and works with the merchant's data through the SitePack REST API: syncing products and stock with an ERP, sending orders to a warehouse, pushing leads into a CRM, connecting a POS.
- [The app.json Manifest](https://sitepack.dev/docs/apps/app-json): app.json describes your app to SitePack: its name, its settings page, what it renders on the storefront and, for an API integration, which scopes and webhooks it uses. SitePack reads the manifest of the version you published last.
- [Editor Elements](https://sitepack.dev/docs/apps/editor-elements): Editor elements are on the roadmap and do not work yet: SitePack ignores the editor section of app.json for now, and the SitePackAdmin editor SDK described below does not exist yet. This page shows the planned design, so you can see where it is going. To put your app on the storefront today, use storefront blocks.
- [Example: A Complete API Integration](https://sitepack.dev/docs/apps/example-integration): This page puts the whole API integration flow into one small, runnable server: the install callback, the token exchange, token refresh, a signed webhook and an API call. It is written for Node.js 18 or newer and uses no packages, so every step stays visible. The same steps work in any language.
- [Apps FAQ](https://sitepack.dev/docs/apps/faq): Building
- [Your First App: a WhatsApp Button](https://sitepack.dev/docs/apps/getting-started): In this tutorial you build a complete storefront app: a floating WhatsApp button that appears on every page of the merchant's site. It is a slimmed-down version of the WhatsApp app in the SitePack Marketplace.
- [Authentication and OAuth 2.0](https://sitepack.dev/docs/apps/oauth-flow): SitePack uses OAuth 2.0 to authorize apps to access merchant data. Merchants stay in control of which apps can access their site and what those apps may do.
- [Introduction to SitePack Apps](https://sitepack.dev/docs/apps/overview): A SitePack app adds something to a merchant's website or webshop: a chat button, a tracking tag, a review widget, or a full sync with an ERP, a POS or an accounting package. Merchants find apps in the SitePack Marketplace and switch them on for their site.
- [The Partner Portal, Step by Step](https://sitepack.dev/docs/apps/partner-portal): Everything around your app that is not code lives in the SitePack Partner Portal: your organisation and team, the app itself, its Marketplace listing, its prices, its OAuth credentials and the review. This page walks through it in the order you will need it.
- [App Marketplace Policy](https://sitepack.dev/docs/apps/policy): This policy defines what's expected of an app before and after it's listed on the SitePack App Marketplace. It reflects how the review process and the Partner Portal actually work today: read it alongside the App Manifest Reference and Publishing & Monetization.
- [Post Types](https://sitepack.dev/docs/apps/post-types): An app can register its own post types in app.json: a named list of records the merchant manages in the SitePack admin, with the fields your app defines. Think of the cinemas of a cinema advertising network, the branches of a franchise, the members of a club or the brands of a distributor. You describe the post type once; SitePack stores the records, gives the merchant a screen to manage them and hands them to themes and app templates.
- [Product options & variants](https://sitepack.dev/docs/apps/product-options-variants): A SitePack product can be sold as a single product or as a product with options and variants. This is the recommended way to model things like a shirt that comes in several sizes and colours: one product owns its options and variants, instead of many separate products linked together.
- [Publishing & Monetization](https://sitepack.dev/docs/apps/publishing-and-monetization): Once your app works on your own site, you decide who can use it and what it costs. This page explains versions, visibility, how merchants install your app and how you get paid. The clicks in the Partner Portal are in The Partner Portal, Step by Step.
- [Scopes and Permissions](https://sitepack.dev/docs/apps/scopes): Scopes are only needed for an API integration. A storefront app that does not call the API declares no scopes, and merchants install it with one click from the Marketplace.
- [Storefront Blocks & Events](https://sitepack.dev/docs/apps/storefront-events): An app does not only live in the admin. With blocks and scripts in its app.json it runs on every page of the storefront, and SitePack hands it two streams of events to act on: the events the server recorded while rendering the page, and the events the SitePack SDK raises in the browser while the visitor interacts. Together they let any app react to a shop end to end without touching the theme, whether it is analytics, a tag manager, a marketing pixel, or a chat or review widget.
- [Testing & Debugging](https://sitepack.dev/docs/apps/testing-and-debugging): Your app runs inside someone else's site, so SitePack is strict about what it accepts, and it fails quietly on the storefront rather than breaking a merchant's page. This page tells you where each check happens and where to look when something does not show up.
- [App Translations](https://sitepack.dev/docs/apps/translations): A SitePack app is installed by merchants across the Netherlands, Belgium, Germany, France and Spain, and its storefront blocks are read by their visitors. Both sides read your app in their own language when you ship a translation dictionary with it: one JSON file per language, next to your app.json.
- [Webhooks](https://sitepack.dev/docs/apps/webhooks): Webhooks allow your app to receive real-time notifications when specific events occur within a SitePack store. Instead of polling the API for changes, SitePack will "push" data to your server via an HTTPS POST request.
- [Developer Changelog](https://sitepack.dev/docs/changelog): What changed for app, theme and SDK developers, newest first. Changes are backwards compatible unless an entry says otherwise.
- [AI editor (MCP)](https://sitepack.dev/docs/cli/ai-mcp): sitepack mcp turns the site you are developing into a live workspace for an AI editor. While sitepack theme create pages, put them in a menu, and manage the online store's categories and products, then check that what it built actually renders.
- [Authentication](https://sitepack.dev/docs/cli/authentication): To use the SitePack CLI, you need to authenticate with your SitePack account. This ensures you have the necessary permissions to manage apps, themes, and organizations.
- [Commands](https://sitepack.dev/docs/cli/commands): This page provides a comprehensive reference for all available commands in the SitePack CLI.
- [Installation](https://sitepack.dev/docs/cli/installation): To get started with SitePack, you need to install the CLI on your machine. The CLI is available as an npm package and can be used with any major package manager.
- [Organizations](https://sitepack.dev/docs/cli/organizations): Most resources in SitePack, such as Apps and Themes, are owned by an organization (also referred to as a partner). The SitePack CLI allows you to manage these organizations and switch between them.
- [Account](https://sitepack.dev/docs/sdk/account): The sdk.account module exposes the storefront customer account: reading the current session, logging in, and requesting a password reset.
- [Content, Search, Leads & Site Content](https://sitepack.dev/docs/sdk/content-search-leads): This page covers the smaller storefront modules: sdk.content, sdk.search, sdk.leads, sdk.newsletter, sdk.usps and sdk.events, plus the instance-level contactSiteOwner helper. The last three read the site content a merchant manages centrally in the admin (the newsletter, the USPs and the agenda) — the same content the sitepacknewsletterform(), sitepackusps() and sitepackevents() theme functions render server-side.
- [Ecommerce](https://sitepack.dev/docs/sdk/ecommerce): The sdk.ecommerce module is the largest part of the SDK. It covers the product catalogue, the shopping cart, checkout information, categories and filters, stock, and address lookups.
- [Getting Started](https://sitepack.dev/docs/sdk/getting-started): The SDK is loaded automatically on every storefront page — you do not install it from npm or add a `` tag yourself. This guide shows how to initialize it and make your first request.
- [SitePack JavaScript SDK](https://sitepack.dev/docs/sdk/overview): The SitePack SDK is a browser-side JavaScript library that lets theme and app developers talk to the storefront safely — reading products, managing the cart, running searches, fetching content, generating leads, and more — without ever hand-writing fetch calls or worrying about CSRF, rate limiting, or endpoint URLs.
- [API Reference](https://sitepack.dev/docs/sdk/reference): A compact map of every SDK method to the endpoint it calls. All endpoints live under /api/sdk and are protected as described in Security & Rate Limiting. Every network method returns a Promise.
- [Security & Rate Limiting](https://sitepack.dev/docs/sdk/security): The SDK is designed so that theme and app developers get safe defaults for free. This page explains what protects each request, where the limits are, and the rules for using the SDK responsibly.
- [UI & Cookies](https://sitepack.dev/docs/sdk/ui-cookies): Two small helper modules: sdk.ui for talking to the SitePack host environment, and sdk.cookies for first-party cookies.
- [Theme Assets & Global CDN Delivery](https://sitepack.dev/docs/themes/assets): Theme assets are the frontend client-side resources—such as CSS stylesheets, interactive JavaScript scripts, branding images, and custom webfonts—that govern the appearance and user experience of your SitePack storefront.
- [Theme Directory Structure & File Mapping](https://sitepack.dev/docs/themes/directory-structure): A SitePack theme follows a structured, standard directory layout. This directory conventions-based system ensures that the SitePack compilation engine can instantly locate, resolve, and render your templates, modular snippets, layouts, translations, and dynamic configurations.
- [Custom Twig Filters Reference API](https://sitepack.dev/docs/themes/filters): SitePack registers a small set of custom filters inside the Twig environment to streamline asset URLs and sanitize link behavior. Colour math lives in the Functions Guide (calculatebrightness, calculatetext_color), though CSS color-mix() is usually the better tool — see below.
- [Custom Twig Functions Reference API](https://sitepack.dev/docs/themes/functions): SitePack registers a suite of custom Twig functions on top of the standard Twig environment. They compile down to native, sandboxed PHP calls, giving you high-performance building blocks for rendering layout chrome (headers, footers, navigation), commerce UI (cart, prices, stock), and platform integrations (icons, cookies, app blocks) — without writing any backend code yourself.
- [Getting Started: Installation, Initialization & Local Watch](https://sitepack.dev/docs/themes/getting-started): Setting up your environment for SitePack theme development is simple and highly automated. This step-by-step guide will walk you through preparing your machine, initializing your first theme project, starting local hot-reloading development, and publishing a release to the SitePack Marketplace.
- [Built-in SVG Icons Library & Reference](https://sitepack.dev/docs/themes/icons): SitePack themes include a comprehensive, highly optimized library of vector SVG icons natively. Instead of importing heavy, third-party icon fonts (like FontAwesome or material-icons) which delay page loads and hurt your Google Lighthouse / Core Web Vitals performance scores, you can render these icons instantly on the server side using our fast built-in function sitepack_icon('icon-name').
- [Introduction & Theme Development Overview](https://sitepack.dev/docs/themes/overview): Welcome to the SitePack Theme Development guide! Whether you are an experienced e-commerce developer or a frontend designer building your first storefront skin, SitePack provides an incredibly fast, secure, and modern platform to realize your designs.
- [Page Examples](https://sitepack.dev/docs/themes/page-examples): The fastest way to understand a SitePack theme is to see the smallest template that still renders a working page. Every example below is a complete {% block content %} you can paste into the matching templates/*.twig file — the chrome (head, header, footer, cookies, scripts) comes from layouts/base.twig, so a page template only fills in its own content.
- [Theme Marketplace Policy](https://sitepack.dev/docs/themes/policy): This policy defines what's expected of a theme before and after it's listed on the SitePack Theme Marketplace. It reflects how the review process and the Partner Dashboard actually work today — read it alongside the theme.json Reference and Publishing, Licensing & Monetization.
- [Publishing, Licensing & Monetization](https://sitepack.dev/docs/themes/publishing-and-monetization): Once your SitePack theme is developed, styled, localized, and thoroughly verified, you are ready to distribute it. SitePack provides a robust infrastructure for developers, accommodating both custom client themes and public marketplace monetization.
- [Template Hooks & App Blocks](https://sitepack.dev/docs/themes/template-hooks): To build a thriving, modular e-commerce ecosystem, SitePack themes must be fully compatible with third-party applications (such as review aggregators, loyalty programs, search boosters, and custom banners).
- [Theme Manifest & Settings Configuration (theme.json)](https://sitepack.dev/docs/themes/theme-json): The theme.json file is the mandatory manifest at the root of every SitePack theme. It registers your theme's identity with the platform and declares two kinds of merchant-facing customization:
- [Theme Translations & Internationalization](https://sitepack.dev/docs/themes/translations): SitePack includes native support for multi-language storefront translations. By utilizing localized translation dictionaries in JSON format, you can easily adapt your theme's headings, form labels, interface actions, and checkout messages for any country, region, or custom language profile.
- [Twig Global Objects & API Data Models](https://sitepack.dev/docs/themes/twig-objects): SitePack automatically injects fully-populated data models into your Twig templates depending on which page is being rendered. This guide is the definitive field-by-field reference for every object your theme can access — from the site object available everywhere, down to the page-specific product, category, cart, customer, blog/article, and sitemap objects.