> ## 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 Organizations API — Settings and User Management

> API reference for Nymble Commerce organization management, including retrieving org details, updating configuration, and managing organization settings.

Organization endpoints allow you to view and update your organization's settings, including display name, billing address, and pricing configuration. You can also manage users within your organization — assigning admin roles, removing them, and linking users to customer accounts.

<Note>
  Most organization endpoints require an **Admin** role. The sole exception is `POST /api/organizations` (create a new organization), which is public and does not require an existing token.
</Note>

***

## POST /api/organizations

Create a new organization and its initial admin user in a single request. This endpoint is public — you do not need an existing token to call it. It provisions both the organization record and an admin user account simultaneously.

### Request body

<ParamField body="Organization" type="object" required>
  Details about the organization to create.

  <Expandable title="Organization fields">
    <ParamField body="Name" type="string" required>
      The organization's display name.

      Example: `"Acme Corp"`
    </ParamField>

    <ParamField body="BillingAddress1" type="string">
      Primary billing street address.

      Example: `"123 Any Street"`
    </ParamField>

    <ParamField body="BillingAddress2" type="string">
      Secondary billing address line (suite, unit, etc.).

      Example: `"Suite 100"`
    </ParamField>

    <ParamField body="BillingCity" type="string">
      Billing city.

      Example: `"Miami"`
    </ParamField>

    <ParamField body="BillingStateProvince" type="string">
      Billing state or province code.

      Example: `"FL"`
    </ParamField>

    <ParamField body="BillingPostalCode" type="string">
      Billing postal / ZIP code.

      Example: `"33101"`
    </ParamField>

    <ParamField body="BillingCountry" type="string">
      ISO 3166-1 alpha-2 country code for the billing address.

      Example: `"US"`
    </ParamField>

    <ParamField body="PhoneNumber" type="string">
      Organization contact phone number.

      Example: `"561-555-1212"`
    </ParamField>

    <ParamField body="Email" type="string">
      Organization contact email address.

      Example: `"contact@acmecorp.com"`
    </ParamField>

    <ParamField body="Website" type="string">
      Organization website URL.

      Example: `"https://www.acmecorp.com"`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="User" type="object" required>
  Details about the initial admin user to create for the organization.

  <Expandable title="User fields">
    <ParamField body="FirstName" type="string" required>
      The admin user's first name.
    </ParamField>

    <ParamField body="LastName" type="string" required>
      The admin user's last name.
    </ParamField>

    <ParamField body="Email" type="string" required>
      The admin user's email address. Used as the login identifier.
    </ParamField>

    <ParamField body="Password" type="string">
      An initial password for the admin user. Ignored if this email is already registered on the platform.
    </ParamField>

    <ParamField body="PhoneNumber" type="string">
      The admin user's phone number.
    </ParamField>
  </Expandable>
</ParamField>

### Example request

```bash cURL theme={null}
curl -X POST https://api.achievemomentum.com/api/organizations \
  -H "Content-Type: application/json" \
  -d '{
    "Organization": {
      "Name": "Acme Corp",
      "BillingAddress1": "123 Any Street",
      "BillingAddress2": "Suite 100",
      "BillingCity": "Miami",
      "BillingStateProvince": "FL",
      "BillingPostalCode": "33101",
      "BillingCountry": "US",
      "PhoneNumber": "561-555-1212",
      "Email": "contact@acmecorp.com",
      "Website": "https://www.acmecorp.com"
    },
    "User": {
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "john.doe@acmecorp.com",
      "Password": "Password1234!",
      "PhoneNumber": "561-555-1212"
    }
  }'
```

### Response fields

<ResponseField name="OrganizationId" type="string">
  The unique Nymble Commerce organization ID for the newly created organization.
</ResponseField>

<ResponseField name="IdentityOrganizationId" type="string">
  The organization code used when calling `POST /api/auth/access` to enrich a user token.
</ResponseField>

<ResponseField name="Name" type="string">
  The organization's display name.
</ResponseField>

<ResponseField name="Slug" type="string">
  A URL-friendly identifier for this organization.
</ResponseField>

### Example response

```json theme={null}
{
  "OrganizationId": "6d24ab9faf9e034e881fcd97",
  "IdentityOrganizationId": "org_acme123",
  "Name": "Acme Corp",
  "Slug": "org_acme123"
}
```

### Error responses

| Status                      | Description                                                           |
| --------------------------- | --------------------------------------------------------------------- |
| `400 Bad Request`           | The organization name already exists, or required fields are missing. |
| `500 Internal Server Error` | An unexpected error occurred during provisioning.                     |

***

## GET /api/organization

Retrieve your organization's full details, including active subscriptions and feature entitlements. The organization ID is read from your JWT claims — you do not pass it as a parameter.

<Warning>
  **Requires Admin role.**
</Warning>

### Authentication

```text theme={null}
Authorization: Bearer {your_admin_access_token}
```

### Example request

```bash cURL theme={null}
curl https://api.achievemomentum.com/api/organization \
  -H "Authorization: Bearer {your_admin_access_token}"
```

### Response fields

<ResponseField name="Organization" type="object">
  The full organization record.

  <Expandable title="Organization fields">
    <ResponseField name="OrganizationId" type="string">
      The unique Nymble Commerce organization ID.
    </ResponseField>

    <ResponseField name="Name" type="string">
      The organization's display name.
    </ResponseField>

    <ResponseField name="BillingAddress1" type="string">
      Primary billing street address.
    </ResponseField>

    <ResponseField name="BillingCity" type="string">
      Billing city.
    </ResponseField>

    <ResponseField name="BillingStateProvince" type="string">
      Billing state or province.
    </ResponseField>

    <ResponseField name="BillingPostalCode" type="string">
      Billing postal code.
    </ResponseField>

    <ResponseField name="BillingCountry" type="string">
      Billing country code.
    </ResponseField>

    <ResponseField name="PhoneNumber" type="string">
      Organization contact phone number.
    </ResponseField>

    <ResponseField name="Email" type="string">
      Organization contact email address.
    </ResponseField>

    <ResponseField name="Website" type="string">
      Organization website URL.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="Subscriptions" type="array">
  A list of active subscription records for the organization.
</ResponseField>

<ResponseField name="Entitlements" type="array">
  A list of feature entitlements derived from the active subscription. Each entry describes a platform capability the organization has access to.
</ResponseField>

### Example response

```json theme={null}
{
  "Organization": {
    "OrganizationId": "6d24ab9faf9e034e881fcd97",
    "Name": "Acme Corp",
    "BillingAddress1": "123 Any Street",
    "BillingCity": "Miami",
    "BillingStateProvince": "FL",
    "BillingPostalCode": "33101",
    "BillingCountry": "US",
    "PhoneNumber": "561-555-1212",
    "Email": "contact@acmecorp.com",
    "Website": "https://www.acmecorp.com"
  },
  "Subscriptions": [],
  "Entitlements": []
}
```

### Error responses

| Status            | Description                                               |
| ----------------- | --------------------------------------------------------- |
| `400 Bad Request` | The organization derived from your token cannot be found. |
| `403 Forbidden`   | Your token does not carry the Admin role.                 |

***

## GET /api/organizations/users/admins

List all users who hold the admin role in your organization.

<Warning>
  **Requires Admin role.**
</Warning>

### Authentication

```text theme={null}
Authorization: Bearer {your_admin_access_token}
```

### Example request

```bash cURL theme={null}
curl https://api.achievemomentum.com/api/organizations/users/admins \
  -H "Authorization: Bearer {your_admin_access_token}"
```

### Response

Returns a list of `OrganizationUser` objects for every admin in your organization.

<ResponseField name="[]" type="array">
  <Expandable title="OrganizationUser fields">
    <ResponseField name="Id" type="string">
      The user's Nymble Commerce user ID.
    </ResponseField>

    <ResponseField name="Email" type="string">
      The user's email address.
    </ResponseField>

    <ResponseField name="FirstName" type="string">
      The user's first name.
    </ResponseField>

    <ResponseField name="LastName" type="string">
      The user's last name.
    </ResponseField>

    <ResponseField name="Roles" type="array of strings">
      The roles assigned to this user within the organization (e.g. `["admin"]`).
    </ResponseField>
  </Expandable>
</ResponseField>

### Example response

```json theme={null}
[
  {
    "Id": "kp_abc123def456",
    "Email": "john.doe@acmecorp.com",
    "FirstName": "John",
    "LastName": "Doe",
    "Roles": ["admin"]
  }
]
```

***

## POST /api/organizations/users/admins

Assign the admin role to a user in your organization. The user must already have a Nymble Commerce account. A welcome email is sent to the user upon successful assignment.

<Warning>
  **Requires Admin role.**
</Warning>

### Authentication

```text theme={null}
Authorization: Bearer {your_admin_access_token}
```

### Request body

<ParamField body="Email" type="string" required>
  The email address of the user to promote to admin.

  Example: `"jane.smith@acmecorp.com"`
</ParamField>

### Example request

```bash cURL theme={null}
curl -X POST https://api.achievemomentum.com/api/organizations/users/admins \
  -H "Authorization: Bearer {your_admin_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "Email": "jane.smith@acmecorp.com"
  }'
```

### Response fields

<ResponseField name="Success" type="boolean">
  `true` when the admin role has been successfully assigned.
</ResponseField>

### Example response

```json theme={null}
{
  "Success": true
}
```

### Error responses

| Status            | Description                                                                  |
| ----------------- | ---------------------------------------------------------------------------- |
| `400 Bad Request` | No user was found with the given email address, or the request is malformed. |
| `403 Forbidden`   | Your token does not carry the Admin role.                                    |

***

## DELETE /api/organizations/users/admins

Remove the admin role from a user in your organization.

<Warning>
  **Requires Admin role.**
</Warning>

### Authentication

```text theme={null}
Authorization: Bearer {your_admin_access_token}
```

### Request body

<ParamField body="UserId" type="string" required>
  The user ID of the admin to demote.

  Example: `"kp_abc123def456"`
</ParamField>

### Example request

```bash cURL theme={null}
curl -X DELETE https://api.achievemomentum.com/api/organizations/users/admins \
  -H "Authorization: Bearer {your_admin_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "UserId": "kp_abc123def456"
  }'
```

### Response fields

<ResponseField name="Success" type="boolean">
  `true` when the admin role has been successfully removed.
</ResponseField>

### Example response

```json theme={null}
{
  "Success": true
}
```

### Error responses

| Status            | Description                                      |
| ----------------- | ------------------------------------------------ |
| `400 Bad Request` | `UserId` is missing or the user cannot be found. |
| `403 Forbidden`   | Your token does not carry the Admin role.        |

***

## POST /api/organizations/users/associate-customer

Link a user account to a customer record within your organization. Once associated, that user's JWT is automatically enriched with the customer's `CustomerNumber`, `PriceTier`, and `CurrencyCode` on their next token enrichment call.

<Warning>
  **Requires Admin role.**
</Warning>

### Authentication

```text theme={null}
Authorization: Bearer {your_admin_access_token}
```

### Request body

<ParamField body="UserId" type="string" required>
  The user ID of the user to associate with a customer account.

  Example: `"kp_abc123def456"`
</ParamField>

<ParamField body="CustomerNumber" type="string" required>
  The customer account number from your ERP or order management system to link to this user.

  Example: `"C-10042"`
</ParamField>

### Example request

```bash cURL theme={null}
curl -X POST https://api.achievemomentum.com/api/organizations/users/associate-customer \
  -H "Authorization: Bearer {your_admin_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "UserId": "kp_abc123def456",
    "CustomerNumber": "C-10042"
  }'
```

### Response fields

<ResponseField name="Association" type="object">
  The newly created user-customer association record.

  <Expandable title="Association fields">
    <ResponseField name="UserId" type="string">
      The user ID.
    </ResponseField>

    <ResponseField name="CustomerNumber" type="string">
      The linked customer account number.
    </ResponseField>

    <ResponseField name="OrganizationId" type="string">
      The organization this association belongs to.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example response

```json theme={null}
{
  "Association": {
    "UserId": "kp_abc123def456",
    "CustomerNumber": "C-10042",
    "OrganizationId": "6d24ab9faf9e034e881fcd97"
  }
}
```

### Error responses

| Status            | Description                                         |
| ----------------- | --------------------------------------------------- |
| `400 Bad Request` | `UserId` or `CustomerNumber` is missing or invalid. |
| `403 Forbidden`   | Your token does not carry the Admin role.           |

***

## GET /api/organizations/users/associations

List all user-customer associations in your organization. Supports pagination, sorting, and filtering by `UserId` or `CustomerNumber`.

<Warning>
  **Requires Admin role.**
</Warning>

### Authentication

```text theme={null}
Authorization: Bearer {your_admin_access_token}
```

### Query parameters

<ParamField query="PageNumber" default="1" type="integer">
  Page of results to return (1-indexed).
</ParamField>

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

<ParamField query="SortOn" default="UserId" type="string">
  Field to sort by. Accepted values: `UserId`, `CustomerNumber`.
</ParamField>

<ParamField query="SortDirection" default="asc" type="string">
  Sort direction. Accepted values: `asc`, `desc`.
</ParamField>

<ParamField query="Filters" type="array">
  Optional array of filter objects. Each filter targets either `UserId` or `CustomerNumber`.

  **Supported operators:** `startswith`, `contains`, `notcontains`, `endswith`, `equals`, `notequals`, `gt`, `gte`, `lt`, `lte`
</ParamField>

### Example request

```bash cURL theme={null}
curl "https://api.achievemomentum.com/api/organizations/users/associations?PageNumber=1&PageSize=25&SortOn=UserId&SortDirection=asc" \
  -H "Authorization: Bearer {your_admin_access_token}"
```

### Response fields

<ResponseField name="Data" type="array">
  The current page of user-customer association records.
</ResponseField>

<ResponseField name="TotalCount" type="integer">
  The total number of associations matching the query (before pagination).
</ResponseField>

<ResponseField name="PageNumber" type="integer">
  The current page number.
</ResponseField>

<ResponseField name="PageSize" type="integer">
  The number of records per page.
</ResponseField>

### Example response

```json theme={null}
{
  "Data": [
    {
      "UserId": "kp_abc123def456",
      "CustomerNumber": "C-10042",
      "OrganizationId": "6d24ab9faf9e034e881fcd97"
    }
  ],
  "TotalCount": 1,
  "PageNumber": 1,
  "PageSize": 25
}
```

***

## POST /api/organizations/price-tiers

Add a new price tier to your organization. Price tiers are referenced when enriching user tokens and are used to return the correct pricing on product queries.

<Warning>
  **Requires Admin role.**
</Warning>

### Authentication

```text theme={null}
Authorization: Bearer {your_admin_access_token}
```

### Request body

<ParamField body="Name" type="string" required>
  A unique name for the price tier within your organization.

  Example: `"Wholesale"`
</ParamField>

<ParamField body="CurrencyCode" type="string" required>
  The ISO 4217 currency code for this tier.

  Example: `"USD"`
</ParamField>

### Example request

```bash cURL theme={null}
curl -X POST https://api.achievemomentum.com/api/organizations/price-tiers \
  -H "Authorization: Bearer {your_admin_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "Wholesale",
    "CurrencyCode": "USD"
  }'
```

### Response

Returns `200 OK` with an empty body on success.

### Error responses

| Status            | Description                                                                 |
| ----------------- | --------------------------------------------------------------------------- |
| `400 Bad Request` | `Name` or `CurrencyCode` is missing or the currency code is not recognized. |
| `403 Forbidden`   | Your token does not carry the Admin role.                                   |

***

## PUT /api/organizations/price-tiers

Update an existing price tier's name or currency code.

<Warning>
  **Requires Admin role.**
</Warning>

### Authentication

```text theme={null}
Authorization: Bearer {your_admin_access_token}
```

### Request body

<ParamField body="OldName" type="string" required>
  The current name of the price tier to update.

  Example: `"Wholesale"`
</ParamField>

<ParamField body="NewName" type="string" required>
  The new name for the price tier.

  Example: `"Retail"`
</ParamField>

<ParamField body="CurrencyCode" default="USD" type="string">
  The updated ISO 4217 currency code for this tier.

  Example: `"CAD"`
</ParamField>

### Example request

```bash cURL theme={null}
curl -X PUT https://api.achievemomentum.com/api/organizations/price-tiers \
  -H "Authorization: Bearer {your_admin_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "OldName": "Wholesale",
    "NewName": "Retail",
    "CurrencyCode": "USD"
  }'
```

### Response

Returns `200 OK` with an empty body on success.

### Error responses

| Status            | Description                                                                       |
| ----------------- | --------------------------------------------------------------------------------- |
| `400 Bad Request` | `OldName` does not match any existing price tier, or required fields are missing. |
| `403 Forbidden`   | Your token does not carry the Admin role.                                         |

***

## DELETE /api/organizations/price-tiers

Remove a price tier from your organization by name.

<Warning>
  **Requires Admin role.**
</Warning>

### Authentication

```text theme={null}
Authorization: Bearer {your_admin_access_token}
```

### Request body

<ParamField body="Name" type="string" required>
  The name of the price tier to delete.

  Example: `"Wholesale"`
</ParamField>

### Example request

```bash cURL theme={null}
curl -X DELETE https://api.achievemomentum.com/api/organizations/price-tiers \
  -H "Authorization: Bearer {your_admin_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "Wholesale"
  }'
```

### Response

Returns `200 OK` with an empty body on success.

### Error responses

| Status            | Description                                                                         |
| ----------------- | ----------------------------------------------------------------------------------- |
| `400 Bad Request` | `Name` does not match any existing price tier, or the organization cannot be found. |
| `403 Forbidden`   | Your token does not carry the Admin role.                                           |