Customer Number
(Kundennummer) Pro
CS-Cart gives you users. This add-on gives you customers with identity. Every real customer gets a permanent, human-readable Kundennummer — structured for invoicing, accounting, ERP sync, and cross-channel operations from day one.
01 Why you need Kundennummer — not just user_id
CS-Cart's user_id is a technical database key. It's sequential, auto-incremented, and meaningless to your accounting system, your ERP, your invoice template, and your customer on the phone. It changes meaning if you migrate platforms, merge databases, or archive old accounts.
A Kundennummer is a business identifier — stable, human-readable, and meaningful across every system and touchpoint in your company.
K-100042 — none of them know what to do with user_id = 1847.user_id remains untouched as the technical database key. Kundennummer lives alongside it as the business-layer identifier. No core CS-Cart tables are modified. Clean install, clean uninstall.INSERT … ON DUPLICATE KEY UPDATE with InnoDB row-level locking — race-condition safe even on high-traffic stores. A UNIQUE index on the number column is the final backstop.02 Number formats
Two formats are available. Choose before you start generating numbers — the format should stay consistent once customers have been assigned numbers.
000001 style, or none for 100001.K, DE-2026, CUST, or your company abbreviation. The dash separator is automatic. Prefix and zero-padding width are fully configurable.03 Dual ID architecture
The add-on introduces a clean separation between technical identity and business identity — two IDs that coexist without interfering with each other.
| Property | user_id (technical) | Kundennummer (business) |
|---|---|---|
| Purpose | Database foreign key | Business customer identifier |
| Format | Integer, auto-increment | Sequential or prefixed string |
| Immutable | Yes | Yes |
| Human-readable | No | Yes |
| On invoices / exports | Technically possible, not meaningful | Yes — designed for this |
| ERP / accounting aware | No | Yes |
| Touched by this add-on | Never — untouched | Created and managed |
04 External IDs
Three optional external ID fields can be enabled independently. Each has a configurable label so you can name it to match your specific systems. External IDs are entered manually in the customer profile — or pushed via API-driven sync from your integration layer.
DATEV: 12345
Lexware: K-789
PayPal: PAYER-...
Mollie: cst_kEn...
eBay: seller_id
Kaufland: ext_id
05 Requirements
| Requirement | Value | Notes |
|---|---|---|
| CS-Cart version | 4.6.1 – 4.99.x | Tested on CS-Cart 4.13 through 4.20.x |
| Supported editions | CS-Cart, Ultimate, Multi-Vendor | Works on all three editions with edition-appropriate UI |
| Database | MySQL / MariaDB with InnoDB | Uses InnoDB row-locking for atomic counter increments. Creates two addon tables. |
| PHP | 7.1+ | Compatible with all CS-Cart 4.6+ supported PHP versions |
| Core file edits | None | Hook-based only — no core CS-Cart tables or files are modified |
06 Installation & first setup
Purchase and download
Get the Customer Number Pro Add-On from the CS-Cart Marketplace and download the .zip archive.
Install via Admin Panel
In your CS-Cart admin go to Add-ons → Manage Add-ons → +, select the .zip and click Upload & Install. Two database tables are created automatically: ?:jukello_customer_numbers and ?:jukello_customer_number_counters.
Configure your number format
Go to Add-ons → Manage Add-ons → Customer Number Pro → Settings. Choose Sequential or Prefixed, set your prefix, starting number, and zero-padding. This is the most important step — decide before any numbers are generated.
Enable External IDs (optional)
In Settings → External IDs section, enable the fields you need (ERP ID, Payment Provider ID, Marketplace ID) and set their labels to match your systems. Disabled fields show no UI and are not stored.
Backfill existing customers
Go to Customers → Customer Numbers → Dashboard and run the backfill tool. This assigns Kundennummern to all existing customers who don't have one yet. New customers are numbered automatically from this point.
07 Settings reference
General
| Setting | Default | Description |
|---|---|---|
| Number format | Sequential | Sequential — pure numbers (100001, 100002). Prefixed — PREFIX-NUMBER (K-100001). Choose before generating any numbers. |
| Prefix | K | The prefix used in Prefixed mode. Can be any string: K, CUST, DE-2026. A dash separator is added automatically between prefix and number. |
| Starting number | 100001 | The first number in the sequence. The counter seeds itself to start_number − 1 on first use, so the first generated number equals exactly this value. |
| Zero padding (digits) | 6 digits | Total digit width of the number part: None (100001), 4 (0001), 6 (000001), 8 (00000001). Applied before the prefix in Prefixed mode. |
| Assign on | Registration | Customer registration — number assigned immediately when a customer account is created. First successful order — number assigned when the customer's first order is placed. |
External IDs
| Setting | Default | Description |
|---|---|---|
| Show ERP ID field | No | Enables the ERP ID field on customer profiles. When disabled, the field is completely hidden and no data is saved. |
| ERP ID field label | ERP ID | Custom label for the ERP ID field. Rename to match your system: "DATEV-Nummer", "SAP-Kundennummer", "Lexware ID". |
| Show Payment Provider ID | No | Enables the payment provider ID field. Useful for storing Stripe cus_ IDs, PayPal payer IDs, Mollie customer IDs. |
| Payment ID field label | Payment Provider ID | Rename to "Stripe Customer ID", "PayPal Payer ID", or your provider's terminology. |
| Show Marketplace ID | No | Enables the marketplace ID field for tracking cross-channel customer identifiers. |
| Marketplace ID field label | Marketplace ID | Rename to "Amazon Seller ID", "Kaufland ID", or whichever marketplace you use. |
Display
| Setting | Default | Description |
|---|---|---|
| Show Kundennummer in customer list | Yes | Adds a Kundennummer column to the admin customer list (Customers → Customers). Supports sorting and search/filter by Kundennummer. Disable to keep the column hidden. |
08 Admin dashboard
Navigate to Customers → Customer Numbers to access the dedicated dashboard. It gives you a live operational view of your customer number system.
09 Backfilling existing customers
When you install the add-on on a store with existing customers, none of them have a Kundennummer yet. The backfill tool handles this cleanly without disrupting your store.
Configure your format first
Set your number format, prefix, starting number, and zero-padding in Settings before running backfill. All numbers generated during backfill will use these settings — they cannot be changed retroactively.
Open the dashboard
Go to Customers → Customer Numbers. The KPI row shows how many customers are missing a number. The orange alert banner links directly to the backfill section.
Set batch size and run
Enter a batch size (default 50, max 500) and click Run backfill. Each run processes that many customers and redirects back with a result notice showing assigned / skipped / errors. Repeat until the missing count reaches 0.
Verify coverage
Coverage percentage in the KPI row reaches 100% when all active customers have a number. The orange alert banner disappears. New customers are numbered automatically going forward — no further action needed.
user_id order — oldest customers first. If you need a specific ordering (e.g. by registration date or total spend), export your customer list first and use the manual Assign now button on individual profiles in the desired order.10 CSV & EXIM export
Kundennummern are available in two export channels — a standalone CSV from the dashboard, and CS-Cart's native EXIM system for users.
| Export method | Access | Columns included |
|---|---|---|
| Dashboard CSV | Customers → Customer Numbers → Export CSV | User ID, Kundennummer, ERP ID, Payment Provider ID, Marketplace ID, Assigned Date, Email, First Name, Last Name, Status |
| CS-Cart EXIM | Administration → Export Data → Users | Adds "Kundennummer" column to the standard CS-Cart user export. Appears alongside all native CS-Cart user fields. |
CS-Cart gives you users. This gives you customers.
Permanent Kundennummern, ERP-ready external IDs, full audit trail — live in minutes.
11 Use cases
Connecting CS-Cart to DATEV or Lexware
Enable the ERP ID field and label it "DATEV-Mandantennummer". When a customer is onboarded in DATEV, enter their DATEV client number in the CS-Cart customer profile. Your Kundennummer becomes the stable reference ID for reconciling CS-Cart orders against DATEV invoices — eliminating the manual lookup step that currently costs your accounting team hours per month.
Stripe customer mapping
Enable the Payment Provider ID field and label it "Stripe Customer ID". After creating a Stripe customer object for a CS-Cart customer, store the cus_ ID in the field. When a payment dispute or refund request comes in via Stripe, you can find the CS-Cart customer instantly by Stripe ID — without cross-referencing by email or name.
Assigning on first order instead of registration
Set Assign on to "First successful order" in Settings. This reserves Kundennummern for customers who have actually made a purchase — avoiding numbers being assigned to accounts created speculatively or abandoned at registration. Useful for stores where registration is required to browse but purchase intent varies.
Migrating an existing store
Install the add-on. Configure your format to match your existing Kundennummer scheme if you have one from a previous system (e.g. set prefix to K, start number to your current highest + 1). Run backfill to assign numbers to all existing customers in ascending user_id order. For the small number of customers who need specific legacy numbers, use the manual Assign now button after using the counter reset tool to seed the correct value first.
B2B wholesale stores with account managers
The Kundennummer appears on the customer profile page and in the customer list column. Your account manager can look up a customer by Kundennummer instantly using the customer list search — and reference it in every email, quote, and invoice without ambiguity. External IDs let you additionally store the customer's own reference number (their internal ID for your company) in the Marketplace ID field.
12 FAQ
Can a Kundennummer change after it's assigned? ▼
What number formats are available? ▼
What are External IDs and when should I use them? ▼
Does this work on existing stores with thousands of customers? ▼
Can two customers accidentally get the same number? ▼
INSERT … ON DUPLICATE KEY UPDATE with InnoDB row-level locking — safe even under concurrent load. A UNIQUE index on the kunden_nr column is the final backstop. The CollisionGuard class retries up to 10 times before throwing an error (which in sequential/prefixed mode should never happen unless the counter table is manually corrupted).Does the add-on work with CS-Cart Multi-Vendor? ▼
Does the add-on appear in CS-Cart's EXIM (export/import) system? ▼
Does the add-on modify CS-Cart core tables? ▼
?:jukello_customer_numbers and ?:jukello_customer_number_counters) and uses CS-Cart's native hook system exclusively. No core CS-Cart tables or files are modified. Uninstalling the add-on drops both tables cleanly — or you can comment out the uninstall query to preserve data for archival.