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

# Stock

> How Fanfare prevents overselling, splits inventory across sequences, and handles mid-drop stock changes and over-allocations.

Stock controls how many units of each product and size a drop can sell. When Fanfare manages your inventory, every unit is tracked from initial supply through allocation and checkout—so your drops can never sell more than you actually have.

## Choosing who manages stock

Every product has a **Stock management** mode set when you create it:

| Mode | Where the count lives | Eligible checkouts | What caps a drop |
| - | - | - | - |
| **Fanfare-managed** | In Fanfare (every change is logged in **Stock history**) | Fanfare checkout only | Experience allocations and each sequence's share |
| **Not managed** | Nowhere (per-sequence caps only) | Any checkout your organization uses | Each sequence's per-size limit, if set |
| **Shopify-managed** | In Shopify | Shopify checkout only | Each sequence's per-size limit, plus Shopify's live stock at checkout |

Keep three rules in mind when setting up products:

* **The choice is permanent:** Once a product is created, you can't switch its **Stock management** mode. See [Add products](https://docs.fanfare.io/guide/create/products.md).
* **How checkout shapes your options:** **Fanfare-managed** requires Fanfare checkout. Organizations using an external checkout create **Not managed** products in the admin (where the product-level quantity and **When sold out** settings don't cap sales), while products synced from Shopify are **Shopify-managed** (you can't select **Shopify-managed** manually in the admin). See [Checkout options](https://docs.fanfare.io/concepts/checkout-options.md) and [Manage stock](https://docs.fanfare.io/guide/create/stock.md).
* **Don't mix Fanfare-managed and Shopify-managed products:** One experience can't combine both, though **Not managed** products can appear alongside either.

Unless noted otherwise, the rest of this page covers **Fanfare-managed** products.

## How units move through a drop

Every Fanfare-managed unit progresses through five stages:

1. **Supply** — Opening stock entered at product creation, plus every receipt, adjustment, write-off, and return recorded since.
2. **Allocated** — Units reserved from Supply for a specific experience, size by size.
3. **Assigned to a sequence** — Each sequence gets its own slice of the experience's allocation. Units reserved for the experience but not yet given to a sequence stay **Unassigned**.
4. **In checkout** — Held exclusively for a customer during their payment window. See [Admission and the payment window](https://docs.fanfare.io/concepts/admission-and-payment.md).
5. **Sold** — Payment captured.

Sequences never share stock—a sequence sells only the units allocated to it, even if another sequence in the same experience still has units left. See [Sequences and routing](https://docs.fanfare.io/concepts/sequences.md).

On any product page, the **Stock by SKU** panel tracks these counts per size:

| Metric | What it means |
| - | - |
| **Supply** | Opening stock plus all recorded receipts, adjustments, write-offs, and restocked returns. |
| **Sold** | Units with captured payment (refunds don't reduce this number). |
| **On hand** | `Supply − Sold`. |
| **Allocated** | Total units reserved across all your experiences for this size. |
| **Available** | `Supply − Allocated`: units free to allocate to an experience. If negative, displays **Over-allocated by \[count]**. |
| **At risk** | Units currently in live checkouts that **On hand** no longer covers (normally `0`). |

## Per-sequence stock limits

Each sequence sets the maximum number of units it can sell for every size it offers. Configure these on the sequence's **Stock** card with **Edit allocations**—see [Allocate stock to a drop](https://docs.fanfare.io/guide/create/stock-allocation.md). For Fanfare-managed products, sequence limits draw directly from the experience's allocation so sequences can never collectively exceed what the experience holds.

> [!WARNING]
>
> Any size left without a number starts at `0` and displays **Opens sold out**. This always applies to Fanfare-managed products and to every sequence running a Dutch auction. Customers can't buy that size until you allocate units—check every size on every sequence before launch.

For products Fanfare doesn't manage, default starting limits depend on your checkout and distribution type (see [Allocate stock to a drop](https://docs.fanfare.io/guide/create/stock-allocation.md)). **No limit** is available only for products Fanfare doesn't manage, and never on a Dutch auction sequence—sizes set to **No limit** never sell out, though Fanfare still tracks **Sold** and **In checkout** counts.

## What changes once a drop opens

Live stock counting begins about 10 minutes before a sequence opens. Each size on its **Stock** card moves from **Not counting yet** → **Preparing** → **Ready** → **Selling**, exposing live **Sold**, **In checkout**, and **Remaining** counts.

Once counting begins:

* **Experience-level allocations lock** while the experience is live.
* **You can top up, not trim directly:** On a counting sequence, you can raise a size's limit using the experience's **Unassigned** units, but you can't lower it directly. To move units out of a live sequence—either to another sequence in the same experience or back to **Unassigned**—use **Move units**. See [Change things mid-drop](https://docs.fanfare.io/guide/drop/live-controls.md).
* **Draws stay in sync:** Moving units into or out of a sequence with an active draw raises or lowers its **Winner count** by the same number, and you can't set a draw's **Winner count** higher than the units available across its sizes. See [Draw](https://docs.fanfare.io/concepts/distributions/draw.md).

> [!NOTE]
>
> A single sequence supports up to **256** size combinations (product-and-size pairs, or 256 products for a **Mystery Box**). Above 256, Fanfare blocks new entries and auction bids while the sequence is counting and displays a warning on the **Stock** card—remove products or sizes to bring it back within the limit.

## Handling over-allocated stock

If a write-off or downward stock adjustment pushes **Supply** below **Allocated**, the affected size becomes over-allocated: **Available** displays **Over-allocated by \[count]** and a warning banner appears in **Stock by SKU**. Fanfare resolves the shortfall in a strict order:

1. **Live experiences return spare units first (newest first):** Fanfare reclaims **Unassigned** units from live experiences first, then uncommitted units from live sequences (whether counting or not). Note that an **Ended** experience still counts as live while entrants or active checkouts remain.
2. **Active checkouts stay protected:** Units currently **In checkout** stay with those shoppers. If **On hand** drops below those checkouts, the uncovered units are flagged as **At risk**.
3. **Upcoming distributions pause if any shortfall remains:** Even a 1-unit shortfall puts every distribution selling that size that hasn't started counting on hold (**Held: stock**)—even inside a live experience where an earlier distribution is already selling.

To clear a hold, either record a stock receipt or select **Resolve** to lower an upcoming experience's allocation. Once **Supply** covers **Allocated** again, held sequences resume automatically on Fanfare's next stock check. See [Manage stock](https://docs.fanfare.io/guide/create/stock.md).

![The Stock by SKU panel for a product, with the US 11 size over-allocated: its Available cell reads Over-allocated by 18, and a banner names Summer Drop as the held experience with a Resolve button.](https://mintcdn.com/fanfare/1LIsN6sNCEZdXydH/images/guide/concepts-stock-product-panel.webp?fit=max\&auto=format\&n=1LIsN6sNCEZdXydH\&q=85\&s=b1c99fa6e92fac4f0c0129402d8517e9)

A negative Available count means the size is over-allocated and upcoming distributions are held until resolved.

## Releasing unsold stock after a drop

Once every distribution in a sequence has ended or been deactivated and no customers remain in checkout, Fanfare automatically releases the sequence: its allocations shrink to match what sold, and leftover units return to the experience's **Unassigned** pool.

Once at least one sequence is released and no other sequence still holds active Fanfare-managed units, the experience's **Allocated** count shrinks to what sold—putting all unsold units straight back into **Available** for your next drop. Releasing doesn't log a stock adjustment, so **Supply** stays unchanged. Once a sequence shows **Released**, it's final: its stock can't be edited and no units can be moved into it.

## Refunds don't restock automatically

Issuing a refund never reduces **Sold** and doesn't automatically add the unit back to **Supply**. To restock a refunded Fanfare-managed unit, check the return-to-stock option when issuing the refund or select **Return to stock** on the order afterward. See [Orders and refunds](https://docs.fanfare.io/guide/learn/orders.md).

## Example: a mid-drop write-off

Suppose Northbound Supply Co. has **200** Fanfare-managed Phantom Stitch Anoraks in size M. **Phantom Stitch Anorak Drop** is allocated **150** units—**50** to **Inner Circle Early Access** (a queue from 10:00 to 11:00) and **100** to **Public Draw** (opening at 11:00), with `0` **Unassigned**.

By 10:30, the queue has sold **20** units and **5** shoppers are currently in checkout:

| View | Size M counts |
| - | - |
| Product **Stock by SKU** | **Supply** 200 · **Allocated** 150 · **Available** 50 · **Sold** 20 · **On hand** 180 · **At risk** 0 |
| **Inner Circle Early Access** Stock card | **Allocated** 50 · **Sold** 20 · **In checkout** 5 · **Remaining** 25 |
| **Public Draw** Stock card | **Allocated** 100 · **Not counting yet** |

At 10:30, your warehouse discovers 80 damaged jackets and you record an 80-unit write-off. **Supply** drops to **120**—30 units short of the 150 allocated:

1. **Live experience gives back first:** There are no **Unassigned** units, so **Inner Circle Early Access** returns its 25 remaining uncommitted units. Its allocation drops to `25` and **Remaining** drops to `0`.
2. **Active checkouts keep their holds:** The 5 units **In checkout** remain untouched. **On hand** is still `100` (`120 − 20`), which easily covers them, so **At risk** stays `0`.
3. **Upcoming draw is held:** Total **Allocated** is now `125` (`25 + 100`) against **Supply** of `120`, leaving **Available** at `−5`. Because **Public Draw** hasn't started counting yet, it switches to **Held: stock** and won't start selling at 11:00 until the 5-unit gap closes.

Because the experience is already live, **Resolve** can't lower its allocation. To let **Public Draw** open on time, record a receipt for at least 5 size M units before 11:00—or, if any of the 5 in-flight checkouts expire unpaid, each lapsed unit reduces the shortfall by 1.

## On Shopify

Products in the Fanfare app in Shopify sync directly from your Shopify catalog:

* **Shopify-managed (default):** When your organization uses external/Shopify checkout (the default when installing the app), synced products are **Shopify-managed**—Shopify owns the inventory count and you update stock in Shopify admin. See [Products from Shopify](https://docs.fanfare.io/guide/shopify/products.md).
* **Fanfare-managed (if using Fanfare checkout):** Products imported while connected to Fanfare checkout can use **Fanfare-managed** stock. Because Fanfare tracks that inventory independently from Shopify, set those units aside for your drop and take them off sale in Shopify yourself. See [Manage stock](https://docs.fanfare.io/guide/create/stock.md).

## Related

> [card] [Manage stock](https://docs.fanfare.io/guide/create/stock.md)
>
> Choose stock management modes, adjust stock, inspect stock history, and resolve over-allocations.

> [card] [Allocate stock to a drop](https://docs.fanfare.io/guide/create/stock-allocation.md)
>
> Reserve units for an experience and split allocations across sequences.

> [card] [Change things mid-drop](https://docs.fanfare.io/guide/drop/live-controls.md)
>
> Move units between sequences while a drop is live.

> [card] [Checkout options](https://docs.fanfare.io/concepts/checkout-options.md)
>
> See how inventory counts behave on each checkout processor.


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