Registering a new Customer
Read use-api.md first for API basics, sessions and response formats.
Registration is one POST to /api/client/newclient1. It creates the customer, stores the delivery address, signs the session in and triggers the shop's onboarding chain: tour or depot assignment, welcome mail, owner notification, newsletter opt-in, CRM sync, bank/address verification. Everything after the call happens in the back office (PCG) asynchronously — plan your UI around that, see What the backend changes afterwards.
A variant does registration and the first order in one call, the guest order (/api/client/regorder2, section 8).
The shop's own JavaScript components already implement all of this (profile component in registration mode, see use-js-components.md). This skill is for implementers who build their own form or onboard customers from another system.
1. Read the shop configuration first
/api/configuration40 (Config) tells you which parts of the form a shop needs:
| Config field | What it means for the form |
|---|---|
banking |
0 = no bank fields, 1 = optional, 2 = bank data required (see Bank data) |
reg_relaxed |
1: bank data is never enforced, even with banking = 2 |
agb_link |
if set, the customer must accept the terms (agb=1), otherwise agb_required |
dse_link, dse_required |
privacy policy link; if dse_required is true the customer must accept it (privacy-check=1), otherwise dse_required |
def_country |
preselect the country; country may be omitted |
offer_depot |
the shop offers pickup stations — show the depot alternative when no tour serves the address |
wait_page |
waiting-list page to send the visitor to when neither a tour nor a depot serves the address |
auto_optin |
true: a ticked newsletter box subscribes immediately; false: a double-opt-in mail is sent first |
nl_page |
newsletter information page to link next to the checkbox |
has_voucher_or_coupon |
show an input for referral / invitation codes |
new_customer_id |
the temporary id the shop uses for not-yet-registered visitors (guest sessions) |
/api/system/register_reasons lists the "how did you
hear about us" options (RegisterReason); submit the chosen
reason text as note.
2. Check whether the shop delivers to the address
Do this before the customer fills the rest of the form — nothing is more annoying than a complete form answered with "we do not deliver here".
- Geocode the address with /api/geocode1 (
zipcity,streetnr,country,ns=1for a public page). Keeplat,lngandllqof the best GeoAddress — you post them with the registration so the stored delivery address has coordinates right away.llqbelow 5 means the location is vague (zip level); the shop components ask the customer to check the address. - Find the tours with /api/findtour2 (
lat,lng,zip,strategy=-10for the shop's configured strategy,for_company=1/0when you know whether it is a business,invcodeif the visitor typed a code). You get TourDistance rows — candidate tours,isfull=1for tours that cannot take new customers — and ShopDate rows, the next delivery dates of those tours. Let the customer pick one tour and pass itstouridastourid1; a single tour can be preselected. - No tour? If
offer_depotis true, call /api/getdepots1 with the samelat/lngand offer the pickup stations (Address rows); pass the chosen depot's addressidasdepot. Otherwise send the visitor towait_pagewith the address prefilled. Every miss is recorded by the shop automatically, the operator sees unserved demand on a map — you do not need to log anything.
Invitation codes. A tour or depot may be reachable only by code (TourDistance.code).
findtour2 / getdepots1 with invcode skip the distance and postal-code checks and return
the matching tour even if it is hidden; an unknown code yields empty lists. Pass the same
value as invcode to the registration — it is recorded with the new customer so the
operator can see where they came from. A referral code of an existing customer typed into
the same input is not a tour code: keep it client-side and apply it in the cart later.
3. Submit the registration
POST /api/client/newclient1. All fields are plain form parameters; the generated parameter list on the endpoint page is the reference, the groups below explain what belongs together. Parameters marked * are accepted but not listed there.
Identity: opener, firstname, name, email (login name; required unless the shop
says otherwise), email1 (CC copies only, cannot log in), phone, mobile, lang,
birthday. company, dept, vatid for business customers; for_company=1* marks the
account as a business customer (this also selects business tours in step 2).
Password: passwd + verify. You may omit both: the shop then generates a password and
the welcome mail carries it. The customer can request a new one any time via
/api/client/password2.
Invoice address: street (max. 35 characters), zip, city, country.
Delivery address: dstreet, dzip, dcity, dname, dcompany, ddept* — only
when it differs from the invoice address, see the next section. lat, lng, llq* from
the geocoding step. depot* = address id of a chosen pickup station.
Tour: tourid1 from findtour2, or usenct=1 to let the shop assign its configured
new-customer tour. Without either the customer has no tour and no delivery dates until the
back office assigns one — shops with a configured new-customer tour usually want usenct=1
when your own lookup found nothing.
Placement note ("where to leave the box"): placecode* — a bitmask, 1 usually at
home, 2 use the named place, 4 use a neighbour — and placenote (free text, max. 200).
Both are kept verbatim; once the back office has set up the address they appear as the
editable chint on the customer's delivery address (Address v23).
Legal: agb=1 when agb_link is set, privacy-check=1* when dse_required is true.
The acceptance timestamps are stored with the customer; the profile later tells you via
needs_tc if the terms changed and must be accepted again.
Bank data: e_bank, e_blz (BIC), e_konto (IBAN; IBAN* is an alias). See
Bank data for when they are enforced.
Newsletter: noad=0* subscribes, noad=1 (the default when omitted) does not. Combined
with auto_optin, see Newsletter consent. Never pre-tick this.
Marketing: note = the register reason text, invcode* from step 2.
Technical: checkemail=1 (refuse if the email is already registered — recommended),
dupcheck (a random value per form rendering; a second submit with the same value is
rejected as duplicate), keep=1* (set a persistent-login cookie, like "remember me"),
silent=1 (admin only, see Creating customers from your own system).
4. Invoice address vs. delivery address — where each one lands
The registration takes two address sets and stores them in two different places:
| You post | Stored as | Returned as |
|---|---|---|
street, zip, city, country, company, dept |
the customer's invoice address on the customer record | street, zip, city, ... on UserInfo |
dstreet, dzip, dcity, dname, dcompany, ddept |
the customer's delivery address — one Address record named Lieferadresse (or Depot <name> when depot was given, then with the depot's street) |
the addresses list of the response and of /api/user33; also mirrored as dstreet, dzip, ... on UserInfo |
Rules:
- Both sets posted: invoice address on the customer, delivery address as the address record. Deliveries, tour lookups and date selection use the address record; invoices use the customer record.
- Only the plain set posted (
street/zip/city): it serves as both. The address record is created from it and namedStandard. - Only the delivery set posted (
dstreet/dzip/dcity): it is also copied into the invoice fields, so the customer always has an invoice address. The address record is still namedLieferadresse. (The shop's own form posts this way.) - Depot: the address record carries the depot's street and
dadr= depot id. If the shop allows it, the customer's home address is stored as a second, usually hidden, address record so the customer can switch to home delivery later. - Exactly one delivery address record is created (two with the depot alternative). The
coordinates
lat/lng/llqare only on the address record if you posted them; the tour on it istourid1.
The address record ids, names and the customer id itself are provisional — the back office renumbers and may relabel them when it imports the customer, see section 6.
5. What you get back
On success the response contains:
- NewClientResult:
result=address_new_mail(welcome mail sent) oraddress_new(no mail, e.g. silent mode). - UserInfo: the full profile of the now authenticated
session (
auth=AUTH). Noteallowed_paycodes: until the back office has processed the customer it reflects the shop's configured payment methods, not a decision about this customer.noadshows the stored newsletter state,sepa_mandateis empty — the mandate is created by the back office. - Tour list: the assigned tour, empty if none.
- Address list: the delivery address record(s) from section 4.
- ShopDate: the next delivery date the session was placed on — empty if the customer has no tour yet.
boxesanddiscounts: empty for a new customer.
The session is signed in; no separate logon is needed. Continue with the delivery date
(delivery-date-selection.md, /api/client/settour5)
and the first order. Re-read the profile with /api/user33 whenever
you need the current state (newer Address version with chint, bonus data).
Errors
Errors come as HTTP 400 with the code in the X-oekobox-error header
(parameter_error as parameter_error:<field>:<reason>):
| Code | What to do |
|---|---|
email_exists |
the address is already registered: offer the login and a "forgotten password" link (password2) instead of a second account |
email_required |
the shop requires an email |
agb_required, dse_required |
the respective checkbox was not accepted |
bank_required |
the shop requires bank data and none was given, see below |
parameter_error |
a field failed validation; field names it (customers.email, customers.e_konto, ...), reason is too_short, too_long, is_null, verify (passwords differ), email_wrong, iban |
duplicate |
the same dupcheck value was submitted before — the first submit most likely succeeded |
tblocked |
too many registrations from this IP (30 within 30 minutes); tell the user to try later |
address_not_new |
internal re-submit guard, treat like duplicate |
403 violation |
the session is already signed in as a customer, or the request tried to set a role. The shop also signs that session out; start a fresh session |
Bank data
With banking = 2 (required) the shop insists on an IBAN unless the customer has another
way to pay: PayPal is configured and chosen, another non-bank payment method is available
for this customer type, or reg_relaxed is set. The check only runs for German-language
requests. Bank data entered here is the basis for the SEPA direct-debit mandate, which the
back office creates (sepa_mandate on the profile); until then direct debit is not yet
"approved" for the customer. Optionally the shop verifies bank data and address with its
payment provider after the registration — nothing you need to handle.
Newsletter consent
noad=0 means "yes, newsletter". What happens next depends on the shop:
auto_optinfalse (double opt-in): the subscription is parked, the customer receives a confirmation mail and is subscribed only after clicking it.noadin the profile stays "not subscribed" until then.auto_optintrue: subscribed immediately.- Some shops subscribe every new customer regardless of the checkbox (their legal basis, not yours).
Show the checkbox unticked and link nl_page; a pre-ticked box is not a valid consent.
6. What the backend changes afterwards
The back office imports every new customer from a queue, usually within minutes but possibly hours. Expect these changes:
- The customer id changes. The id returned at registration is provisional; the imported
customer gets a new id. A logon with the old id still works (the shop resolves it), and
emailis stable, but do not store the registration id as a foreign key in your system — read the id from the profile after the next logon instead. - Addresses are renumbered and may be relabeled (
Standard,Lieferadresse, a tour name, ...). The back office may also add the invoice address as an address record or attach driver hints. Always work with the currentaddresseslist from /api/user33. - Placement note:
placecode/placenoteare turned into the address'schint, which the customer can edit in the profile. - Payment methods:
allowed_paycodesbecomes the back office's decision for this customer; a SEPA mandate appears once created. - Tour and dates: the back office may assign a different tour. Until the import is through, the customer counts as "new": a tour can withhold its nearest delivery dates from new customers (longer lead time), so the date list may grow after the import. Do not cache the dates from the registration response.
- Bonus and action groups: if the shop tags new registrations with an action group
(welcome series, marketing), the id shows up in
actiongroupson the profile after the import; bonus campaigns the customer is eligible for appear in the profile's bonus data (see bonus_system.md, actiongroups.md).
7. Creating customers from your own system
An integration that creates customers on behalf of the shop (CRM, telephone orders, a
second storefront) uses a session authenticated as a staff user with API permission and
calls newclient1 in that session:
silent=1suppresses the customer-facing mails (welcome mail, password mail) for the rest of that session; the owner notification is still sent. Withoutsilent, the new customer receives the welcome mail with a generated password.- Such a session may register several customers in a row; a plain customer session may not
(
violation). - Posting only
street/zip/cityis fine, the address record is created from them (section 4). Postlat/lng/llqif you have them, otherwise the back office geocodes. - Use
usenct=1or atourid1fromfindtour2, otherwise the customer has no delivery dates until the back office assigns a tour. - Follow with feed-orders-into-the-system.md to place the first order in the same session.
8. Registration and first order in one call
/api/client/regorder2 registers the customer and
places their first order in a single POST — the "guest order": a visitor fills the cart,
enters their address and is done. It is the same registration as newclient1 followed by
the same order submission as /api/client/neworder8, in
one request and one session.
What it takes. All registration parameters of section 3 — with the delivery address
(dstreet, dzip, dcity, dcompany, ddept) being the required set here, and
street/zip/city optional "for invoicing"; the storage rules of section 4 apply
unchanged. Plus the order:
ddate_iso— the delivery date (yyyy-MM-dd or ISO timestamp) andtour— the tour id, both taken from thefindtour2result of step 2. Without a date the call fails withno_date; the shop does not pick one for you.opos— the order positions, one parameter occurrence per position, pipe-delimited (item id, amount, unit, ...): the same format asneworder8, see its parameter list and feed-orders-into-the-system.md.used_paycode— the payment method the customer chose; it must be one the shop allows for new customers (seeallowed_paycodesin section 5).usenct=1ortourid1as in section 3 when you did not look the tour up yourself.
What is different from the two-step flow:
- Every call creates a new customer account. The email duplicate check is switched
off for this endpoint (the
checkemailparameter has no effect), so a returning guest who orders again with the same email becomes a second customer record; the back office merges or tolerates that. If you want one account per email, use the two-step flow withcheckemail=1, or look the customer up first. - The session is signed out at the end, unless you pass
no_logout=1. The response therefore contains the order side only: ChangeOrderResult (changed= the new order id), the ShopDate list with the ordered date, and empty subscription/favourite lists — no UserInfo, no Address. If you need the customer id or the stored address, passno_logout=1and read /api/user33 in the same session; remember that the id is provisional anyway (section 6). - Two kinds of errors. Registration-side refusals (
email_required,agb_required,dse_required,bank_required,tblocked, ...) come as HTTP 409 here,parameter_erroras 400 — and nothing is stored. Order-side refusals (no_date,too_late,below_mbw,exceeded,protected_items,insufficient_sales_items,emptyas 404,retry) come after the customer was created: the account exists, the order does not. Show the error, keep the form data and let the user retry the order — but not the registration (that would create a third account);no_logout=1plusneworder8in the same session is the clean way to resubmit. - Two mails go out: the welcome mail with the generated password (unless
silent) and the order confirmation, each with the shop's templates.
Typical uses: a landing page that sells one fixed box ("Probierkiste") to first-time customers without a shop visit, a kiosk or event sign-up with a starter order, or an external storefront that hands over new customers together with their first basket.
Don't forget
- Legal: terms and privacy acceptance are the customer's active action — never
pre-tick, keep the links visible, and re-check
needs_tcon later logons. The newsletter box is a separate consent (double opt-in where configured). - Bank data is sensitive: transport only over HTTPS, do not echo the IBAN back in full (the API masks it in the profile for a reason), and tell the customer that a SEPA mandate is created from it.
- Geocode before you submit and show the resolved address for confirmation; a wrong house number costs the driver a tour stop.
- Honour
isfullon tours and depots, and do not offer hidden tours without a code. - Rate limits and duplicates: generate a fresh
dupcheckper form rendering and do not retry a successful submit; the shop blocks an IP after 30 registrations in 30 minutes. - Provisional ids: nothing you get back at registration is a stable key except the email. Re-read the profile after the backend import.
- Guest orders multiply accounts:
regorder2never checks for an existing email. Fine for a one-off landing page, a nuisance when the same people order every week — then use the two-step flow or a login for returning customers. - Business customers: set
companyandfor_company=1so the tour lookup and the payment options match; B2B shops show net prices, see supporting-b2b-customers.md. - Welcome mail content (shop name, password, next date) is defined by the shop, not by
the API caller; if you need your own onboarding mail use
silent=1and send it yourself.
Ideas
- A "do you deliver to me?" widget on the landing page: zip/street input,
geocode1+findtour2, and the result "next delivery: Thursday" with a link straight into the prefilled registration — the miss log tells the operator where demand is. - A depot map:
getdepots1with the visitor's location, markers with the next delivery date, one click into the registration withdepotpreset. - Referral landing pages: the tour's
codeas part of a link (?invcode=...), so a partner, a farm shop or a neighbourhood initiative can invite customers into a tour that is otherwise hidden. - Onboarding checklist after registration: tour and date chosen, placement note entered, newsletter confirmed, bonus campaign joined — each item backed by the profile data.