Launch pricing

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:

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

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.

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`

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

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

{
  "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 tier off the subtotal (not on top of a discount code unless you allow it). The answer gains cart:

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

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

Overview

API reference

Node.js SDK

Webhooks

How a price is worked out

Flash sales

Fair pricing

Early-bird price steps

The buyer’s price (public)

Orders and webhooks

Errors

MCP

​How a price is worked out

​Flash sales

​Fair pricing

​Early-bird price steps

​The buyer’s price (public)

​Orders and webhooks

​Errors

​MCP

How a price is worked out

Flash sales

Fair pricing

Early-bird price steps

The buyer’s price (public)

Orders and webhooks

Errors

MCP