Donations and Tip
Shop operators can configure special items — such as a tip for the driver or a charitable donation — that customers may add to their order. These items may be handled specialin an online shop.
These donation items have item type 78 and follow a few special rules described here.
Key rules
- Donation items are identified by item type 78.
- They may be hidden or visible, like any other item: the
hiddenflag only controls whether the item appears in the regular category and search listings. Independent of that flag, it is up to your implementation how donation items are placed into the cart — the reference implementation (standard shop) offers them as buttons atop the cart. - They do not count towards the minimum order value (MOV) or a delivery-cost limit (Lieferkosten). Only offer them once the MOV is already reached by regular items, and exclude their value when you compute or display MOV progress or a delivery-cost-limit threshold. Their price does count towards the order total the customer pays.
- Once a donation item is in the cart, treat it as always available — do not apply the usual availability or order-deadline checks to it.
- The reference implementation adds a fixed quantity of 1 per click and hides the button while a donation item is already in the cart.
1. Discover the configured donation items
Call /api/configuration40. The returned Config object contains
donation_item_ids— the ids of the configured donation items. An empty array means the feature is not used by this shop: render nothing in that case.
2. Load the item details
Fetch the items by id with
GET .../api/itemlist19?hidden=1&i=<comma separated ids>
Pass hidden=1 so you also receive donation items the operator chose to hide from the
regular shop. The response contains regular Item objects; use
name and the item image (if any) to render the donation buttons. Expect type = 78
on these items.
3. Present them in the cart
The standard shop shows one button per donation item in the cart's action area:
- Recommended: Show the buttons only when the MOV is reached (excluding donation positions from that calculation, and likewise from a delivery-cost-limit calculation if you show one) and the item is not already in the cart.
- Cart positions of type-78 items should carry a short disclaimer that the item does not
count towards the minimum order value. The translation key
boss.carth.donation.hint("Wird nicht auf den Mindestbestellwert angerechnet") is available in the Translation list of /api/configuration40. - you may highlight this items using its own icon or a general icon.
3a. It's a regular item — the button is only a shortcut
A donation item is a fully generic Item; the suggested-button flow above is
just one convenient way to add it, not the only one. Once a donation item is visible (not hidden,
or you deliberately surface it), your implementation may instead let the customer:
-
Open it like any other item (detail view / product page) and add it to the cart in any quantity via the normal add-to-cart flow — donation items are always treated as available, so the usual availability/order-deadline checks and the amount widget behave exactly as for a regular item.
-
Subscribe to it (Abo/recurring delivery) like a regular item, subject to the item's own
noabosetting — there is nothing donation-specific about subscribability. -
The MOV disclaimer is conditional: only render it when a minimum order value and/or a delivery-cost limit actually applies to the current order/tour — an item with neither configured should carry no disclaimer at all. When a delivery-cost limit is configured, mention delivery costs too, not just the MOV. Two translation keys are available in the Translation list of /api/configuration40 for this:
boss.carth.donation.hint— MOV-only wording, for when only a MOV applies.boss.carth.donation.hint.lk— combined wording mentioning both the MOV and the delivery-cost limit; use it whenever a delivery-cost limit applies (with or without a MOV also applying).
4. Submit the order
No special handling is needed.
The stored position appears like any other position in subsequent /api/order28 responses; identify it by its type 78 to keep rendering a disclaimer/Icons and to skip availability checks for it.
Related
- saleout — other item-level special behaviours
- Minimum order value: the MOV itself (per tour/address) is part of the shop date and configuration data; donation items are excluded from it (and from any delivery-cost limit) as described above.