For developers
Connect a shop to NEURA
NEURA's assistants answer shoppers from the shop's own data. You do two things: build a small bridge so NEURA can read the shop, and add one line to the shop's pages for the chat box. Any shop can connect, including one you built yourself.
GET.- 1Build the bridgeYou
- 2Say what your shop can doYou
- 3Check your workYou and the shop owner
- 4Connect your shopThe shop owner
- 5Add the chat boxYou and FiveNeurals
Before you start
https://api.fiveneurals.com/v1/developers/mcp
1 · Build the bridge
First ask FiveNeurals whether a ready-made bridge exists for the shop's system. If it does, install it like any other add-on and go to step 2. If not, build the addresses below. Put them under any prefix, usually /neura/v1.
| Address | Gives the assistant |
|---|---|
GET /health | What your shop can do (step 2) |
GET /products | A page of products, and search |
GET /products/{id} | One product |
| Address | Gives the assistant |
|---|---|
GET /inventory | Stock: whether something can be bought now |
GET /policies | Returns, shipping and warranty pages |
GET /categories | Your categories: what you do sell when nothing fits |
| Address | Gives the assistant |
|---|---|
GET /orders | A page of orders, and search by email or order number |
GET /orders/{id} | One order |
GET /customers/{id} | One customer, never a member of staff |
- Everything is GET. No address changes anything in the shop.
- Check the shop token on every address except
/health. NEURA sendsAuthorization: Bearer <shop token>; refuse a request without it. Read the token from a setting, for exampleNEURA_SHOP_TOKEN, never from code. The shop owner makes the real token in their NEURA dashboard and sends it to you; until then, put any text in that setting to test. - Pages by cursor, not page number. Return an opaque
next_cursor; NEURA sends it back unchanged. - The exact format of every answer is in the OpenAPI file you downloaded.
GET /products/1042{
"external_id": "1042",
"title": "Wool Hiking Socks",
"description": "Warm merino socks for long walks.",
"status": "active",
"url": "https://yourshop.example/products/wool-hiking-socks",
"image_urls": ["https://yourshop.example/images/wool-hiking-socks.jpg"],
"category_ids": ["12"],
"variants": [
{
"external_id": "1042-m",
"title": "M",
"options": { "size": "M" },
"price": { "amount": "12.00", "currency": "EUR" },
"in_stock": true,
"stock_quantity": 8
},
{
"external_id": "1042-l",
"title": "L",
"options": { "size": "L" },
"price": { "amount": "12.00", "currency": "EUR" },
"in_stock": false,
"stock_quantity": 0
}
]
}- Each size or colour is a variant, with its own price and stock. A product with neither still needs one variant: that is where its price and stock go.
- "in_stock" is true only if it can be bought now. Here size M can, size L can't.
- A price is text and a three-letter currency:
"12.00"and"EUR". - The list,
GET /products, sends the same product, many at a time, in"items".
2 · Say what your shop can do
/health tells NEURA what your bridge can do. The assistant gets only what is on this list, so it is the one answer to get exactly right.
{
"status": "ok",
"spec_version": "1.0",
"platform": "yourshop",
"capabilities": [
"product.read",
"product.search",
"inventory.read",
"policy.read",
"category.read"
]
}| Field | What to write |
|---|---|
status | Exactly "ok".Anything else, even "healthy", and NEURA treats your shop as down. |
spec_version | "1.0", the version of this format.The check tool fails without it. |
platform | Your shop system's name, in any words. For information only. |
capabilities | What your bridge can do: the table below. |
| You built | Write this word |
|---|---|
| 1. Start with these three | |
GET /health | nothingThis address is the list itself. |
GET /productsGET /products/{id} | product.read |
Search: GET /products?q=… | product.search |
| 2. Add these for better answers | |
GET /inventory?variant_ids=… | inventory.read |
GET /policies | policy.read |
GET /categories | category.read |
| 3. Only for order questions | |
GET /orders/{id} | order.read |
Search: GET /orders?email=…Also by phone, customer_id and order_number. | order.search |
GET /customers/{id} | customer.read |
| Extras | |
GET /products?updated_since=…Returns only what changed since then. | sync.incrementalOptional. Without it, NEURA reads every product each time. |
| Change messagesYour shop tells NEURA when something changes. | nothing yetNEURA can't receive them yet. Leave out events.realtime. |
product.search while your search still finds nothing, and the assistant tells shoppers you don't sell things you do. The check tool in step 3 can't tell either.No token on this one. /health is the only address anyone may open, so you can check your bridge from a browser. Put no shop data in it.
3 · Check your work
The shop owner runs the check from their NEURA dashboard, as often as you need. There is no tool to download. It asks your bridge about 20 questions, the way the assistant will, and names anything wrong. Every question is a GET, so nothing in the shop changes.
- 1The shop owner sends you the shop tokenShop ownerThey make it in their NEURA dashboard. Put it in your bridge's setting, in place of your test text.
- 2Put your bridge onlineYouAt an
https://address on the public internet. NEURA won't calllocalhost, a private network or plainhttp://. - 3Send the shop owner the bridge's addressYouThe exact address on your live shop, for example
https://yourshop.example/neura/v1. NEURA doesn't follow redirects. The address that passes is the one that gets connected, and it can't be changed afterwards. - 4The shop owner presses CheckShop ownerIf something is wrong, they send you the full check. Fix what it names, then ask them to check again.
NEURA check · https://yourshop.example/neura/v1 · 2026-10-01 09:30 UTC
✘ auth.rejects_wrong_token /orders accepted an invalid bearer token (HTTP 200)
→ The token is being ignored rather than verified.
⚠ products.search_no_match search returned results for nonsense text
→ Over-broad matching floods the agent's context with irrelevant products.
✔ health ok
✔ products.get_missing ok
…
18 passed · 1 failed · 1 warning(s)- ✘A problem. The shop owner can't connect while there is one.
- ⚠A warning. It doesn't stop the owner connecting, but each one means a worse answer for a shopper. Fix it anyway.
- Stock. A sold-out product says
"in_stock": false. - Prices. The same as on the shop's page, with the currency as three capital letters, such as
EUR. - Hidden products. One the shop doesn't show yet comes as
"status": "draft". The assistant never mentions a draft. - Customers. If you built
/customers/{id}, a member of staff's id answers404.
4 · Connect your shop
You have nothing to press here. The shop owner connects the shop in their dashboard, and NEURA reads it for the first time.
- 1The shop owner presses ConnectShop ownerIn their dashboard: Connect and copy my catalogue. It works only after a check with no problems.
- 2NEURA copies the shop's catalogueNEURAYour products, page by page, and your categories and policy pages if you built them. Orders and customers are not copied.
- 3The owner sees Your shop is connectedShop ownerThen Your catalogue is copied, with the number of products.
- Keep the bridge online, at the same address. The assistant asks it questions live while shoppers chat: searches, products, stock.
- Keep the shop token secret. Never in a web page, the browser or a public code repository. NEURA can't show it again, not even to the shop owner: if it's lost, the owner makes a new one.
- A new token from the owner? Put it in straight away. Until you do, the assistant can't read the shop, and the old token still works for whoever has it. Then ask the owner to press Check again.
5 · Add the chat box
One line of HTML puts the chat box on the shop's pages.
- 1Send FiveNeurals the shop's web addressesYouEvery exact address the chat box will run on, for example
https://yourshop.exampleandhttps://www.yourshop.example, and a test site if you have one. One key can cover them all. - 2FiveNeurals makes the chat box keyFiveNeuralsA public key that starts with
fn_pk_. It works only from the addresses you sent. A key from a NEURA test system starts withfn_pk_test_. It works the same way, and “test” has nothing to do with practice mode. - 3Add the line to every page shoppers seeYouNot your admin pages: staff questions would use AI and mix with real shoppers' chats.
<script src="https://api.fiveneurals.com/v1/widget/widget.js" async
data-neura-key="fn_pk_…"></script>- The key is public, and that's fine. It works only from the addresses it was made for.
www.and nowww.,httpandhttps, are different addresses. - Never put a secret key in a page. Secret keys start with
fn_sk_, and anyone can read a page's source. NEURA refuses one there, and the chat box says why. - Keep the key in the shop's settings, like the shop token, not in the template. A new key then needs no code change.
- It won't break your page. One file, no dependencies, loaded
async. It draws itself in its own box, so your styles don't reach it. - Strict content security policy? Allow our address in
script-src, and inconnect-srcwith bothhttps://andwss://. Nounsafe-inlineneeded.
- Open a shop page: the chat button appears at the bottom right.
- Send one test message (it uses AI). The shop owner's dashboard then shows The chat box is on your shop.
- In practice mode, every reply is a short your message has been received note. The owner reads the real reply in Review.
- Every message gets We could not reach the assistant? The page's address is probably not on the key: check
www.,httporhttps, and the test site.
data-neura-key- The chat box key. Required
data-neura-title- The panel's heading. Default Chat with us
data-neura-opentrueopens the panel when the page loadsdata-neura-agent- Usually leave it out: NEURA picks the right assistant for each question.
care(questions about the shop) orsell(help choosing) sends every question on the page to that one data-neura-api- Only if you serve
widget.jsfrom somewhere else: NEURA's address. By default, the address the file came from data-neura-products- The products a page shows, for suggestions. See below
data-neura-pairs-auto-opentruelets a suggestion open the panel. See belowdata-neura-customer-pass- A signed-in customer's pass, for order questions. See Optional: order questions
data-neura-sign-in-url- Your sign-in page, for order questions. See Optional: order questions
<script src="https://api.fiveneurals.com/v1/widget/widget.js" async
data-neura-key="fn_pk_…"
data-neura-products="1042,1077"></script>- The ids your bridge sends (each product's
external_id), separated by commas. At most 10 count. - Only on the page that shows them, usually the basket. The line normally lives in a shared layout: let that page hand the layout its ids, and leave the setting out everywhere else.
- This uses AI. The first time a product appears here, NEURA asks an AI model once, in the background, what goes with it, and keeps the answer. The shopper never waits.
- Want the panel to open by itself? Add
data-neura-pairs-auto-open="true". It opens at most once per visit, and only when there is a suggestion. Off by default. - Nothing shows? Failures here are silent on purpose: the shopper is about to pay. Look at the
suggestionsrequest in your browser's Network tab, and ask the shop owner whether their shop has suggestions.
Optional: order questions (part of NEURA-CARE)
NEURA-CARE can answer “Where is my order?” in the chat box for a shopper who is signed in to the shop, and only about their own orders. Your shop's server tells the chat box who is signed in, with a short-lived pass that only your server can make.
It needs the order addresses from step 1 (group 3), listed in /health. With order.read, the assistant answers about an order by its number. Add order.search and customer.read, and it also finds a shopper's orders when they don't give one.
- 1The shop owner makes the secretShop ownerOn Shop connection in their NEURA dashboard: Make the secret. NEURA shows it once, and they send it to you. It starts with
fn_cs_. - 2Keep it on your shop's serverYouIn a setting, for example
NEURA_CUSTOMER_SECRET, like the shop token. Never in a web page: anyone who has it can make a pass for any customer. NEURA refuses it in a page. A new secret from the owner stops the old one at once, so put it in straight away. - 3Make a pass on every page a signed-in customer opensYouYour server makes a fresh one each time it draws the page, and writes it into the chat box line. Nobody presses anything.
fn_cs_ included, exactly as the shop owner sent it. Any JWT library makes one in a few lines:use Firebase\JWT\JWT; // composer require firebase/php-jwt
// $customerId: from your shop's own sign-in session, never from the request.
$now = time();
$pass = JWT::encode([
'sub' => (string) $customerId, // text, exactly as your bridge sends it
'iat' => $now,
'exp' => $now + 15 * 60, // at most 15 minutes
], getenv('NEURA_CUSTOMER_SECRET'), 'HS256');const jwt = require("jsonwebtoken"); // npm install jsonwebtoken
// customerId: from your shop's own sign-in session, never from the request.
const pass = jwt.sign(
{ sub: String(customerId) }, // text, exactly as your bridge sends it
process.env.NEURA_CUSTOMER_SECRET,
{ algorithm: "HS256", expiresIn: "15m" }, // adds iat and exp: at most 15 minutes
);sub- The signed-in customer's id, as text: the same id your bridge sends as
customer_external_idon their orders, because NEURA keeps only the orders whose id matches. Write it in quotes,"385", not385: NEURA refuses a number. Up to 128 characters iat- When you made the pass, in seconds since 1 January 1970 (Unix time). A pass made more than a minute ahead of NEURA's clock is refused, so keep your server's clock right
exp- When the pass stops working: at most 15 minutes after
iat. A shopper who keeps a page open longer is asked to reload it, which makes a new pass
These three and nothing else: NEURA refuses a pass with any other field, so a name or an email is never sent by mistake. It also refuses a pass signed any way but HS256.
<script src="https://api.fiveneurals.com/v1/widget/widget.js" async
data-neura-key="fn_pk_…"
data-neura-customer-pass="eyJhbGciOiJIUzI1NiIs…"
data-neura-sign-in-url="https://yourshop.example/login"></script>data-neura-customer-pass- The pass, only when the shopper is signed in. For everyone else, leave the setting out: no pass means not signed in
data-neura-sign-in-url- Optional. Your shop's sign-in page, as a full address with
https://. A shopper who isn't signed in and asks about an order gets a Sign in link to it. A short address such as/loginshows no link
- Only from your shop's own sign-in session. Take the customer's id from the session your shop already uses to know who is signed in. Never from anything in the request, such as
?customer=385, and never build an address that makes a pass for whoever asks: anyone could then read another customer's orders. - Never cache a page that carries a pass. Send it with
Cache-Control: private, no-store, and keep it out of your shop's own page cache. A cached copy would give one customer's pass to everyone who opens the page, for up to 15 minutes, or keep showing the same customer a pass that has stopped working.
- Signed in
- Answers about their own orders: status, items and tracking. Another customer's order number gets the same answer as a number that doesn't exist.
- Not signed in
- “Please sign in to your account so I can help with your orders. Or contact our store:” and the shop's contact details from the dashboard. With
data-neura-sign-in-url, a Sign in link under it. The same words whatever order number they type, so nobody can find out which orders exist. - Signed in, page open longer than its pass
- “Your sign-in on this page has timed out. Please reload the page and ask again.”
- On a shop that is live, sign in as a test customer with an order, open a page and ask Where is my order? The assistant answers about that customer's orders. In practice mode the shopper sees only the received note (step 5).
- Each answer says what NEURA made of the pass, in
customer_pass:valid,expiredorinvalid, andnullwhen the page sent none. Why, incustomer_pass_reason. Find it in your browser's Network tab: the chat's live connection (stream, under Messages), or thechatrequest when there is no live connection. invalid? The browser's console says why, once per page, after the first message: NEURA: the customer pass in data-neura-customer-pass was refused, so this shopper is treated as not signed in: and the reason.- Sign out and ask again: you are asked to sign in.
Optional: product views (part of NEURA-SELL)
NEURA-SELL can show the shop owner a Sold out list: sold-out products that shoppers kept opening in the last 7 days. See what the owner sees
For it, your shop's server tells NEURA each time a shopper opens a product or adds one to the basket. Build it only if the shop owner wants it.
- 1The shop owner decides, and signs a data agreementShop ownerWith FiveNeurals. Without it, NEURA stores nothing about shoppers.
- 2FiveNeurals makes your secret keyFiveNeuralsIt starts with
fn_sk_and is made for sending product views. It can only be made once the agreement is recorded. - 3Build a setting, off by default, and the sendingYouWhile the setting is off, your server sends nothing. NEURA has no switch of its own: what it receives, it keeps.
- 4The shop owner turns the setting onShop ownerOnce the shop asks its shoppers for permission. The agreement makes that the shop's job, so ask the shop owner how it is done.
POST https://api.fiveneurals.com/v1/observe/events
Authorization: Bearer fn_sk_…
Content-Type: application/json
{
"event_id": "ev_7f3a9c2e1b4d4e8a",
"session_id": "s_2c9e41b7d05f4a63",
"type": "product.viewed",
"product_id": "1042",
"occurred_at": "2026-10-01T09:30:00Z",
"in_stock": false
}event_id- Your own id for this event: 16 to 64 characters, using only a to z, A to Z, 0 to 9, hyphens (-) and underscores (_). Send the same one again and it counts once, so a retry is safe
session_id- One per shopper visit, so the list counts visits and not only views: 16 to 128 characters, the same kinds as
event_id. Never the shop's session cookie itself: make it from the session with a secret only your server holds (a keyed hash) typeproduct.viewedwhen a shopper opens a product page.cart.addedwhen a product goes into the basket, once the add workedproduct_id- The product's
external_id, exactly as your bridge sends it, up to 128 characters. Dots, slashes and spaces are fine occurred_at- When it happened, with a time zone. Not older than 7 days, and not more than 5 minutes ahead
in_stock- Views only: could the product be bought at that moment (at least one variant in stock),
trueorfalse. Leave it out ofcart.added
Send these six fields and nothing else. NEURA refuses a request with any other field, so nothing more about a shopper can be sent by mistake.
- From your server only. Never from the shop's pages: anyone can read a page, and NEURA refuses a secret key sent from one.
- Nothing about who the shopper is. No name, email, IP address or browser details.
- Never slow a page down. Send in the background, for example from a queue.
- Nothing for search-engine robots. Check the browser details on your server against a list of known robots, and send nothing for one, or for a request with none. A robot keeps no cookie, so each page it reads would count as a new visitor who never adds to the cart. The browser details themselves are still never sent.
- Kept for 7 days, then deleted. If the agreement ends, everything is deleted at once.
- Each event is answered
202with"stored": true. The sameevent_idagain is answered"stored": false: it was already counted. - A wrong or extra field is answered
400, and the error names the field. 403withDPA_REQUIRED: the agreement isn't recorded yet. Ask the shop owner.
Webhooks to NEURA
Messages your shop's server sends to tell NEURA that a product or order changed. Step 2 calls them change messages.
entityChanged, under webhooks): skip that part for now, and leave events.realtime out of your list (step 2).You lose nothing. The chat box asks your bridge live, so it sees a new product or a stock change straight away. Only NEURA's own copy of the catalogue, used by the shop owner's dashboard, waits until the owner presses Sync now.
If something doesn't work
- The bridge refused the shop token
- The token in your bridge's settings isn't the one the shop owner made. Put theirs in exactly, then ask them to press Check again.
- Could not reach the address
- Your bridge isn't online at that address, or the address isn't public. NEURA calls only public
https://addresses (step 3). - There is no bridge at this address
- The address isn't your bridge's (send the one
/healthsits under), or it redirects. NEURA doesn't follow redirects (step 3). - Its
"status"is not"ok" /healthmust answer"status": "ok", exactly (step 2)./healthpasses, everything else fails- Usually your bridge's database settings. A
/healththat doesn't touch the database stays green while every other address fails.
- The chat button doesn't appear
- The line isn't on this page (look in the page's source), a strict content security policy blocks it (step 5), or the shop still serves an old cached page.
- Every message gets We could not reach the assistant
- The page's address isn't on the chat box key: check
www.,httporhttps, and the test site (step 5). - A secret key may not be used from a web page
- The line holds a secret key (
fn_sk_). Put the chat box key (fn_pk_) there, and keep secret keys on your server.
- It says the shop doesn't sell something it does
- An item listed in
/healthwhose address isn't built: NEURA reads its 404 as “nothing there” (step 2). Or your search misses the words shoppers use: try them on/products?q=yourself. - A sold-out product is called in stock, or a price shows the wrong currency
- Compare your bridge's answers with the shop by hand (step 3):
in_stock, and a three-letter currency code.
- The console says the signature does not match
- Your setting doesn't hold the shop's current secret. Use the whole secret,
fn_cs_included, exactly as the owner sent it. A new secret from the owner replaces the old one at once. - The console says this shop has no customer sign-in secret yet
- Ask the shop owner to press Make the secret on Shop connection.
- The console says sub must be text
- The customer's id went in as a number. Turn it into text:
(string) $customerIdin PHP,String(customerId)in Node.js. - Signed in, but asked to sign in
customer_passisnull: the page has no pass. Look fordata-neura-customer-passin the page's source. Missing on a page you know you added it to? A cache served an old copy.- Signed in, but the assistant finds no orders
subisn't the id your bridge sends ascustomer_external_idon that customer's orders. Compare the two for your test customer.
- The Sold out list stays empty
- It lists only products opened while they were sold out, so check one was. Then read NEURA's answer to your request:
403 DPA_REQUIREDmeans no agreement yet, and a400names the wrong field. No request at all? The setting is off.