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

# Launch pricing

> Flash sales, fair pricing by country and early-bird price steps with your API key, and the price a buyer pays right now.

Base URL `https://api.pocketsflow.com`. Authenticate with your API key
(`Authorization: Bearer pk_live_…` or `pk_test_…`). Turning a feature **on**
needs the Growth plan (`403 FEATURE_LOCKED` below it); turning it off,
deleting and reading never do. When a store moves below Growth, its products
go back to their list prices.

## How a price is worked out

One rule, on our server, for the product page, the checkout, the receipt, the
order and the `order.completed` webhook:

1. **Price in effect** — the lowest of the product's price (or the
   variant's), the early-bird step's price while a step is open, and the
   buyer's own personal-deadline offer. On a tie the early-bird step wins.
2. **At most one discount, the best for the buyer** — among the live flash
   sales, fair pricing for the buyer's country and the code they entered (a
   discount code or a unique coupon), taken off the price in effect.
   Discounts never stack with each other. Ties: the code, then the flash
   sale, then fair pricing.
3. **Limits** — flash sales and fair pricing never take a price under 1.00 or
   make an order free; a code can (a 100% code is a free order, as before).

Pay-what-you-want products and subscriptions are not repriced.

## Flash sales

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/flash-sales` | List sales (`?status=live\|scheduled\|ended`) with orders and revenue |
| `POST` | `/flash-sales` | Create a sale |
| `GET` | `/flash-sales/{id}` | One sale |
| `PATCH` | `/flash-sales/{id}` | Change a sale (move `endsAt` to now to end it early) |
| `DELETE` | `/flash-sales/{id}` | Delete a sale (orders keep their record) |
| `POST` | `/flash-sales/{id}/announcement` | Draft the announcement email (nothing is sent) |

```bash theme={"system"}
curl -X POST https://api.pocketsflow.com/flash-sales \
  -H "Authorization: Bearer $POCKETSFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday",
    "startsAt": "2026-11-27T08:00:00.000Z",
    "endsAt": "2026-11-30T23:59:00.000Z",
    "valueType": "percentage",
    "value": 30
  }'
```

| Field | Type | Notes |
| - | - | - |
| `name` | string | Up to 80 characters. Shown to buyers with the countdown. |
| `startsAt`, `endsAt` | ISO date | Up to 90 days apart; `endsAt` in the future. |
| `valueType` | `percentage` \| `fixed` | |
| `value` | number | Whole percent 1–90, or an amount in your currency. |
| `productIds` | string\[] | Your products on sale. Empty or left out: the whole store. |
| `allProducts` | boolean | `true` puts the whole store on sale. |

The response is the sale with `status` (`scheduled`, `live`, `ended`,
computed from the clock), `stats: { sales, revenue }` and
`announcementPostId`. The announcement endpoint answers `{ postId, created }`:
review the draft, then send or schedule it with the
[newsletter endpoints](/api-reference/endpoints#posts).

## Fair pricing

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/fair-pricing` | Settings and the tier table (every country per tier) |
| `PUT` | `/fair-pricing` | Change settings (fields left out keep their value) |
| `GET` | `/fair-pricing/analytics?days=30` | Orders, revenue, discount given and billing mismatches by country |
| `PATCH` | `/products/{id}/fair-pricing` | A product's mode: `store`, `off` or `custom` |

```json theme={"system"}
{
  "enabled": true,
  "tiers": { "t1": 20, "t2": 35, "t3": 50, "t4": 60 },
  "countryOverrides": { "BR": 40, "PT": 0 }
}
```

Tiers hold the countries whose prices are 58–72% (`t1`), 45–58% (`t2`),
33–45% (`t3`) and under 33% (`t4`) of US prices. A country exception wins over
its tier; `0` means full price. Percents are whole numbers from 0 to 80.

The buyer's country is the country of their IP, worked out on our server. The
discount applies only when the browser time zone (`tz`) belongs to that
country and any billing country sent at checkout is the same. After payment,
the billing country collected is compared again: a mismatch is recorded on
the order as `pricing.fairPricing.verified: false`.

## Early-bird price steps

| Method | Endpoint | Description |
| - | - | - |
| `PUT` | `/products/{id}/price-steps` | Set a product's steps |
| `GET` | `/products/{id}/launch-pricing` | Its steps (seats sold, the step in effect) and fair pricing mode |
| `GET` | `/pricing/early-bird` | Every product with steps |

```json theme={"system"}
{
  "enabled": true,
  "steps": [
    { "price": 49, "maxSales": 50 },
    { "price": 59, "endsAt": "2026-11-01T00:00:00.000Z" }
  ]
}
```

Up to 5 steps, each below the product's price, with `maxSales`, `endsAt` or
both; prices go up from step to step. Send back the step `id`s you received to
keep their counts when you edit. Steps need a fixed price and no variants.

Seats are taken atomically when a checkout starts and held for 20 minutes, so
concurrent buyers never oversell a step; an unpaid seat goes back on sale. A
buyer who pays after their hold expired was shown and charged the step price,
so the sale is honoured and counted (a step can end one over its limit only
through payments that were already in flight).

## The buyer's price (public)

`GET /pricing/quote/{productId}?tz=Asia/Kolkata` — no API key, never cached.
Optional `variantId`, `discountId`, `billingCountry`, `orderBumpIds`.

```json theme={"system"}
{
  "productId": "665f1c2a9b3e4a0012ab34cd",
  "currency": "USD",
  "payWant": false,
  "listPrice": 79,
  "basePrice": 49,
  "price": 44.1,
  "applied": { "source": "flash_sale", "label": "Launch week", "valueType": "percentage", "value": 10, "amountOff": 4.9 },
  "codeIgnored": false,
  "earlyBird": { "index": 0, "count": 2, "price": 49, "nextPrice": 59, "left": 23, "maxSales": 50, "endsAt": null },
  "flashSale": { "id": "6711d4e59e3f1a0012cd8b01", "name": "Launch week", "endsAt": "2026-10-20T09:00:00.000Z", "valueType": "percentage", "value": 10, "applied": true },
  "fairPricing": null
}
```

Amounts are in your currency. The checkout charges this same price.

Add `orderBumpIds` (comma-separated) to price the whole cart the way the
checkout does: each order bump at its offer price, then the
[Buy more, save more](/selling/buy-more-save-more) tier off the subtotal (not
on top of a discount code unless you allow it). The answer gains `cart`:

```json theme={"system"}
{
  "cart": {
    "items": [
      { "productId": "665f1c2a9b3e4a0012ab34cd", "price": 39.69 },
      { "productId": "665f1c2a9b3e4a0012ab34ce", "orderBumpId": "6711d4e59e3f1a0012cd8c02", "price": 26.1 }
    ],
    "subtotal": 73.1,
    "tieredDiscount": { "percentOff": 10, "itemCount": 2, "amount": 7.31, "settlementAmount": 7.31 },
    "total": 65.79
  }
}
```

`total` is what the checkout charges before tax; each item's `price` is its
share after the tier, as recorded on its order.

## Orders and webhooks

Every order priced by these rules carries `pricing` (also in the
`order.completed` webhook):

```json theme={"system"}
{
  "pricing": {
    "listPrice": 79,
    "basePrice": 49,
    "price": 29.4,
    "amountOff": 49.6,
    "currency": "USD",
    "source": "fair_pricing",
    "earlyBird": { "stepId": "step_3f9a1c2b7d4e", "index": 0, "price": 49, "nextPrice": 79 },
    "fairPricing": { "country": "IN", "tier": "t4", "percentOff": 40, "billingCountry": "IN", "verified": true },
    "codeIgnored": false
  }
}
```

## Errors

| Status | When |
| - | - |
| `400` | Invalid input, e.g. `Step 1: the price must be lower than the product's price`. |
| `403` | `code: FEATURE_LOCKED` — turning it on needs the Growth plan. |
| `404` | No sale or product with this id in your account. |

## MCP

`list_flash_sales`, `create_flash_sale`, `get_flash_sale`,
`update_flash_sale`, `delete_flash_sale`, `create_flash_sale_announcement`,
`get_fair_pricing`, `update_fair_pricing`, `get_fair_pricing_analytics`,
`list_price_steps`, `get_product_launch_pricing`, `set_product_price_steps`,
`set_product_fair_pricing`, `get_price_quote`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.