Skip to content

Simulate an order

Check what the checkout would charge a customer, or a new one, for each price of a product, without buying anything.

Updated

GET /products/{product}/checkout/simulate 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:

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"
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:

{
  "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.

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 answers the same from Simulate order on the Orders page, and the merchant MCP server as the simulate_checkout tool.

Type to search…

↑↓ navigate↵ selectEsc close