# Test mode

> Build against a Shoprocket store before it goes live: the test gateway, test orders and test webhook endpoints.

Build and rehearse a whole integration, checkout and webhooks included, before a store takes real orders.

## A store starts in test mode

Every new store starts in test mode, the dashboard's set-up stage, and stays there until its owner presses **Go live**. The seller API reports it as `storeMode` on `GET /stores/{storeId}`: `test` until then, `live` after (or `paused` / `suspended` while the store is not taking orders).

**A store in test mode is hidden until it goes live.** `GET /public/{pk}` answers `"comingSoon": true`: its hosted shop shows visitors a "coming soon" page, the widget draws nothing, `GET /payment-methods` is empty with `checkoutDisabledReason` "this shop is not open yet", and `POST /cart/checkout` answers 409 `store_not_open`. Catalogue reads (products, categories, pages) work as usual, so you can build against them.

The store opens inside its owner's **preview session**: a page whose address carries `?sr_preview=<token>`, as the dashboard's **View shop** and **Place a test order** open it. The widget sends the token back as `X-Shoprocket-Preview`; a headless client sends that header itself. Tokens come from `POST /stores/{storeId}/preview-session` and last 4 hours, and `GET /public/{pk}/preview-session` says whether one is still valid. Inside a preview the whole shop shows, and checkout offers only the test gateway, so every order is a test order.

Three kinds of test-mode store are public and offer the test gateway to anyone, with no token: the demo store these docs call, an unclaimed store an AI builder created (see the quickstart), and a store that still runs on Shoprocket v2. `comingSoon` is false on all three.

## The test gateway

Inside a preview session, and on the public test-mode stores above while they have no real way to pay, `GET /payment-methods` offers Shoprocket's own test gateway, marked `testMode: true`. It moves no money: you decide the outcome. After a store goes live its owner's preview offers the test gateway beside the real methods, so test orders work any day.

1. Check out as usual (see [a headless checkout](https://shoprocket.io/docs/basics.md#checkout)) with the test gateway as the `paymentMethod`.
2. `POST /orders/{orderId}/pay` answers a `test_gateway` handoff carrying a `paymentId`. There is no page to send the shopper to.
3. `POST /test-gateway/{paymentId}` with `"outcome": "approve"` or `"decline"`. It answers the order's new `paymentStatus`, and from there the order behaves exactly like a paid (or declined) real one.

A cart started while the test gateway was on offer can only be paid with it, and a cart started before cannot use it: if the store connects a real gateway mid-checkout, start a new cart. On a store that is not live yet, a cart started outside the preview is refused inside it too (`store_not_open`): start a new one in the preview.

It is in the roster

```
curl https://api-v3.shoprocket.io/v3/public/pk_bCz5dnUr-Mdw6bj0BcoE3CALrGA1vhYq/payment-methods
```

Check out with it

```
"paymentMethod": { "kind": "gateway", "gateway": "test" }
```

pay answers

```
"handoff": { "kind": "test_gateway", "paymentId": "pay_..." }
```

Approve it

```
curl -X POST https://api-v3.shoprocket.io/v3/public/pk_bCz5dnUr-Mdw6bj0BcoE3CALrGA1vhYq/test-gateway/pay_... \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "approve" }'
```

## Test orders

An order paid through the test gateway is a test order: `isTest` is true on it everywhere the API returns it. It runs the same path a real order does, stock, confirmation emails, download links and gift cards included, so you can check every step. It is left out of reports, invoices and marketing emails.

| To | Call |
| --- | --- |
| List only real orders | GET /stores/{storeId}/orders?mode=live |
| List only test orders | GET /stores/{storeId}/orders?mode=test |
| Clear test orders out | POST /stores/{storeId}/test-orders/delete |

The orders list returns both kinds unless you pass `mode`, so filter on it in any sync that should only see real sales. Deleting test orders also removes what they produced (gift cards, download links, test customers). Licence keys they took from a product's pool go back in it; keys that were generated for them or supplied by your own key server are deleted. It never touches a real order.

## Test webhooks

A webhook endpoint is either live or test, set with the **Test mode endpoint** switch when you add it. Events about test orders go only to test endpoints, and a live endpoint never receives them. Add a test endpoint pointing at your development server and drive test orders through it. The [webhooks guide](https://shoprocket.io/docs/webhooks.md#test-mode) has the details, including the **Send test** button.

## Going live

The store owner goes live from the dashboard's set-up checklist once its other steps are done. It is one way: there is no going back to test mode. Nothing about the API or your keys changes: `comingSoon` turns false, the shop and its embeds open to everyone, and the store's real payment methods take real orders.

A live store can still make test orders: the seller places them from the dashboard (Orders or Payments, "Place a test order"), they are marked `isTest` in the same way, and they reach test webhook endpoints only.

---

- HTML version: https://shoprocket.io/docs/test-mode
- Language: English (en)
