← API Index

Building a cart with the API

The cart is where the customer decides. In a PCG shop it is more than a list of items: it is the order for one delivery date, shown with the deadlines that apply, the buttons that make sense right now, and a reason whenever something is not possible. This skill lists what the standard shop does, so that your own UI client behaves nice and the customer never gets a surprise from the server (at the time he/she finally submits). If you only want to push orders from another system, read feed orders into the system instead. If you want the ready-made cart, embed the cart component (see use-js-components).

Data you need

What Where to get it
The order and its positions api/order with items=1: Order, Position, the Item of every position, TourLimit rows and alternative units
The delivery date and its deadlines the ShopDate of the selected date, returned by api/settour, api/dates and every order call
The customer api/user: UserInfo with role, payment method, new-customer limit, vouchers, autosave opt-in, needs_tc (terms must be accepted again)
Shop rules Config from api/configuration: min_order_strict, allow_multiple_per_tour, has_voucher_or_coupon, quotes, show_item_season, donation_item_ids, agb_link
Pauses and special dates Pause and AuxDate lists, delivered with the date calls

Select the date first (see delivery date selection); item data, prices and limits depend on it. A cart always belongs to exactly one delivery date and delivery address.

The three deadlines

Every cart shows and enforces deadlines. Do not compute them yourself from tour settings, take them from the data:

  1. Change deadline – ShopDate.lastOrderChangeDate. Until then positions can be added, changed and removed. The standard shop shows it one minute earlier ("Bis zum So, 11.10.26, 22:59 Uhr änderbar").
  2. Cancel deadline – ShopDate.lastCancelDate. The whole order can be cancelled until then. It is the earliest item deadline of the order (see 3), so it can be far earlier than the change deadline; -1 means the order cannot be cancelled at all (locked by the back office, already in packing). Offer the cancel button only while this moment is ahead.
  3. Item deadline – per position. A TourLimit row for the item (iid > 0) or its category (iid < 0) on the order's tour (tid) shifts the change deadline: item deadline = lastOrderChangeDate + orderStopHour hours (orderStopHour is negative, e.g. -18). A value of 1 means the item is not offered on this tour at all. After its item deadline a position is frozen: it can neither be changed nor removed, and the order can no longer be cancelled. If Item.preOrderOnOrderStop is true the item may instead be ordered for the next ride (pre-order).

Independent of the ride, an item may have an order period and a delivery period (Item.orderPeriodStart/End, deliveryPeriodStart/End, preorderPossible): after orderPeriodEnd a position is frozen as well; a delivery period that starts after the selected date makes the item a pre-order for a later ride.

Headline: tell the customer where they are

Situation Show
before the change deadline date, address name, order number (if stored), "änderbar bis {lastOrderChangeDate}"
some positions have an earlier item deadline that is still ahead an extra line with the earliest item deadline and that cancelling is impossible afterwards (the standard shop uses a stop watch icon)
an item deadline has passed, change deadline not yet an extra line that the deadline for some items is over, the order cannot be cancelled anymore, the other positions stay changeable
after the change deadline "Der Bestellschluss für den {date} war {lastOrderChangeDate}" and a link to pick another date; no controls
ShopDate.isChangable = 0 or Order.stateid ≠ 0 "Diese Bestellung kann nicht verändert werden"; no controls
order date inside a Pause with pauseType 0 warning that a delivery pause is registered for this date
AuxDate entries within two weeks of the date list them (holidays, shifted delivery days)
UserInfo.role negative "Bitte kontaktiere uns, um die Bestellung zu ändern"; read-only cart

Buttons

Recommendation: Offer one primary button and decide it in this order:

Who / what, state Primary button Call on click
visitor, no date known "Weiter zur Anmeldung und Terminwahl" your logon / registration flow
visitor with an address check done "Weiter zur Anmeldung" api/newclient or api/regorder for a one-shot order
customer, no stored order, no subscriptions "Kaufen", worded by payment method (Lastschrift, Rechnung, Vorkasse, Barzahlung, PayPal, Wero) api/neworder with used_paycode
customer, no stored order, but existing subscriptions on this date "Änderungen jetzt absenden" api/neworder
customer, stored order "Änderungen jetzt absenden"; keep the provider button for PayPal / Wero / Vorkasse orders, a changed amount needs a new consent api/changeorder with oid
customer, stored order emptied in the cart big "Stornieren" api/cancelorder
customer without a usable payment method no button, a hint to complete the profile instead -

Enable the primary button only when the cart differs from the loaded order and none of these apply: total below the minimum order value (ShopDate.minOrderValue; with Config.min_order_strict the check is only strict within that many days before the deadline), total below zero, total above UserInfo.nc_limit for new customers, UserInfo.needs_tc = 1 and the customer has not ticked the terms checkbox yet (see "Do not forget"), a payment authorisation still pending. Enable the customer note field only when the order is otherwise ready to send.

Secondary controls:

Positions

Render for every position image, name, amount with unit, stepping controls honouring Item.AmountMin, AmountMax and AmountStep, the line total (Position.price if set, otherwise the item price) and the deposit (Position.refund, refundname). Then apply the states:

State Derived from Controls
locked order not changeable, change deadline passed, role < 0, item deadline passed, orderPeriodEnd passed, protection 50 or protected item none; show the reason as tooltip
delete only item hidden but already in the order, subscription-only item, pre-order item delivered after this date, protection 46 delete
no decrease / no increase protection 44 / 45 plus only / minus only
earlier deadline item deadline ahead but before the change deadline all, plus a stop watch and "Bestellschluss eher: {time}"
pre-order item not deliverable on this ride but on a later one all, label "Vorbestellung zum {date}"; group such positions under their own date heading
problem item no longer available (not in the current offering, sold out) delete; label "Artikel nicht lieferbar"
subscription Position.aboid > 0 show rhythm and validity; on delete ask "Abo beenden oder nur zu dieser Lieferung aussetzen?", on amount change ask "Abo ändern oder nur diese Lieferung?"
assortment box Position.aboboxenid > 0, boxname group the contained items under the box
duplicate same item twice in the cart label, let the customer jump to the twin (teh system avoids duplicates as far as possible)
price change Position.price ≠ current Item.price label "Preissenkung!" / "Preisanstieg"
discount Position.discount > 0, or bulk price reached label with the percentage
deleted Position.deleted = 1 do not show (or show struck through in an order history)

Removing the last position of a stored order is a cancellation: ask the customer first.

Submitting

After a successful submit show a thank-you block: delivery date, order number (ChangeOrderResult.changed), the change deadline, the confirmation e-mail address (or that none is stored), for first orders the customer number, and offers to look at the order again, pick another date, or start another order for the same day.

Do not forget

Ideas