@neuron-cart/sdk

Typed server-side client for Neuron Cart — carts, checkout, and orders for any storefront. No dependencies.

npm i @neuron-cart/sdk

Need a key? Sign up at cart-admin.neuroncommerce.com/signup — free, and new stores work immediately against a sandbox (client-side pricing, mock payments, free shipping) so you can take a real order before configuring anything.

Quick start

import { createNeuronCart } from '@neuron-cart/sdk';

const neuron = createNeuronCart({
  apiUrl: process.env.NEURON_CART_API!, // https://cart-api.neuroncommerce.com/v1
  apiKey: process.env.NEURON_CART_KEY!, // cs_live_… — server-side only
});

const cart = await neuron.carts.create();

await neuron.carts.addItem(cart.id, {
  sku: 'SPACE-TEE',
  quantity: 1,
  // Developer mode prices from metadata; in production your
  // product.validate webhook is the authority and this is ignored.
  metadata: { unitPriceCents: '2499', name: 'Space Tee' },
});

The API key never goes to the browser. Use this from your server (Astro API routes, Next.js route handlers, Express, edge functions) and have client code call your routes.

Checkout, end to end

await neuron.checkout.initiate(cart.id);
await neuron.checkout.setShippingAddress(cart.id, {
  firstName: 'Ada', lastName: 'Lovelace', line1: '1 Fremont St',
  city: 'Las Vegas', state: 'NV', postalCode: '89101', email: '[email protected]',
});

const { rates } = await neuron.checkout.getShippingRates(cart.id);
await neuron.checkout.setShippingRate(cart.id, {
  rateId: rates[0].id, rateName: rates[0].name, amount: rates[0].amount,
});

const { paymentIntent } = await neuron.checkout.createPaymentIntent(cart.id);
const order = await neuron.checkout.confirm(cart.id, {
  paymentIntentId: paymentIntent.id,
  billingAddress: { /* … */ },
  email: '[email protected]',            // required for guest checkout
});

order.orderNumber; // ORD-2026-00001

Storefront proxy

@neuron-cart/sdk/server ships the server proxy every integration ends up writing — tenant-key injection, customer-cookie forwarding, transparent 401 refresh with cookie rotation, and outage mapping:

// Next.js: app/api/cart/[...path]/route.ts
import { createCartProxy } from '@neuron-cart/sdk/server';

const proxy = createCartProxy({
  apiUrl: process.env.NEURON_CART_API!, // origin, no /v1
  apiKey: process.env.NEURON_CART_KEY!,
});

export const { GET, POST, PUT, PATCH, DELETE } = proxy.nextHandler();

Framework-agnostic underneath (Web-standard Request/Response), so it works outside Next.js too.

Customer accounts — phone-first

Text a code, verify it, done. First-time numbers get a customer created on the spot, and any guest orders matching the phone/email link to the account server-side:

// Step 1 — from your server route. Sandbox tenants need no bot check:
// getConfig().turnstileSiteKey is null there, so no widget and no token.
await neuron.auth.requestOtp({ phone: '+17025550100' });

// Step 2 — exchange the texted code for a session
const { token, refreshToken, customer, expiresIn } =
  await neuron.auth.verifyOtp({ phone: '+17025550100', code: '123456' });

Keep token server-side (httpOnly cookie; expiresIn is in milliseconds) and pass it as customerToken on later calls — that scopes orders to the shopper and stamps new orders with their identity:

const me     = await neuron.customers.me({ customerToken: token });
const orders = await neuron.orders.list({ customerToken: token });
await neuron.checkout.confirm(cartId, input, { customerToken: token });

Email + password (auth.register / auth.login), email OTP, and auth.refresh / auth.logout round out the surface. When getConfig().turnstileSiteKey is non-null, render the Cloudflare Turnstile widget with it and pass the widget's token as turnstileToken on requestOtp / requestEmailOtp.

Verified phone at checkout

Some stores treat a proven phone number as a fraud control. getConfig() tells you which kind you're integrating with:

const { phoneVerificationPolicy, phoneOtpEnabled } = await neuron.getConfig();
// 'off'      — don't ask
// 'optional' — offer it; checkout completes either way
// 'required' — confirm WILL be refused until the phone is verified

'required' is already degraded to 'optional' server-side when the store cannot send codes, so you don't have to cross-check phoneOtpEnabled before trusting it.

Put the number on the shipping address, then verify that same number — the gate reads shippingAddress.phone:

await neuron.checkout.setShippingAddress(cartId, { ...address, phone });
await neuron.auth.requestOtp({ phone, disclosure: 'OTP_CHECKOUT' });
await neuron.auth.verifyOtp({ phone, code });   // stamps the verification

Show SMS_DISCLOSURE.OTP_CHECKOUT before you ask, and pass the matching key so the consent log records what was on screen.

Enforcement is server-side at payment-intent, wallet express, and confirm — a client-side flow is not an enforcement point. Handle PHONE_VERIFICATION_REQUIRED (422) as "send them back to the verify step", never as a generic failure. A shopper who verified on a previous visit carries customer.phoneVerifiedAt and needs no second challenge.

After the order, orders.enableSmsNotifications(orderId) turns on delivery texts for guests and account holders alike — no phone argument, so it can only ever opt in the number already on the order.

API surface

| | | |---|---| | carts | create, get, getBySession, addItem, updateItem, removeItem, clear | | checkout | initiate, setShippingAddress, getShippingRates, setShippingRate, createPaymentIntent, confirm | | orders | list, get, getByNumber, shipments, enableSmsNotifications | | auth | register, login, refresh, logout, requestOtp, verifyOtp, requestEmailOtp, verifyEmailOtp | | customers | me | | getConfig() | Store name, currency, developerMode, turnstileSiteKey, phoneVerificationPolicy, addressProvider (+ its browser key), and adminUrl (deep link to this store's admin) | | request() | Escape hatch for endpoints not yet wrapped |

Failures throw NeuronCartError with the API's code (CART_NOT_FOUND, EMAIL_REQUIRED, …) and statusCode.

Scaffold instead

npm create neuron-astro-store@latest my-store

A complete Astro storefront using this SDK — catalog, cart, checkout, order page, and an operator shortcut to your admin.

Docs

neuroncommerce.com/developers

MIT © Xumulus Inc.

Neuron Cart™ and Neuron Commerce™ are trademarks of Xumulus Inc. Other product names and logos are the property of their respective owners.