# 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).

Every API works the same in test mode. What changes is how a checkout can be paid, and what that order is marked as. (The examples on these docs call a demo store that can never take real money, so you can run them as they are.)

Test mode is not a sandbox for real gateways

A store in test mode that has connected a real gateway (Stripe, PayPal...) or turned on an offline method takes real payments through it, and those orders are real. Shoppers only make test orders through the test gateway; the one exception is a seller paying in their own dashboard preview.

## The test gateway

While a store in test mode has 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.

1. Check out as usual (see [a headless checkout](https://v3.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.

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://v3.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; the test gateway simply stops being offered to shoppers.

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://v3.shoprocket.io/docs/test-mode
- Language: English (en)