Building a profile page with the API
The profile is where a customer looks after everything that is not a single order: his data, his subscriptions, pauses, favourites, discounts and what he still owes or is owed. This skill lists the sections of the standard shop and where their data comes from, so that your own page shows the same and changes things the same way. If you only want the ready-made page, embed the profile component instead (see use-js-components).
Data you need
Two calls deliver almost everything; load them once when the page opens:
| Call | Delivers |
|---|---|
| api/user | UserInfo (customer number, names, email, role, payment method and allowed payment methods, balance, notification settings, box count, ...), the customer's Tour and Address list, Box, Discount, bonus data and OutstandingPayment |
| api/dates | ShopDate (with the order id of each date that has an order), Pause, Subscription, deselected items and groups, Favourite |
Plus api/configuration for the shop rules (is the subscription feature on, which notification channels exist, ...) and api/order per order you want to show in detail.
Freshness. The customer data in api/user is the state of the customer's last login. After a change through
api/client/setprofile the response carries the new data; changes made by the
shop's back office meanwhile only show after the next login. The one exception is the list of open positions
(OutstandingPayment), which is read anew on every call.
Sections
| Section | Shows | Read from | Change with |
|---|---|---|---|
| Login data | customer number, email, password change | UserInfo |
api/client/setprofile |
| Settings & newsletter | newsletter, notification channels per event (email / SMS / push), remembered preferences | UserInfo (event_notification1..8, preferences), channels from Config |
setprofile |
| Interests & promotions | groups the customer can join or leave | api/system/actiongroups | api/client/actiongroup |
| Subscriptions | each subscription with frequency, amount, tour | Subscription, ShopDate, Pause |
addsubscription, changesubscription, dropsubscription |
| Delivery pauses | pauses, optionally for the subscription only | Pause, Subscription |
api/client/addpause, api/client/droppause |
| Deselected items | items and groups the customer never wants to receive | deselected items from api/dates |
api/client/dropdeselected |
| Favourites | remembered items | Favourite |
addfavourite, dropfavourite |
| Discounts | discounts, vouchers, bonus points | Discount, UserInfo, bonus data; campaigns from api/system/bonus/list |
api/client/applybonus |
| Box status | returnable boxes still at the customer's place | Box, UserInfo.boxcnt (if set, show the number rather than counting the list) |
- |
| Past orders | orders with date and state; open in cart, cancel | order ids from ShopDate, details from api/order |
api/client/cancelorder |
| Personal data, delivery | name, title, birthday, phone, company, delivery address, tour | UserInfo, Tour, Address |
setprofile |
| Payment | payment method, billing address, balance, open positions (see below) | UserInfo, OutstandingPayment |
setprofile; PayPal: api/client/ppauthorize |
| Delete account | reasons to pick, warning about open orders and subscriptions | api/system/goodbye_reasons | api/logout with unregister=true and an optional message |
Payment: balance and open positions
- Allowed payment methods. Offer only the codes in
UserInfo.allowed_paycodes; the shop has already filtered them for this customer. - Balance.
UserInfo.accountis the customer's account balance in the shop's accounting. The standard shop shows it only when it is not 0: "Dein Kontostand in unserem System beträgt {balance}." - Open positions.
OutstandingPaymentlists positions the shop has booked for the customer but not yet settled with an invoice, typically deposit. Each hasamount,service_dt(the delivery or service it belongs to, may be empty) andnote(the text to show). The list comes newest first and is usually short; the standard shop shows a small table (date, text, amount) under the balance, scrolling when long, and nothing at all when the list is empty. Shownoteas text, not as HTML. - Sign of an open position. A positive
amountis still to be paid by the customer, a negative one is still to be credited to them - the sign of an invoice line, the opposite of the balance, where a positive value is credit. The standard shop shows the amounts as booked and explains the sign in one line under the table. The open positions are not part ofUserInfo.accountyet, so don't subtract them from or add them to the balance shown.
Don't forget
- Guests and visitors. Without a login
api/userhas no customer. The standard shop then turns the page into the registration (personal data, delivery, payment, terms, saved with api/client/newclient); see new customer registration. - Roles. A negative
UserInfo.rolerestricts what the customer may change (no subscription changes, or no changes at all). Show the data read only and ask the customer to get in touch. - Trivial password. If
UserInfo.trivialis set (the password is trivial), ask for a new one before letting the customer change email or address. - Section switches. Some sections are optional per shop (discounts, box status, referral code, account deletion, subscriptions). Hide what the shop doesn't use instead of showing an empty section.
- Deep links. The standard shop opens a section from the URL hash (
#payment,#sub, ...). Mails and other pages link there, so keep the same names if your page replaces the standard one.
Ideas
- A "what do I owe" view combining the balance, open positions and unpaid orders.
- Remind the customer of returnable boxes from the box status before the next delivery.