Developer sandbox
Build and test against NinjaBuy with test keys, fake money and simulated orders.
The developer sandbox is a separate copy of NinjaBuy for building and testing integrations. It runs the same REST API and the same MCP server as the live site, but it holds only test data: fake money, test orders and test tracking numbers. Nothing you do there reaches a real customer, a real seller or a real payment, and nothing there carries over to your live account.
| Live | Sandbox | |
|---|---|---|
| Site and sign-in | https://www.ninjabuy.com | https://sandbox.ninjabuy.com |
| REST API | https://www.ninjabuy.com/api/v1 | https://sandbox.ninjabuy.com/api/v1 |
| MCP server | https://www.ninjabuy.com/mcp | https://sandbox.ninjabuy.com/mcp |
| API keys start with | nb_ | nb_test_ |
Get a sandbox key
- Open
https://sandbox.ninjabuy.comand sign in with a phone number. The sandbox sends no texts: enter the code000000. - Open Account → Settings → API keys and create a key, as described in API keys. A sandbox key starts with
nb_test_.
A sandbox key works only on the sandbox, and a live key only on the live site. Sending a sandbox key to the live API returns 401 with the problem type sandbox-key.
Sandbox accounts are not private. Anyone who signs in to the sandbox with the same phone number reaches the same sandbox account, so use a number of your own, and never put real customer data in the sandbox.
Call the REST API
Every route in this guide works on the sandbox. Swap the host and send your sandbox key:
curl -sS "https://sandbox.ninjabuy.com/api/v1/search?q=desk%20lamp" \
-H "Authorization: Bearer $NINJABUY_SANDBOX_KEY"Search reads real marketplace listings, so the products and prices you get back are real. Links you create in the sandbox point at the sandbox and credit your sandbox account only.
Place a test order
Orders are handled through the MCP server's order tools. Connect your client to https://sandbox.ninjabuy.com/mcp the way Use NinjaBuy in ChatGPT and Claude describes. Sign-in uses the sandbox's own OAuth, with the 000000 code. For example:
claude mcp add --transport http ninjabuy-sandbox https://sandbox.ninjabuy.com/mcpThe sandbox adds three tools that the live server does not have:
| Tool | What it does |
|---|---|
sandbox_add_funds | Adds test money to the wallet, up to ¥100,000 per call. |
sandbox_place_order | Pays for the cart's ticked lines from the wallet and places the order. Reusing an idempotency_key returns the first order instead of paying again. |
sandbox_advance_order | Runs the order's next step now instead of waiting for the next automatic step. |
A test order goes like this:
productwith a product link, thenadd_to_cartwith a variant'sskuId.sandbox_add_funds, thensandbox_place_order. The order is paid from the wallet.- The simulator moves the order on by itself, about once a minute:
- Procured: the warehouse buys the goods.
- At the warehouse: the goods are received, weighed (500 g per unit) and photographed.
warehouselists them with their QC photo. - Shipped: a shipment order is placed and packed, then handed over with a
NBTEST-…tracking number, and a "shipped" notification is sent.
- Read each step with
list_orders,orderandwarehouse. They are the same tools and the same answers as on the live site.
Call sandbox_advance_order to skip the wait. A step that has nothing left to do returns done.
Limits
- The sandbox charges nothing and buys nothing. Card checkout runs in Stripe test mode, and no real purchase is ever made from a seller.
- The simulated warehouse ships every item of an order to one fixed test address, and it records the shipping bill as paid without taking it from your wallet.
- There are no webhooks yet, on the sandbox or the live site. Poll
orderorlist_ordersto follow an order. - The order tools are MCP only. The REST API has no order routes yet.
- Rate limits are the same as on the live site. See Rate limits.
- Sandbox data is test data. It may be reset, and it is never moved to the live site.