Skip to content

Quickstart

The minimal integration: a subscribe button on the product page, one endpoint on your server that creates the order, and a call to open().

  1. Set up the panel. In the shop panel enable payment and at least one delivery method. Optionally set a subscription discount.

  2. Get the key and shop id. On Settings → Integration click «Generate new API key» and store it — it is shown once. Copy the «Shop ID» from the same tab.

    The Integration tab: shop ID, API key and webhooks

  3. Add the script and the button. The script — once per page; the button — under your own «Buy» button:

    <script src="https://cdn.neocarts.com/bundle.js" data-shop-id="SHOP_UUID" defer></script>
    <neocarts-button product-id="SKU-1" amount="249000" title="Brit Care Adult Large Breed"
    variant="12 kg" image="https://shop.example.com/i/brit.jpg"></neocarts-button>

    product-id is your product external_id; amount is the price of one unit in kopecks (249000 = 2,490.00 ₴). The shopper picks a frequency in the button’s window. See Subscribe button.

  4. Build items on the page. On «Checkout» pass the cart lines through getOrderItems() and send them to your server:

    const nc = window.NeocartsSubscription;
    const items = nc.getOrderItems([
    { external_id: 'SKU-1', title: 'Brit Care Adult Large Breed', variant: '12 kg',
    image_url: 'https://shop.example.com/i/brit.jpg', product_url: 'https://shop.example.com/p/brit',
    price: 249000, quantity: 1 },
    ]);
    const { orderId } = await fetch('/api/neocarts/order', {
    method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ items }),
    }).then((r) => r.json());
  5. Create the order on the server. Your endpoint calls POST /v1/shop/orders/create with the key and returns order.id:

    Terminal window
    curl -X POST https://core.neocarts.com/v1/shop/orders/create \
    -H "Authorization: Bearer nc_live_…" \
    -H "Accept-Language: en" \
    -H "Content-Type: application/json" \
    -d '{
    "locale": "en",
    "redirect_url": "https://shop.example.com/cart?neocarts=checkout",
    "items": [{
    "external_id": "SKU-1", "title": "Brit Care Adult Large Breed", "variant": "12 kg",
    "image_url": "https://shop.example.com/i/brit.jpg", "product_url": "https://shop.example.com/p/brit",
    "price": 249000, "quantity": 1,
    "mode": "subscription", "interval_value": 4, "interval_unit": "week"
    }]
    }'

    Check line prices against your own database — do not trust prices that came from the browser. Fields and errors — Orders.

  6. Open checkout and listen to events.

    await nc.open({ orderId });
    nc.on(nc.events.Paid, ({ number }) => { /* clear the cart, show the number */ });
    nc.on(nc.events.OrderMissing, () => { /* forget orderId, create a new order */ });

    See Checkout and Events.

  7. Test it. Go through checkout as a shopper. On staging payment runs in a sandbox with no real money (Environments); on production pay a small order and refund it from the panel. After payment the order becomes paid, an active subscription appears, and the page receives neocarts:paid.

Next: integration flow, webhooks, troubleshooting.