Embedding
One script loads both widgets — the subscribe buttons and checkout. Add it to the site’s shared template.
<script src="https://cdn.neocarts.com/bundle.js" data-shop-id="SHOP_UUID" defer></script>| Attribute | Required | Description |
|---|---|---|
src |
yes | https://cdn.neocarts.com/bundle.js. Unversioned: always the current build, changes are backward compatible. |
data-shop-id |
yes | The shop ID (UUID). Needed by the subscribe buttons, config() and openHowItWorks(). |
defer |
recommended | The script does not block page loading. |
Once loaded, the script creates window.NeocartsSubscription, registers the <neocarts-button> element and dispatches neocarts:ready.
Where to find the shop id
Section titled “Where to find the shop id”In the shop panel: Settings → Integration, the «Shop ID» field. Unlike the API key, the shop id is not a secret.

SPAs and modules
Section titled “SPAs and modules”If the tag is added dynamically or the script is loaded as a module, data-shop-id cannot be read. Pass the shop id with a call:
NeocartsSubscription.init({ shopId: 'SHOP_UUID' });Buttons already on the page appear right after the call. init() can be called again with another shop.
When the widget is ready
Section titled “When the widget is ready”Your code may run before the script. Check the global object, and if it is not there yet, wait for neocarts:ready:
const ready = () => { const nc = window.NeocartsSubscription; // event subscriptions, config(), open()};if (window.NeocartsSubscription) ready();else document.addEventListener('neocarts:ready', ready, { once: true });Returning to checkout: ?neocarts=checkout
Section titled “Returning to checkout: ?neocarts=checkout”If the page address contains ?neocarts=checkout (or #neocarts-checkout), the widget reopens the shopper’s unfinished checkout in this browser and removes the marker from the address. If there is none, nothing happens.
Useful for the order’s redirect_url and «back to payment» links.
Content Security Policy
Section titled “Content Security Policy”If the site has a CSP, allow:
| Directive | Value |
|---|---|
script-src |
https://cdn.neocarts.com |
connect-src |
https://core.neocarts.com |
style-src |
https://fonts.googleapis.com |
font-src |
https://fonts.gstatic.com |
frame-src |
the shop’s payment provider domain (the payment page opens inside the checkout window) |
The payment provider domain depends on the provider in Settings → Payment.