> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox Gotchas & FAQ

<Tip>
  **Purpose:** A single reference for the sandbox-specific behaviors every new partner hits in their first week of integration. If something "isn't working" in sandbox, start here before opening a ticket.
</Tip>

This guide supplements the [POS/Kiosk](/overview/guides/pos-kiosk), [Consumer UX](/overview/guides/consumer-ux), and [Basket Lifecycle](/overview/guides/basket-lifecycle) guides with behaviors that are specific to the sandbox environment.

**Who this is for:**

* Partners actively integrating against `thanxsandbox.com` hosts
* Anyone troubleshooting unexpected sandbox responses before escalating to Dev Support

## 1. Sandbox purchase processing has a noticeable delay

Sandbox purchase processing runs on a lower-priority worker pool, so a successful `billed` basket or a sandbox `POST /purchases` request will not show up immediately.

| Environment | Typical latency                        |
| ----------- | -------------------------------------- |
| Production  | Near real-time                         |
| Sandbox     | 15 minutes, commonly up to 30+ minutes |

<Tip>
  Before reporting "points not accruing" or "purchase missing," wait \~30 minutes and re-check `GET /account` or `GET /purchases`. The majority of these sandbox tickets resolve themselves in this window.
</Tip>

## 2. Array query parameters require bracket notation

When a Thanx endpoint accepts an array filter (e.g., filtering rewards by state), the query parameter name must include `[]` — dropping the brackets causes the server to interpret the value as a single string instead of an array element.

**Wrong:**

```
GET /rewards?states=available,active
```

**Right:**

```
GET /rewards?states[]=available&states[]=active
```

<Note>
  The [Get Rewards](/consumer/rewards/get-rewards) endpoint documents this directly. The same convention applies to any array-valued filter across the Consumer, Partner, and Loyalty APIs.
</Note>

## 3. Granting rewards in sandbox — `POST /rewards/grant`

You don't need to trigger campaigns or wait for earn conditions to test rewards in sandbox. Use [`POST /rewards/grant`](/consumer/rewards/grant-reward) to issue any configured campaign's reward directly to a user.

**Availability:** Sandbox only. The endpoint is disabled in production.

**Required parameters:**

* `campaign_id` — the **hashid** form of the program's `external_uid`, not the numeric program ID
* `user_id` — the user to grant the reward to

**Finding the `campaign_id`:** Ask Dev Support for the hashids of the campaigns set up on your sandbox merchant, or look them up in the merchant's admin. Using the numeric program ID will not resolve — the endpoint only accepts the hashid-encoded external UID.

```bash theme={null}
curl https://api.thanxsandbox.com/rewards/grant \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Accept-Version: v4.0" \
  -H "Authorization: Bearer ${token}" \
  -H "X-ClientId: ${client_id}" \
  -d '{
    "campaign_id": "YOUR_CAMPAIGN_HASHID",
    "user_id":     "YOUR_USER_ID"
  }'
```

## 4. Simulating a purchase in sandbox — `POST /purchases`

To test points accrual, tier progression, or campaign triggers that depend on a completed purchase, use [`POST /purchases`](/consumer/purchases/create-purchase). This is the only way to create a sandbox purchase without going through a live POS or payment processor.

**Availability:** Sandbox only.

**Behavior:**

* Processed asynchronously — the endpoint returns no JSON body
* The purchase takes the usual 15–30+ minutes to land (see §1)
* Poll `GET /purchases` to confirm ingestion — see guidance below

```bash theme={null}
curl https://api.thanxsandbox.com/purchases \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Accept-Version: v4.0" \
  -H "Authorization: Bearer ${token}" \
  -H "X-ClientId: ${client_id}" \
  -d '{
    "purchase": {
      "merchant_id":  "YOUR_MERCHANT_ID",
      "location_id":  "YOUR_LOCATION_ID",
      "user_id":      "YOUR_USER_ID",
      "amount":       13.45,
      "purchased_at": "2020-09-15T00:52:10.655+00:00"
    }
  }'
```

**Polling guidance for sandbox verification:**

* Wait at least 60 seconds before the first poll
* Use exponential backoff — start at 60s, double up to a 5-minute cap
* Stop polling as soon as the purchase appears, or after \~45 minutes total
* This is a sandbox-only pattern for verifying test setup. Production integrations should not poll — sandbox latency is a sandbox artifact and does not reflect production behavior.

<Note>
  Loyalty API integrations use [`POST /baskets`](/loyalty/create-update-basket) with state `billed` instead of `POST /purchases`. `POST /purchases` is specifically for Consumer API sandbox testing.
</Note>

## 5. Test cards trigger fraud detection on protected rewards

Commonly-used shared test card numbers (e.g., the standard Visa/MC test PANs) are flagged as high-risk by Thanx's fraud engine.

**When this causes problems:**

* Fraud-protected reward types include intro, birthday, winback, and signup rewards
* Using a shared test card on a user registered to one of these rewards will silently fail to earn/activate
* You'll see no error — just no reward

**How to work around:**

* For fraud-protected reward flows, register **a unique card number per test user** (only the first 6 and last 4 digits need to be valid; the middle digits can be random but consistent)
* For non-protected reward types (points products, free-item rewards), shared test cards are fine

## Need sandbox credentials?

Sandbox credentials (client ID, client secret, merchant key, partner token, and test user) are provided by Thanx Developer Support during onboarding. If you haven't received them or need a reset, email [developer.support@thanx.com](mailto:developer.support@thanx.com).

## Related Pages

* [Integrating with Thanx](/overview/integrating)
* [Basket Lifecycle & Troubleshooting](/overview/guides/basket-lifecycle)
* [POS/Kiosk Integration Guide](/overview/guides/pos-kiosk)
* [Consumer UX Integration Guide](/overview/guides/consumer-ux)
* [Grant Reward (sandbox only)](/consumer/rewards/grant-reward)
* [Create Purchase (sandbox only)](/consumer/purchases/create-purchase)