Stock
Limit how many times a choice can be taken, share stock across forms, and show what is left.
Stock limits how many times a choice can be taken: seats on a bus, tickets for a session, T-shirts in each size. When a choice runs out, it is grayed out or hidden, and the form refuses more than what is left, even when two people send at the same moment. Several choices, and several forms, can sell from one shared stock.
Which fields can have stock#
- Drop-down, Choose one and Choose several, for each choice.
- Product or service (a payment field), for each choice, or for the product itself when it is shown as One price.
Choices that come from Fill choices from another source can't have stock; only choices typed in the field's own choices list can.
Limit stock on choices#
- Select the field in the builder.
- Below its choices list, tick Limit stock. A stock column appears beside each choice.
- Type how many there are for each choice. Empty means no limit. 0 means sold out.
Once entries arrive, each choice shows how many are left (or how many were taken, for a choice without a limit).
For a Product or service shown as One price, the field has In stock for its own number, or Shared stock item for a shared item's short name.
Turning Limit stock off keeps the numbers on the choices, so turning it back on brings them back.
Shared stock#
A shared item is one count that any choice in any form can draw from. Use it when the same thing is offered in several places, such as 40 bus seats split between a members' form and a guests' form.
- In a choice's stock cell, choose Use shared stock (the link button), then pick an item. The cell then shows the item's name and how many are left.
- New shared stock asks for a Name and How many there are, then links the choice to it.
- Use a number instead unlinks the choice and goes back to its own number.
Each shared item gets a short name (its slug) made from its name: lowercase letters, numbers and underscores, such as bus_seats. If the name is taken, a number is added (bus_seats_2). A shared item that has been removed no longer limits anything; the choice shows Removed.
What visitors see#
Each stock field has these settings once Limit stock is on:
| Setting | What it does |
|---|---|
| Sold-out choices | Grayed out (shown but can't be chosen, with the sold-out message beside it) or Hidden |
| When everything is sold out | Show the message (the field is shown disabled, not required, with the message) or Hide the field |
| Sold-out message | The words for a sold-out choice or field. Empty uses "Sold out". |
| Show how many are left | Shows a note beside each limited choice |
| Words for what is left | The note's words. {left} is the number. Empty uses "{left} left". |
A choice without a limit is always available, so a field is only sold out as a whole when every one of its choices has a limit and none is left.
Quantities#
By default each answer takes one. To take more, add a field that sets the quantity:
- A Number or Slider field: under its advanced settings, set Sets the quantity of to the stock field. Only payment items and fields with Limit stock are offered.
- A Quantity field (a payment field): set Quantity of to a Product or service field.
The answer is rounded down to a whole number. A quantity of 0 takes nothing. With Choose several, the quantity applies to each chosen option.
When stock is taken#
- When the form is sent and every other answer is valid, Kindly holds what the answers ask for and checks it against what is left. Holding first means two people sending at once can't both get the last one.
- If something is short, the form is not accepted. The field shows "Only 2 left of Front row." or "Front row: Sold out", using the choice's label and your sold-out message.
- Once the entry is stored, the hold becomes use, tied to that entry. A hold that never became an entry stops counting after 15 minutes.
Stock is counted per entry when it is taken, so editing an entry's answers afterwards doesn't change the counts.
What gives stock back#
| What happens | Stock |
|---|---|
| The entry is kept as spam | Never taken |
| The payment is refused before the entry is made | The hold is let go at once |
| The payment fails, expires or is canceled | Given back |
| The payment is fully refunded | Given back |
| The entry is marked spam, declined (when it needs approval), or moved to the trash | Given back |
| The entry is restored from spam, declined or the trash | Taken again |
| A payment that was marked failed or expired goes through after all | Taken again |
| The entry is deleted for good | Given back, and its record removed |
Smartcodes#
Shared items have smartcodes, for confirmation messages, emails, field help or the page around the form:
| Code | Shows |
|---|---|
{inventory.SLUG} |
How many are left |
{inventory.SLUG.total} |
How many there are in all |
{inventory.SLUG.used} |
How many are taken (including holds of the last 15 minutes) |
{inventory.SLUG.name} |
The item's name |
For example, "Only {inventory.bus_seats} seats left on the bus." See Smartcodes.
The Inventory screen#
Kindly Edit > Forms > Inventory lists every shared item: its name and smartcode, Total, Used, Left, and Used by (each form that drew from it, with how many).
- Add item asks for a Name and How many there are.
- Click an item's name, or Edit in its menu, to change its name or total in a side panel.
- Start the count again sets used back to 0, so all of it is available again (for a new season, for example). Entries are kept.
- Delete removes it. Forms that counted it down stop being limited by it.
Anyone who can build forms can add and edit items. Starting a count again and deleting need administrator rights, and both ask first. Changes are recorded in the Activity log.
Developers can do the same through REST routes under kindly-forms/v1:
| Route | Who | Does |
|---|---|---|
GET /inventory |
people who can build forms | Every shared item with its total, used and left, and which forms used it |
POST /inventory {name, total} |
people who can build forms | A new shared item |
PUT /inventory/{slug} {name?, total?} |
people who can build forms | Changes its name or total |
DELETE /inventory/{slug} |
administrators | Removes it. Choices linked to it no longer have a limit |
POST /inventory/{slug}/reset |
administrators | Starts its count again from 0 used. Restoring an old entry afterwards doesn't take stock again |
GET /forms/{id}/inventory |
people who can build the form | That form's use by field and choice, and the shared items |
Stock on a single choice is changed in the builder, like any other setting, and takes effect when the form is published.