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

# Nymble Commerce Customers API — B2B Account Management Docs

> REST API reference for Nymble Commerce customer account management — create, list, search, update, activate, and deactivate B2B customer accounts.

The Customers API manages B2B account data — company info, contacts, addresses, pricing tiers, and sales rep assignments. Each customer belongs to an organization and is identified by a `CustomerNumber` that you assign (typically matching your ERP's account number). All endpoints require a valid Bearer token. The `OrganizationId` is read automatically from your JWT claims.

***

## List customers

Retrieve a paginated, sortable, and filterable list of customers in your organization.

```http theme={null}
GET https://api.achievemomentum.com/api/customers
```

### Query parameters

<ParamField query="pageNumber" default="1" type="integer">
  The page of results to return.
</ParamField>

<ParamField query="pageSize" default="25" type="integer">
  Number of customers per page.
</ParamField>

<ParamField query="sortOn" default="Name" type="string">
  Field to sort on. Common values: `Name`, `CustomerNumber`, `CompanyEmail`.
</ParamField>

<ParamField query="sortDirection" default="asc" type="string">
  Sort direction. Accepts `asc` or `desc`.
</ParamField>

<ParamField query="filters" type="array">
  Optional array of filter objects. Each filter has a `field`, `operator`, and `value`. Supported operators: `startswith`, `contains`, `notcontains`, `endswith`, `equals`, `notequals`, `gt`, `gte`, `lt`, `lte`.
</ParamField>

### Response

Returns a paginated result containing an array of [customer objects](#the-customer-object).

### Example

```bash theme={null}
curl -X GET "https://api.achievemomentum.com/api/customers?pageNumber=1&pageSize=25&sortOn=Name&sortDirection=asc" \
  -H "Authorization: Bearer {token}"
```

```json theme={null}
{
  "data": [
    {
      "customerNumber": "ACME-001",
      "companyName": "Acme Industrial Supply",
      "companyEmail": "purchasing@acmeindustrial.com",
      "companyPhone": "555-800-1000",
      "pricing": "Wholesale",
      "active": true,
      "repNumber": "SR-019",
      "terms": "NET30",
      "currencyCode": "USD"
    }
  ],
  "totalRecords": 214,
  "currentPage": 1,
  "totalPages": 9
}
```

***

## Get a customer

Retrieve a single customer by their `CustomerNumber`.

```http theme={null}
GET https://api.achievemomentum.com/api/customers/{customerNumber}
```

### Path parameters

<ParamField path="customerNumber" type="string" required>
  The customer's unique account number.
</ParamField>

### Response

Returns a single [customer object](#the-customer-object).

### Example

```bash theme={null}
curl -X GET "https://api.achievemomentum.com/api/customers/ACME-001" \
  -H "Authorization: Bearer {token}"
```

```json theme={null}
{
  "customerNumber": "ACME-001",
  "companyName": "Acme Industrial Supply",
  "companyEmail": "purchasing@acmeindustrial.com",
  "companyPhone": "555-800-1000",
  "companyFax": "555-800-1001",
  "pricing": "Wholesale",
  "active": true,
  "repNumber": "SR-019",
  "terms": "NET30",
  "externalId": "ERP-CUST-10042",
  "addresses": [
    {
      "externalId": "ADDR-001",
      "line1": "500 Commerce Drive",
      "line2": "Suite 200",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701",
      "country": "US",
      "addressType": "Shipping",
      "phone": "555-800-1000",
      "isPrimary": true
    }
  ],
  "contacts": [
    {
      "externalId": "CON-001",
      "title": "Ms.",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane.smith@acmeindustrial.com",
      "phone": "555-800-1002",
      "fax": "",
      "isPrimary": true,
      "contactType": "Purchasing"
    }
  ]
}
```

***

## Create a customer

Create a new B2B customer account. Use `PUT /api/customers` to upsert — if a customer with the given `CustomerNumber` already exists, Nymble Commerce updates that record.

```http theme={null}
PUT https://api.achievemomentum.com/api/customers
```

### Body parameters

<ParamField body="customerNumber" type="string" required>
  Your unique account number for this customer. Typically matches your ERP's account number.
</ParamField>

<ParamField body="companyName" type="string" required>
  The customer's company or business name.
</ParamField>

<ParamField body="companyEmail" type="string" required>
  Primary business email address for the account.
</ParamField>

<ParamField body="companyPhone" type="string">
  Main business phone number.
</ParamField>

<ParamField body="companyFax" type="string">
  Business fax number.
</ParamField>

<ParamField body="pricing" type="string" required>
  The price tier to apply to this customer, e.g. `Wholesale` or `Retail`. Must match a price tier configured in your organization.
</ParamField>

<ParamField body="active" default="true" type="boolean">
  Whether the customer account is active.
</ParamField>

<ParamField body="repNumber" type="string">
  The sales rep number assigned to this customer.
</ParamField>

<ParamField body="terms" type="string">
  Payment terms for this customer, e.g. `NET30`, `NET60`.
</ParamField>

<ParamField body="externalId" type="string">
  Your system's identifier for this customer. Used for idempotent imports — re-submitting a customer with the same `externalId` updates the existing record.
</ParamField>

<ParamField body="addresses" type="array">
  Array of [address objects](#address-object) for this customer. Include at least one billing and one shipping address.
</ParamField>

<ParamField body="contacts" type="array">
  Array of [contact objects](#contact-object) for this customer.
</ParamField>

<ParamField body="customerAttributes" type="object">
  A free-form dictionary of custom key-value attributes, e.g. `{ "region": "Southwest", "accountTier": "Gold" }`.
</ParamField>

### Response

Returns the created or updated [customer object](#the-customer-object).

### Example

```bash theme={null}
curl -X PUT "https://api.achievemomentum.com/api/customers" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerNumber": "ACME-001",
    "companyName": "Acme Industrial Supply",
    "companyEmail": "purchasing@acmeindustrial.com",
    "companyPhone": "555-800-1000",
    "pricing": "Wholesale",
    "active": true,
    "repNumber": "SR-019",
    "terms": "NET30",
    "externalId": "ERP-CUST-10042",
    "addresses": [
      {
        "externalId": "ADDR-001",
        "line1": "500 Commerce Drive",
        "line2": "Suite 200",
        "city": "Austin",
        "state": "TX",
        "postalCode": "78701",
        "country": "US",
        "addressType": "Shipping",
        "phone": "555-800-1000",
        "isPrimary": true
      }
    ],
    "contacts": [
      {
        "externalId": "CON-001",
        "title": "Ms.",
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "jane.smith@acmeindustrial.com",
        "phone": "555-800-1002",
        "isPrimary": true,
        "contactType": "Purchasing"
      }
    ]
  }'
```

***

## Update a customer

Update an existing customer account by their `CustomerNumber`. Any fields you include are overwritten; omitted fields retain their current values.

```http theme={null}
PUT https://api.achievemomentum.com/api/customers/{customerNumber}
```

### Path parameters

<ParamField path="customerNumber" type="string" required>
  The `CustomerNumber` of the account to update.
</ParamField>

### Body parameters

Same as [Create a customer](#create-a-customer). You can include a subset of fields to perform a partial update.

### Example

```bash theme={null}
curl -X PUT "https://api.achievemomentum.com/api/customers/ACME-001" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "companyPhone": "555-800-2000",
    "pricing": "Premium",
    "repNumber": "SR-022"
  }'
```

***

## Activate a customer

Re-activate a previously deactivated customer account, restoring their ability to place orders.

```http theme={null}
POST https://api.achievemomentum.com/api/customers/{customerNumber}/activate
```

### Path parameters

<ParamField path="customerNumber" type="string" required>
  The `CustomerNumber` of the account to activate.
</ParamField>

### Example

```bash theme={null}
curl -X POST "https://api.achievemomentum.com/api/customers/ACME-001/activate" \
  -H "Authorization: Bearer {token}"
```

Returns `204 No Content` on success.

***

## Delete a customer

Permanently remove a customer account and all associated data.

```http theme={null}
DELETE https://api.achievemomentum.com/api/customers/{customerNumber}
```

### Path parameters

<ParamField path="customerNumber" type="string" required>
  The `CustomerNumber` of the account to delete.
</ParamField>

<Warning>
  Deletion is permanent and cannot be undone. The customer's order history and associated records remain on file for reporting purposes, but the account itself cannot be recovered. If you may need to re-activate the customer in the future, deactivate the account instead using `active: false` on an [update](#update-a-customer) request.
</Warning>

### Example

```bash theme={null}
curl -X DELETE "https://api.achievemomentum.com/api/customers/ACME-001" \
  -H "Authorization: Bearer {token}"
```

Returns `204 No Content` on success.

***

## Address object

Each address in the `addresses` array contains the following fields:

<ResponseField name="externalId" type="string">
  Your system's unique identifier for this address. Use this for idempotent upserts when syncing from an ERP.
</ResponseField>

<ResponseField name="line1" type="string">
  Street address line 1.
</ResponseField>

<ResponseField name="line2" type="string">
  Street address line 2 (suite, unit, floor, etc.).
</ResponseField>

<ResponseField name="city" type="string">
  City.
</ResponseField>

<ResponseField name="state" type="string">
  State or province code.
</ResponseField>

<ResponseField name="postalCode" type="string">
  ZIP or postal code.
</ResponseField>

<ResponseField name="country" type="string">
  ISO 3166-1 alpha-2 country code, e.g. `US`, `CA`.
</ResponseField>

<ResponseField name="addressType" type="string">
  Either `Billing` or `Shipping`.
</ResponseField>

<ResponseField name="phone" type="string">
  Phone number for this location.
</ResponseField>

<ResponseField name="isPrimary" type="boolean">
  Whether this is the customer's primary address for its type.
</ResponseField>

***

## Contact object

Each contact in the `contacts` array contains the following fields:

<ResponseField name="externalId" type="string">
  Your system's unique identifier for this contact.
</ResponseField>

<ResponseField name="title" type="string">
  Salutation or title, e.g. `Mr.`, `Ms.`, `Dr.`.
</ResponseField>

<ResponseField name="firstName" type="string">
  Contact's first name.
</ResponseField>

<ResponseField name="lastName" type="string">
  Contact's last name.
</ResponseField>

<ResponseField name="email" type="string">
  Contact's email address.
</ResponseField>

<ResponseField name="phone" type="string">
  Contact's phone number.
</ResponseField>

<ResponseField name="fax" type="string">
  Contact's fax number.
</ResponseField>

<ResponseField name="isPrimary" type="boolean">
  Whether this is the primary contact for the customer account.
</ResponseField>

<ResponseField name="contactType" type="string">
  The role or category of this contact, e.g. `Purchasing`, `Accounts Payable`, `Receiving`.
</ResponseField>

***

## The customer object

<ResponseField name="customerNumber" type="string">
  Your unique account number for this customer.
</ResponseField>

<ResponseField name="organizationId" type="string">
  The organization this customer belongs to.
</ResponseField>

<ResponseField name="companyName" type="string">
  Company or business name.
</ResponseField>

<ResponseField name="companyEmail" type="string">
  Primary business email.
</ResponseField>

<ResponseField name="companyPhone" type="string">
  Main business phone.
</ResponseField>

<ResponseField name="companyFax" type="string">
  Business fax number.
</ResponseField>

<ResponseField name="pricing" type="string">
  The price tier assigned to this customer.
</ResponseField>

<ResponseField name="active" type="boolean">
  Whether the account is currently active.
</ResponseField>

<ResponseField name="repNumber" type="string">
  The assigned sales rep's number.
</ResponseField>

<ResponseField name="terms" type="string">
  Payment terms, e.g. `NET30`.
</ResponseField>

<ResponseField name="externalId" type="string">
  Your system's identifier for this customer.
</ResponseField>

<ResponseField name="addresses" type="array">
  Array of [address objects](#address-object).
</ResponseField>

<ResponseField name="contacts" type="array">
  Array of [contact objects](#contact-object).
</ResponseField>

<ResponseField name="customerAttributes" type="object">
  Custom key-value attribute dictionary.
</ResponseField>