Kindly EditDocumentationTry the editor

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#

  1. Select the field in the builder.
  2. Below its choices list, tick Limit stock. A stock column appears beside each choice.
  3. 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#

  1. 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.
  2. 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.
  3. 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.

  • Fields for choices lists and their other settings
  • Payments for product fields and quantities
  • Entries for spam, approval and the trash
About this page

Documents Kindly Edit 0.9.16. Source: includes/forms/inventory.php, assets/forms/builder.js, includes/forms/fields.php. Theme choices and account permissions can change which controls appear.

Type a word or phrase to search the full documentation.