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:
- 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"). - 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;-1means 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. - Item deadline – per position. A
TourLimitrow for the item (iid> 0) or its category (iid< 0) on the order's tour (tid) shifts the change deadline: item deadline =lastOrderChangeDate+orderStopHourhours (orderStopHouris negative, e.g. -18). A value of1means 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. IfItem.preOrderOnOrderStopis 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:
- "Stornieren" (small) for a stored order, or a new cart that only consists of due
subscriptions. Hide it when
lastCancelDateis-1or passed, when a position is protected (Position.protection≥ 50 or a protected item), or when the cart holds unsent subscription changes; show "Diese Bestellung kann nicht storniert werden" instead. - "Änderungen verwerfen" for a modified stored order, "Alles Löschen" for a modified new cart.
- "Zahlungsart ändern" when the customer has several allowed payment methods.
- "Weitere Bestellung zum {date} anlegen" when
Config.allow_multiple_per_touris true. - Hints instead of a disabled button: "noch keine Änderungen", "gerade gespeichert" (changed within the last five minutes, typically by autosave), "Der Warenkorb ist leer".
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
- Post the complete cart (
opos, one entry per position), never a delta. Mark positions that were already in the order withisPre=1. - api/neworder creates, api/changeorder
changes (
oidrequired), api/cancelorder cancels. All three return a ChangeOrderResult and the refreshedShopDatelist; reload the order afterwards, the back office may have adjusted prices or positions. - Map the error codes to the hints above instead of showing raw codes:
too_late(deadline passed, for a cancel: the cancel deadline),below_mbw,locked,protected_items,exceeded(order limit),no_change,duplicate,insufficient_sales_items(sold out meanwhile),retry(temporary, try again),not_auth. - A cart left open for a while gets stale: poll api/state with the
order id and its
last_changedand reload when it answerschanged,over,cancelledordeleted. - Save unsent carts with api/savecart; with the customer's opt-in they become orders automatically, see cart autosave.
- Payments by provider: customer Wero API and the PayPal calls (ppauthorize, ppresponse).
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
- Legal: terms of business. The customer accepts them once, at registration (
agb=1on api/newclient / api/regorder; the call is refused withagb_requiredotherwise). They only have to accept again when the shop changed its terms: the shop operator records the change date, and from then onUserInfo.needs_tcis 1 for every customer whose last acceptance is older. The date and an explanation of what changed are public configuration keys (agbChangeDate,agbChangeHint, readable through api/system/config). Show a checkbox linking toConfig.agb_link, ideally with that hint, and sendragb=1with the next api/neworder or api/changeorder; that stores the new acceptance date andneeds_tcgoes back to 0 after the next api/user call. The order calls do not refuse an order without the flag, so your client has to block the submit until the box is ticked. Do not ask on every order. - Legal: the rest. Keep the withdrawal ("Widerruf") link reachable from the cart. Show prices with
VAT, delivery cost and from which value it is free (
shippingCostLimit), and mark weighted items as approximate ("ca."). - Never promise what the server refuses. The cancel button follows
lastCancelDate, not the change deadline; a frozen position must not be editable. Otherwise the customer presses a button and getstoo_late. - Reload after every mutation and when the customer returns to the cart after a while
(
api/state). Deadlines are moments in the shop's time zone, compare them in that zone. - One cart per date. Switching the date (use only allowed dats per
ShopDate) switches the cart. Keep the order id with the cart once it is stored, and sendchangeorderorneworder, from then on as appropriate. - Blocked customers (
role< 0) see their order but may not change it; admins acting for them may. - Minimum order value is per address and date (
ShopDate.minOrderValue), pick-up stations may have their own; donations and tips are only offered once it is reached (see donations and tip). - Subscriptions are not an item in the cart: ending or pausing them is a different action with its own consequences, ask before you do it.
Ideas
- A countdown or colour change once less than a day remains until the earliest deadline.
- Highlight the position that blocks the cancellation when the customer tries to cancel.
- Offer "Vorbestellung" for frozen positions with
preOrderOnOrderStop, moving them to the next ride with one click. - Voice or chat clients: read back the three deadlines when the customer asks "can I still change my order?".
Related
- feed orders into the system – the order calls without a UI
- delivery date selection – why the date comes first
- cart autosave – saving carts that are never submitted
- reduced prices, sale off, donations and tip
- use the API – sessions, formats (
oo-rf=jsongives named fields), error handling