---
title: "Simulate an order"
description: "Check what the checkout would charge a customer, or a new one, for each price of a product, without buying anything."
---

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

# Simulate an order

<a href="/merchant-api/reference/simulate-checkout/">`GET /products/{product}/checkout/simulate`</a> prices a product the way the checkout would for one buyer, and answers every price at once. Nothing is created: no checkout, no coupon use, no payment, and nothing reaches the payment processor. Use it to check a discount before you announce it, to answer a customer who asks what an upgrade costs, or to show a price in your own tools.

What a customer would pay for a course with the code `SPRING10`:

```bash
curl 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/checkout/simulate?customer=7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918&coupon=SPRING10' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
```

```js
const answer = await sherpo('GET', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/checkout/simulate', {
  query: [
    ['customer', '7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918'],
    ['coupon', 'SPRING10'],
  ],
});
```

Answers `200`, abridged:

```json
{
  "at": "2026-11-16T10:30:00.000Z",
  "customer": {
    "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918"
  },
  "product": {
    "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42"
  },
  "coupon": "SPRING10",
  "quantity": 1,
  "owned": null,
  "prices": [
    {
      "price": {
        "id": "0a9b8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
        "tier": {
          "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e",
          "rank": 1,
          "name": "Course"
        },
        "kind": "one_time",
        "period": null,
        "currency": "eur",
        "exponent": 2,
        "amount": 4900
      },
      "verdict": {
        "status": "charged",
        "mode": "purchase",
        "unit": 4410,
        "quantity": 1,
        "total": 4410
      },
      "mode": "purchase",
      "list": 4900,
      "discounted": 4410,
      "discount": {
        "applied": "coupon",
        "automatic": null,
        "coupon": {
          "id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
          "name": "Spring sale",
          "code": "SPRING10",
          "discounted": 4410
        }
      },
      "coupon": {
        "status": "applied"
      },
      "upgrade": null,
      "minimum": {
        "amount": 50,
        "approximate": false,
        "waived": null
      },
      "recurring": null
    }
  ]
}
```

## What you ask

- `customer`: the customer to price for, priced from what they already hold and paid. Leave it out for a new customer.
- `coupon`: a discount's code, as a customer would type it at the checkout, or its id. Leave it out to see the automatic discounts alone.
- `quantity`: how many of a one-time price, 1 by default. A plan, an upgrade or a renewal is always one.
- `at`: a later moment to price at, as an ISO 8601 timestamp, now by default, to see a discount that starts or ends then. A date alone is that day's start in UTC, so today's date is already past. It can't be in the past, and what the customer holds is read as it stands now.

The read needs `price:read`. Naming a customer also needs `customer:read`, and naming a coupon `discount:read`; without either, the call answers `403` with the reason `scope`. Without `discount:read`, the automatic discount still shows what it takes off, but its `id`, `name` and `code` are `null`. Without `revenue:read`, an upgrade's `paid` (what the customer paid, before refunds) is `null`, though its `credit` still reflects what they paid net of refunds. See [scopes](/merchant-api/scopes#scopes-that-change-what-you-see).

## What it answers

`prices` lists every live price of the product, plus an archived one the customer's own plan still renews on, in the order the checkout shows them. For each:

- `verdict` is what the checkout would do: `charged`, with its `mode` (a `purchase`, an `upgrade` or a `renewal`), the `unit` amount, the `quantity` and the `total`; or `refused`, with its `reason`.
- `list` is the amount before any discount or credit, and `discounted` the amount after the discount that applied.
- `discount` shows the automatic discount and the coupon that reach the price, and which one `applied`. A coupon that reaches the price replaces the automatic discount, even one that takes more off; they never stack.
- `coupon.status` says what the coupon did to this price: `applied`, or why not, such as `not_found`, `not_started`, `ended`, `used_up`, `not_for_price`, `not_for_customer` or `not_for_renewal`. It's `null` when you named no coupon.
- `upgrade` is the credit for what the customer already holds of the product, when the price is an upgrade.
- `minimum` is the payment processor's smallest charge in the price's currency; a total under it is granted for free, as `waived` shows.
- `recurring` is a plan's `first` charge and what it then renews at, or `null` for a one-time price.

Amounts are in the currency's minor units, with its `exponent`, as everywhere in the API.

## Why a price is refused

A refused price names its `reason`. The common ones:

- `not_for_sale`: the product isn't on sale at that moment.
- `archived`, `discontinued` or `ended`: the price, or the product, can't be bought anymore.
- `already_owned`, `lower_tier` or `same_tier_no_gain`: the customer already holds this, or more.
- `coupon`: the checkout would refuse the coupon on this price; `coupon.status` says why.
- `one_at_a_time`: the price is bought one at a time, and `quantity` is more than 1.
- `approval_required`: the product takes requests, which you approve, so only a free one-time price is offered, and no upgrade.
- `request_open`: the customer's request for the product is still waiting for your decision.
- `sold_out`: the event doesn't have `quantity` seats left.
- `paused`: new purchases and unlocks are paused for your business, as when it has been past its plan's limits, or its payment has been failing, for 7 days; renewing a plan the customer is already billed on still goes through.

The [merchant app](/merchant-app/orders-and-subscriptions#simulate-an-order) answers the same from **Simulate order** on the Orders page, and the merchant MCP server as the [`simulate_checkout`](/merchant-mcp/tools/simulate_checkout) tool.

Source: https://docs.sherpo.io/merchant-api/guides/simulate-an-order/index.mdx
