Skip to content

Integration flow

The path from an empty panel to a subscription that renews by itself. Shop code is needed only in steps 3–8.

  1. Panel. Enable payment and at least one delivery method; optionally a discount and a palette. Without payment and delivery the shop is «not ready»: the subscribe button is not shown and open() rejects.

  2. Key and shop id. On the Integration tab generate an API key nc_live_… (shown once) and copy the shop ID. The key stays on the server; the ID goes into the data-shop-id attribute.

  3. Products (optional). PUT /v1/shop/products/{external_id} when a product is saved — title, variant, image, link. Can be skipped: an order adds its products to the catalogue anyway.

  4. Subscribe button. Embed the script and place <neocarts-button> under the «Buy» button. The shopper picks a frequency in the button’s window — the choice is kept by the widget.

  5. Cart → items. Before checkout pass the cart lines through getOrderItems(lines) — you get items with mode, interval_value, interval_unit.

  6. Order. Your server calls POST /v1/shop/orders/create with items, locale and an optional redirect_url. The 201 response is the order document in draft status; return order.id to the page. Cart changed before payment — PUT /v1/shop/orders/{order}/items; on 409 create a new order.

  7. Checkout. The page calls NeocartsSubscription.open({ orderId }). The shopper goes through contacts → delivery → review → payment in the Neocarts dialog.

  8. Result. The page receives neocarts:paid { number }: clear the cart. neocarts:order-missing — forget the stored id and create a new order. The server receives the order.paid webhook.

  9. Renewals. Neocarts sends a reminder 3 days ahead, charges the saved card, creates an order for each period and sends emails. On failure — up to 5 attempts, then a pause with reason charge_failed. Every change arrives as a webhook. See Recurring billing.

Where What
Site template the script and <neocarts-button> under the «Buy» button
Cart (browser) getOrderItems() → a request to your server → open({ orderId }); handlers for neocarts:paid and neocarts:order-missing
Server POST /v1/shop/orders/create with the API key
Server a webhook handler — for fulfilling orders and tracking subscriptions