Partner kit

API reference

The Shoppi SDK, the JSON API and TagCodes: everything a partner needs to build on a Shoppi store.

SDK 2.7.5 JSON API Stripe Checkout TagCodes
How it worksSetupStore and content — Shoppi.siteCart — Shoppi.cartCheckout — Shoppi.checkoutCustomer accounts — Shoppi.userNavigation and translations — Shoppi.router, Shoppi.langLocal directory — Shoppi.localEmail — Shoppi.mailerJSON APITagCodes (server-side)Files and data access

How it works

Every store on Shoppi Cloud can be extended with the Shoppi SDK, a JavaScript library served by the platform on every Shoppi-hosted domain, and with TagCodes, server-side placeholders the page engine resolves before the page reaches the browser. Both talk to the same JSON API, which is also available directly.

  • No API keys in the browser. The store is identified by the domain the request is made from, so the SDK works on the store's own domain without secrets in your code.
  • Payments go through Stripe. Checkout sessions are created on the merchant's own Stripe account (Stripe Connect); Shoppi never holds the merchant's customers' money. Refunds also run entirely through Stripe.
  • Every store has its own database. Customers registered through the SDK are stored in the store's own database, separate from other stores.
  • Current SDK version: 2.7.5. Responses use one envelope: {"result": "ok" | "ko", "feedback": …}.

Setup

Include the SDK once, in the page <head>. It creates a global window.Shoppi object on load.

<script>
window.ShoppiConfig = {
    pageId:        "%_ID%",  // store id; the page engine fills it in (use %_ID% inside JS, not {id})
    currency:      "EUR",    // default currency for cart and checkout
    defaultLocale: "it",     // language used when the URL has no /xx/ prefix
    baseUrl:       ""        // leave empty: API calls go to the same origin
};
</script>
<script src="/shoppi/shoppi-sdk.js?v=2.7.5"></script>

All settings are optional: without ShoppiConfig the SDK resolves the store from the domain and uses EUR. Bump the ?v= parameter when you want browsers to fetch a newer SDK.

Store and content — Shoppi.site

Method Returns
Shoppi.site.getInfo() Store profile: name, logo, description.
Shoppi.site.getPage(slug) A content page by its slug, e.g. 'about-us'. Returns title and HTML content. 
const info = await Shoppi.site.getInfo();
document.getElementById('store-name').textContent = info.title;

Cart — Shoppi.cart

The cart lives in the browser (localStorage) and survives reloads. Prices and titles you pass travel to checkout, so always set them.

Call What it does
Shoppi.cart.add(id, qty, { price, title, image }) Adds a product (qty defaults to 1).
Shoppi.cart.updateQty(id, qty) Sets the quantity; 0 removes the line.
Shoppi.cart.remove(id) Removes a line.
Shoppi.cart.clear() Empties the cart.
Shoppi.cart.setCountry(code) Sets the shipping country (ISO code, e.g. 'IT').
Shoppi.cart.data Current state: { items, count, total, country }.

Without JavaScript, using HTML attributes:

<button data-shoppi-add="10034"
        data-shoppi-price="29.90"
        data-shoppi-title="Leather wallet"
        data-shoppi-image="/img/wallet.jpg">Add to cart</button>

<span class="shoppi-cart-count"></span>   <!-- item count, updated automatically -->
<span class="shoppi-cart-total"></span>   <!-- total, formatted in the store currency -->

<select data-shoppi-country>              <!-- shipping country -->
  <option value="IT">Italia</option>
  <option value="DE">Deutschland</option>
</select>

<button data-shoppi-checkout>Checkout</button>

Checkout — Shoppi.checkout

Method What it does
Shoppi.checkout.start() Creates a Stripe Checkout session for the current cart on the merchant's Stripe account and redirects the customer to it.
Shoppi.checkout.startDirect(productId, metadata) One-click purchase of a single product, without the cart (services, bookings, downloads).
Shoppi.checkout.createOnboardingLink() Returns the Stripe onboarding URL for the store, to connect or complete its Stripe account. 
document.querySelector('#buy').addEventListener('click', () => Shoppi.checkout.start());

// Stripe onboarding for the merchant
const url = await Shoppi.checkout.createOnboardingLink();
window.location.href = url;

Any button with data-shoppi-checkout does the same as Shoppi.checkout.start(). Payment fees follow the store's plan: Stripe processing fees plus the Shoppi Pay app fee of 0.4% + 1 minor currency unit per payment. Refunds, full or partial, online or at the POS, are issued through Stripe too.

Customer accounts — Shoppi.user

Accounts for the store's own customers, stored in the store's database. After login the session token is kept in the browser and sent with every SDK request in the X-User-Token header.

Method What it does
Shoppi.user.register(email, password, firstName, lastName) Creates an account and logs in.
Shoppi.user.login(email, password) Logs in.
Shoppi.user.getProfile() Profile of the logged-in customer (null when logged out).
Shoppi.user.updateProfile(data) Updates profile fields, e.g. { phone }.
Shoppi.user.saveAddress(type, address) Saves an address; type is e.g. 'shipping'.
Shoppi.user.logout() Clears the session and reloads the page.

URLs follow /<language>/<page>, e.g. /it/contatti. Shoppi.router.navigate(slug, locale) loads a page without a full reload and renders it in <main>; links with data-shoppi-link do the same.

<a href="/it/contatti" data-shoppi-link="contatti">Contatti</a>

Shoppi.lang.load(locale) loads the store's translations; Shoppi.lang.t(key, vars) returns a string and replaces placeholders written as %_NAME%.

Local directory — Shoppi.local

Method Returns
Shoppi.local.getCities() Cities available in the local directory.
Shoppi.local.getBusinesses(cityId, categoryId) Businesses in a city, optionally filtered by category.

Email — Shoppi.mailer

Sends a transactional email from the store, e.g. a contact form. Limited to 10 emails per day per device.

await Shoppi.mailer.send({
    to:      '[email protected]',
    subject: 'New request from the website',
    body:    '<p>Hello!</p>',
    replyTo: '[email protected]'   // optional
});

Shoppi.mailer.remaining();   // emails left today on this device

JSON API

Every SDK method is a call to the JSON API, which you can use directly with Shoppi.call(endpoint, params, method) or plain fetch: the pattern is /api/<module>/<method>/json, on the store's own domain.

Endpoint Purpose
GET /api/website/info/json Store profile
GET /api/website/section/<slug>/json Content page
POST /api/checkout/createStripeSession/json Stripe Checkout session from a cart
POST /api/checkout/startDirect/json Direct purchase of one product
GET /api/checkout/createOnboardingLink/json Stripe onboarding link
POST /api/frontend_user/register/json Customer sign-up
POST /api/frontend_user/login/json Customer login
GET /api/local/getCities/json Local directory: cities 
const res  = await fetch('/api/website/info/json', { credentials: 'include' });
const data = await res.json();   // { "result": "ok", ... }  or  { "result": "ko", "feedback": "reason" }

Shoppi.call() returns the useful part of an ok response and throws an Error with the feedback message on ko.

TagCodes (server-side)

TagCodes are placeholders in the store's HTML templates, resolved on the server before the page is sent, so the content is in the HTML that search engines see.

TagCode Output
{css} / {js} Stylesheets and scripts of the page and its plugins
{page_title}, {page_description} SEO title and description
{page_name}, {page_logo} Store name and logo
{locale}, {currency}, {country} Active language, currency, visitor country
{title}, {content}, {photo}, {price}, {link} Fields of the current product or article
{cfield:title}, {cfield:description}, {cfield:cover} Store profile fields
{cart:act=drawer} Cart side drawer
{search:nout=true} Search, initialised without default output
{cookieconsent} Cookie consent banner
{offers:act=seo} JSON-LD structured data for products

Inside a JavaScript object literal use %_ID% for the store id: braces there are read as a TagCode.

Files and data access

Each store's files are reachable over WebDAV (also through the Shoppi Go desktop app), and its data stays exportable: standard HTML templates, the store's own database, and the JSON API above. Access credentials are in the store's account panel.

Questions or a use case not covered here? Book a call with the partner team, or go back to the partner kit.