Managing B2B Customer Accounts in the Nymble Commerce API

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.

Contact fields

Each entry in the 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

Price tiers are defined at the organization level. Common examples include 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.

You can deactivate a customer with a 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.

Contacts and addresses

A single customer account can have multiple contacts and multiple addresses, each with a type designation:

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.

Get Started

Core Concepts

Guides

Help

Managing B2B Customer Accounts in the Nymble Commerce API

Customer data model

Address fields

Contact fields

Example: creating a customer

Price tiers

Customer lifecycle

Contacts and addresses

​Customer data model

​Address fields

​Contact fields

​Example: creating a customer

​Price tiers

​Customer lifecycle

​Contacts and addresses

Customer data model

Address fields

Contact fields

Example: creating a customer

Price tiers

Customer lifecycle

Contacts and addresses