← API Index

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".

  1. Geocode the address with /api/geocode1 (zipcity, streetnr, country, ns=1 for a public page). Keep lat, lng and llq of the best GeoAddress — you post them with the registration so the stored delivery address has coordinates right away. llq below 5 means the location is vague (zip level); the shop components ask the customer to check the address.
  2. Find the tours with /api/findtour2 (lat, lng, zip, strategy=-10 for the shop's configured strategy, for_company=1/0 when you know whether it is a business, invcode if the visitor typed a code). You get TourDistance rows — candidate tours, isfull=1 for tours that cannot take new customers — and ShopDate rows, the next delivery dates of those tours. Let the customer pick one tour and pass its tourid as tourid1; a single tour can be preselected.
  3. No tour? If offer_depot is true, call /api/getdepots1 with the same lat/lng and offer the pickup stations (Address rows); pass the chosen depot's address id as depot. Otherwise send the visitor to wait_page with 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:

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:

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.

noad=0 means "yes, newsletter". What happens next depends on the shop:

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:

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:

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:

What is different from the two-step flow:

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

Ideas