> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nymblecommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing B2B Customer Accounts in the Nymble Commerce API

> Nymble Commerce's customer model supports company accounts, multiple contacts, addresses, contract pricing tiers, and sales rep assignments for B2B workflows.

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

```json theme={null}
POST https://api.achievemomentum.com/api/customers

{
  "CustomerNumber": "CUST-0042",
  "CompanyName": "Acme Wholesale Ltd.",
  "CompanyEmail": "orders@acmewholesale.com",
  "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": "jane.smith@acmewholesale.com",
      "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.

```text theme={null}
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](/concepts/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.

```json theme={null}
// Deactivate
POST https://api.achievemomentum.com/api/customers/{customerNumber}/deactivate

// Reactivate
POST https://api.achievemomentum.com/api/customers/{customerNumber}/activate
```

<Warning>
  When you deactivate a customer, any active sessions for that customer's portal users are invalidated. They will need to re-authenticate once reactivated.
</Warning>

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

<Tip>
  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.
</Tip>