Skip to main content

Purchasing, Promotions, Bundles, and Bottle Deposits

Use these Catalog & Inventory pages for supplier replenishment and sellable catalog programs. Purchase Orders uses organization suppliers but receives into a destination store. Promotions is organization-owned and can apply to all stores or the selected store. Bundles and Bottle Deposits operate on products from the selected store.

Prepare Categories and Suppliers​

Set up the organization-wide prerequisites before creating products and purchase orders:

  1. Open the organization section > Categories. Build the category taxonomy shared by all stores, then assign products to the appropriate categories on Products.
  2. Open the organization section > Suppliers. Add the supplier's profile, contacts, payment terms, and product purchasing links.
  3. On Products, set Default supplier for reorders for every item that should be included in supplier-specific low-stock reorder drafts.
  4. On Inventory, set Par level, Reorder point, and Reorder quantity so low-stock alerts have usable reorder values.

Category read access and supplier read access open their respective organization pages. Changing either directory requires the matching organization write access together with organization administrator access.

Purchase Orders​

Open Catalog & Inventory > Purchase Orders. Purchase-order read access lets you review orders and their lines. Purchase-order write access adds New Purchase Order, Review Order, and Receive.

Review low-stock supplier purchase orders​

When a product reaches its reorder threshold and has an active default supplier, the replenishment workflow adds it to that supplier's low-stock purchase order for the destination store. Each store and supplier has at most one created-but-not-ordered low-stock order at a time, so the workflow updates that order instead of starting another one. The order is labeled Created and Auto-Reorder, and records the supplier, destination store, item quantity, unit cost, and notes.

An auto-reorder order that has not been ordered escalates as it waits, counted in 24-hour periods from when it was created: on its first day it looks like any other created order, on its second day it shows an Awaiting review · day 2 badge, and from its third day on the badge turns red. Opening the order shows a notice, in the same color, saying since when it has waited. While any auto-reorder order is waiting, Today at a glance on the dashboard shows a highlighted auto-reorder drafts awaiting review item that links to Purchase Orders; it turns red once the oldest one reaches its third day.

The ordered quantity counts stock already on the way: on-hand quantity plus units still expected on created, ordered, or partially received purchase orders. If that total is above the reorder point, no new line is added. Otherwise the line brings the total up to Par level (or orders the Reorder quantity when no par level is set) and always above the reorder point. The unit cost comes from the supplier's cost for the product, then the product's Cost.

  1. Open Purchase Orders. The page initially shows Created (not ordered) purchase orders.
  2. Use the lifecycle tabs—Created (not ordered), Ordered, Partially received, and Received—to select a status.
  3. Use Destination to show one store or All stores.
  4. Select a created purchase order and verify the supplier, destination, line descriptions, Ordered quantities, unit costs, and total.
  5. With purchase-order write access, select Review Order when the supplier order has actually been placed. Every line needs a unit cost greater than zero first; a line without a known cost shows $0 and blocks Review Order until you enter the real cost.

Create a supplier purchase order manually​

  1. Select New Purchase Order.
  2. Choose the Destination store and Supplier.
  3. Confirm Currency and add optional Notes.
  4. Under Lines, choose an inventory item, enter its Description, Ordered quantity, Unit cost, and currency.
  5. Select Add Line for more items.
  6. Select Create Purchase Order.
  7. Open the created purchase order and select Review Order only after placing the order with the supplier.

Receive a shipment​

  1. Filter to Ordered or Partially received and open the purchase order.
  2. Compare the physical shipment with each line's Ordered and Received quantities.
  3. Enter Receive quantity for each line. A quantity must be from zero through the remaining quantity.
  4. Select Receive.
  5. If only part of the shipment arrived, the order moves to Partially received. Repeat the receiving procedure for later shipments until it reaches Received.

Receiving through Purchase Orders updates the destination-store inventory as part of the purchasing workflow. Do not also use Receive Inventory for the same shipment. A receipt updates the product's average Cost only from known costs: units received at $0 and stock previously held at a $0 cost leave the average unchanged.

Receipt delivery is retry-safe: each explicit shipment receipt has its own required X-Idempotency-Key (1–200 nonblank characters) on POST /api/v1/orgs/{orgId}/purchasing/purchase-orders/{id}/receive. Keep that same key and unchanged line request when a response is lost, including after a page reload; use a new key only for a new receipt. The server binds the attempt to the organization, destination store, purchase order, merchant user, verified authenticated operator subject, and complete request. Another support operator acting for the same merchant cannot reuse the attempt; different receipt details or a different verified operator return a conflict before stock changes or replay. Successful re-delivery by the same operator returns the original receipt result, even if another shipment has since changed the order. The stock ledger records the verified target merchant user, not an inferred system actor.

The server supplies canReceive on purchase orders and outstandingQuantity on their lines. It checks lifecycle, line ownership, whole quantities, promotional reasons, and quantity caps under purchase-order/line locks. Paid and promotional stock, inventory ledger entries, average cost, order status, and the durable replay result commit atomically; failed validation does not leave a partial receipt.

Promotions​

Open Catalog & Inventory > Promotions. Organization promotion read access shows the campaign list. Adding, editing, enabling, disabling, or deleting a promotion requires both organization promotion write access and organization administrator access.

To create a campaign:

  1. Select Add Promotion and enter Name.
  2. Choose a Mechanic:
    • Percent off
    • Amount off
    • Buy X Get Y
    • Buy N for fixed price
  3. Choose Store scope: All stores or Current store only. Buy N for fixed price is limited to the current store.
  4. Enter the fields for the selected mechanic. For Buy X Get Y, use 100 as Reward discount percent when the reward is free.
  5. Enter Priority and, if needed, Uses per transaction (optional). Higher priority wins when promotions overlap. At the same priority, checkout applies the greatest value and then a stable tie-breaker. Non-overlapping promotions can apply together.
  6. Choose Product scope. Use All products in scope or Selected products. Fixed-price quantity promotions require selected products.
  7. For a separate Buy X Get Y reward, choose Separate reward products (optional). Leaving every reward unchecked makes it a same-item reward within each selected product.
  8. Optionally add Description, Starts at, and Ends at. Scheduled times use the selected store's time zone when a store is selected; otherwise they use UTC.
  9. Review Checkout preview, then select Create.

The list reports Mechanic, Terms, Scope, Priority, status, and schedule. Status can be Inactive, Expired, Scheduled, or Active. Use Disable or Enable to change availability without changing the campaign definition.

Promotion amounts, quantities, schedule ordering and product/store eligibility are validated by the server when saving. The editor retains name/code syntax feedback and converts local schedule input to the store time zone, including daylight-saving gap feedback; its checkout preview does not authorize a discount.

Bundles​

Open Catalog & Inventory > Bundles to create a sellable kit or multi-pack whose sale consumes component inventory. The route uses product read access for the selected store.

  1. Select Add Bundle.
  2. Under Bundle product, either define a new sellable product or choose the option to use an existing product.
  3. For a new sellable product, enter Name, Barcode, Price, and Category.
  4. Add optional Description.
  5. Under Inventory consumed, select each component product and the quantity deducted when the bundle sells. Select Add Component for more products.
  6. Select Create.

Use Edit to change the bundle name, description, price, or components. Use Archive when it should no longer sell as a kit. Archiving also archives a sellable product created by the bundle workflow, while a previously existing sellable product remains active.

Bottle Deposits​

Open Catalog & Inventory > Bottle Deposits. The page heading is Container deposits, and the route uses product read access for the selected store.

Add a product deposit rule​

  1. Under Rules, select Add product deposit.
  2. Enter Name and Deposit Amount ($).
  3. Choose the Eligible product. A deposit applies only to an explicitly selected product.
  4. Select Create.

Use Edit to change the rule's name or amount. Use Archive to stop the rule while keeping its historical ledger and reports.

Review deposits​

  • Choose Start Date and End Date, then select Generate Report. Review Collected, Returned / voided, and Net amounts and units.
  • Review the ledger columns Date, Type, Product, Quantity, Amount, and Transaction. Use Previous and Next when the ledger spans multiple pages.

The POS records collected deposits from sales and offsets them with real returns or voids. Use the report and ledger rather than manually changing historical deposit entries.