A Customer in Nymble Commerce represents a business account — not an individual person. Each customer has one or more contacts, shipping and billing addresses, a price tier that determines catalog pricing, and an optionally assigned sales rep. This model is designed for the complexity of real B2B relationships.
Customer data model
The table below covers the key fields on a customer record. Required fields are marked.
| Field | Type | Required | Description |
|---|
CustomerNumber | string | ✅ | Your external customer ID. Used to look up pricing, order history, and as the primary reference when syncing with your ERP or CRM. |
CompanyName | string | ✅ | Legal or trading name of the business. |
CompanyEmail | string | ✅ | Primary contact email for the company account. |
CompanyPhone | string | | Company phone number. |
CompanyFax | string | | Company fax number, if applicable. |
Pricing | string | ✅ | The price tier code assigned to this customer (e.g. "Wholesale", "Retail"). Controls which prices they see in the catalog. |
Active | boolean | | Whether the customer is active. Defaults to true. Inactive customers cannot log in or place orders. |
RepNumber | string | | The RepNumber of the sales rep assigned to this customer account. |
Terms | string | | The payment terms assigned to this customer (e.g. "Net30", "COD"). |
ExternalId | string | | Your own internal ID for syncing this customer with an external system. |
Addresses | array | | List of Address objects (see below). |
Contacts | array | | List of Contact objects (see below). |
CustomerAttributes | object | | Custom key-value attributes defined at the organization level. |
Address fields
Each entry in the Addresses array uses the following structure:
| Field | Type | Description |
|---|
Address1 | string | Street address line 1. |
Address2 | string | Street address line 2 (suite, unit, etc.). |
City | string | City. |
StateProvince | string | State or province. |
ZipPostalCode | string | ZIP or postal code. |
Country | string | Country. |
AddressType | string | Type of address — e.g. "Shipping" or "Billing". |
Code | string | Optional short code to identify this address (e.g. "WAREHOUSE-1"). |
Default | boolean | Whether this is the default address for its type. |
Contacts array uses the following structure:
| Field | Type | Description |
|---|
FirstName | string | Contact’s first name. |
LastName | string | Contact’s last name. |
Email | string | Contact’s email address. Used for login if this contact has a portal account. |
Phone | string | Contact’s direct phone number. |
ContactType | string | Role of this contact — e.g. "Primary", "Billing", "Shipping". |
Example: creating a customer
POST https://api.achievemomentum.com/api/customers
{
"CustomerNumber": "CUST-0042",
"CompanyName": "Acme Wholesale Ltd.",
"CompanyEmail": "[email protected]",
"CompanyPhone": "+1-555-0100",
"Pricing": "Wholesale",
"Active": true,
"RepNumber": "REP-007",
"Terms": "Net30",
"ExternalId": "erp_cust_9982",
"Addresses": [
{
"Address1": "123 Industrial Ave",
"City": "Chicago",
"StateProvince": "IL",
"ZipPostalCode": "60601",
"Country": "US",
"AddressType": "Shipping",
"Default": true
}
],
"Contacts": [
{
"FirstName": "Jane",
"LastName": "Smith",
"Email": "[email protected]",
"Phone": "+1-555-0101",
"ContactType": "Primary"
}
]
}
Price tiers
Every customer is assigned a pricing tier via the Pricing field. This tier code is embedded into their JWT as the PriceTier claim when they authenticate.
When a customer calls any catalog endpoint, Nymble Commerce reads the PriceTier claim from their token and automatically returns the matching price for each product. You don’t need to pass the tier in catalog requests — it resolves transparently.
Customer authenticates → JWT issued with PriceTier: "Wholesale"
↓
GET /api/products → Nymble Commerce filters prices → Returns Wholesale price per product
Wholesale, Retail, and Distributor, but you can name them anything. See the Organizations guide for how to create and manage price tiers.
Customer lifecycle
A customer account moves through the following states:
| State | Description |
|---|
Active (Active: true) | The customer can log in and place orders. All API calls on their behalf succeed normally. |
Inactive / Deactivated (Active: false) | The customer cannot log in or place orders. Their historical data (orders, invoices) is preserved and accessible to admins. |
POST to the deactivate endpoint, and reactivate them instantly via the activate endpoint. Deactivation is non-destructive — no data is deleted.
// Deactivate
POST https://api.achievemomentum.com/api/customers/{customerNumber}/deactivate
// Reactivate
POST https://api.achievemomentum.com/api/customers/{customerNumber}/activate
When you deactivate a customer, any active sessions for that customer’s portal users are invalidated. They will need to re-authenticate once reactivated.
- Multiple contacts — a customer might have a primary buyer, a billing contact, and a shipping coordinator. Each contact has their own email and can optionally hold a portal login.
- Multiple addresses — a customer with several warehouses can have a
Shipping address per location, and a separate Billing address for accounts payable.
Set Default: true on one address per type to indicate which should be pre-selected during checkout.
Use CustomerNumber as your stable external key when syncing Nymble Commerce with your ERP or CRM. Set it to match your existing customer ID in your system of record — this makes it trivial to cross-reference order and invoice data without maintaining a separate ID mapping table.