> For the complete documentation index, see [llms.txt](https://docs.b2bridge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.b2bridge.io/integration/api-integration/public-apis-for-customer-groups.md).

# Public APIs for Customer Groups

### How to get the access key

Go to **Dashboard > Pubic API**, fill out the form and submit your access request. We’ll review it and send the access key to your email.

<figure><img src="https://3178254478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FjESAmWxlqUBmvo5xvYcH%2Fuploads%2FYkIWFztjUAIeD6MdbwTL%2Fimage.png?alt=media&amp;token=8dc2b807-e4eb-4b73-be5f-85a9c455a13c" alt=""><figcaption></figcaption></figure>

## Rule endpoints

There are fields of Customer Group rule, you need to understand:

* `id`: If provided and matches an existing customer group, the group will be updated. If omitted or does not match any existing group, a new customer group will be created.
* `name`<mark style="color:red;">\*</mark>: Customer group name.
* `customer_tags`<mark style="color:red;">\*</mark>: A tag is necessary to differentiate B2B and B2C customers. Must start with the prefix `"b2b-"`.
* `payment_options`<mark style="color:red;">\*</mark>
  * ONLINE: Pay online
  * NETTERM: Net payment term
* `pricing_rule_ids`: IDs of the price list rules to assign to the customer group.
* `collect_tax`
  * 0: Don't collect tax
  * 1: Collect tax

If the **`payment_options`** array includes **`NETTERM`**

* `nt_eligible`
  * ON\_RECEIPT: pay on receipt
  * CUSTOM: custom date net term
  * 7: pay after 7 days
  * 15: pay after 15 days
  * 30: pay after 30 days
  * 60: pay after 60 days
  * 90: pay after 90 days
* `nt_to_final_order`
  * 0: Net Terms orders as draft orders
  * 1: Net Terms orders as final orders
* `nt_tag_order_enable`
  * 0: disable
  * 1: enable
* `nt_tag_order_list`
* `nt_time_custom`: Defaults to `{"time": "DAY", "value": 1}` if not provided.\
  If specified, it must follow the structure
  * time: Must be one of `"DAY"`, `"WEEK"`, or `"MONTH"`.
  * value : If `time` is `"DAY"` must be between `1` and `365`. If `time` is `"WEEK"` or `"MONTH"` must be between `1` and `99`.
* `is_save_for_later`: boolean, defaults to `false`
* `nt_credit_limit`: `null`, or if provided must be an integer
* `nt_credit_option`:
  * defaults to `"ONE_TIME"`
  * fill in if `nt_credit_limit` is an integer; skip if `null`
  * allowed values: `"ONE_TIME"`, `"EVERY_MONTH"`, `"EVERY_QUARTER"`, `"EVERY_SIX_MONTHS"`, `"EVERY_YEAR"`
* `nt_credit_block`: boolean, defaults to `false`
* `order_tags`: if provided, must be an array of strings
* `tax_display_enabled`: boolean, defaults to `false`
* `tax_display`: must be `"incl_only"`, `"excl_only"`, or `"both"`, defaults to `"both"`
* `tax_display_primary`: must be `"incl"` or `"excl"`, defaults to `"incl"`

### Get all customer group by domain

<mark style="color:green;">**`GET`**</mark> `https://b2bridge-public-api.b2bridge.io/api/v1/customer-groups/get-by-domain`

#### Headers

| KEY                | VALUE |
| ------------------ | ----- |
| x-b2bridge-api-key | xxx   |

#### Params

| KEY    | VALUE             |
| ------ | ----------------- |
| domain | abc.myshopify.com |

#### Response <mark style="color:green;">`200`</mark>

```json
{
    "success": true,
    "message": "Get Customer Groups Successfully",
    "groups": [
        {
            "id": 1,
            "shop_id": 1,
            "name": "cg1",
            "customer_tags": "b2b-cus1",
            "pricing_rule_ids": "[1]",
            "payment_options": "[\"ONLINE\",\"NETTERM\"]",
            "nt_eligible": "ON_RECEIPT",
            "nt_limit_option": 0,
            "nt_limit_type": "QUANTITY",
            "nt_limit_value": "0",
            "nt_tag_order_enable": 0,
            "nt_tag_order_list": "[]",
            "nt_time_custom": "null",
            "nt_to_final_order": 0,
            "customer_ids": "[\"7875968794841\",\"7881979887833\"]",
            "collect_tax": 0,
            "nt_form_id": null,
            "created_at": "2025-05-23T04:46:48.149Z",
            "updated_at": null,
            "customerGroupPricing": [
                {
                    "pricing_rule_id": 1,
                    "customer_group_id": 1,
                    "shop_id": 1,
                    "created_at": "2025-05-23T04:46:48.154Z",
                    "updated_at": null,
                    "pricingListRules": {
                        "id": 1,
                        "name": "pl1"
                    }
                }
            ]
        }
    ]
}
```

### Get customer group by id

<mark style="color:green;">**`GET`**</mark> `https://b2bridge-public-api.b2bridge.io/api/v1/customer-groups/get-by-id`

#### Headers

| KEY                | VALUE |
| ------------------ | ----- |
| x-b2bridge-api-key | xxx   |

#### Params

| KEY    | VALUE             |
| ------ | ----------------- |
| domain | abc.myshopify.com |
| id     | 1                 |

#### Response <mark style="color:green;">`200`</mark>

```json
{
    "success": true,
    "message": "Get Customer Group By Id Successfully",
    "group": {
        "id": 1,
        "shop_id": 1,
        "name": "cg1",
        "customer_tags": "b2b-cus1",
        "pricing_rule_ids": "[1]",
        "payment_options": "[\"ONLINE\",\"NETTERM\"]",
        "nt_eligible": "ON_RECEIPT",
        "nt_limit_option": 0,
        "nt_limit_type": "QUANTITY",
        "nt_limit_value": "0",
        "nt_tag_order_enable": 0,
        "nt_tag_order_list": "[]",
        "nt_time_custom": "null",
        "nt_to_final_order": 0,
        "customer_ids": "[\"7875968794841\",\"7881979887833\"]",
        "collect_tax": 0,
        "nt_form_id": null,
        "created_at": "2025-05-23T04:46:48.149Z",
        "updated_at": null,
        "customerGroupPricing": [
            {
                "pricing_rule_id": 1,
                "customer_group_id": 1,
                "shop_id": 1,
                "created_at": "2025-05-23T04:46:48.154Z",
                "updated_at": null,
                "pricingListRules": {
                    "id": 1,
                    "name": "pl1"
                }
            }
        ]
    }
}
```

### Save or update customer group

* If the `id` field is **not provided** in the customer group, it will be treated as a **new customer group**.
* If the `id` field **is provided** and matches an existing, it will be treated as an **update to that existing customer group**.

<mark style="color:yellow;">**`POST`**</mark> `https://b2bridge-public-api.b2bridge.io/api/v1/customer-groups/save`

#### Headers

| KEY                | VALUE            |
| ------------------ | ---------------- |
| Content-Type       | application/json |
| x-b2bridge-api-key | xxx              |

#### Body

```json
{
    "domain": "abc.myshopify.com",
    "data": {
        "name": "cg6",
        "collect_tax": 1,
        "customer_ids": [
            "7875968794841"
        ],
        "customer_tags": "b2b-cus4",
        "payment_options": [
            "ONLINE",
            "NETTERM"
        ],
        "pricing_rule_ids": [],
        "nt_to_final_order":0,
        "nt_tag_order_enable": 0,
        "nt_eligible": "CUSTOM",
        "nt_time_custom": {
            "time": "DAY",
            "value": 1
        }
    }
}
```

#### Response <mark style="color:green;">`200`</mark>

```json
{
    "success": true,
    "message": "Created customer group successfully",
    "payload": {
        "id": 3
    }
}
```

### Save multiple customer group

<mark style="color:yellow;">**`POST`**</mark> `https://b2bridge-public-api.b2bridge.io/api/v1/customer-groups/bulk-save`

#### Headers

| KEY                | VALUE            |
| ------------------ | ---------------- |
| Content-Type       | application/json |
| x-b2bridge-api-key | xxx              |

#### Body

```json
{
    "domain": "abc.myshopify.com",
    "groups": [
        {
            "name": "cg7",
            "collect_tax": 1,
            "customer_ids": [
                "7875968794841"
            ],
            "customer_tags": "b2b-cus4",
            "payment_options": [
                "ONLINE"
            ],
            "pricing_rule_ids": []
        },
        {
            "id": 14,
            "name": "cg4",
            "collect_tax": 0,
            "customer_ids": [
                "7875968794841"
            ],
            "customer_tags": "b2b-cus3",
            "payment_options": [
                "ONLINE"
            ],
            "pricing_rule_ids": []
        }
    ]
}
```

#### Response <mark style="color:green;">`200`</mark>

```json
{
    "success": true,
    "message": [
        "Create new rule 'cg7' with ID 4 successfully",
        "Update rule ID 14 successfully"
    ]
}
```

### Delete customer group

<mark style="color:red;">**`DELETE`**</mark> `https://b2bridge-public-api.b2bridge.io/api/v1/customer-groups/delete-by-id`

#### Headers

| KEY                | VALUE |
| ------------------ | ----- |
| x-b2bridge-api-key | xxx   |

#### Params

| KEY    | VALUE             |
| ------ | ----------------- |
| domain | abc.myshopify.com |
| id     | 1                 |

#### Response <mark style="color:green;">`200`</mark>

```json
{
    "success": true,
    "message": "Delete Customer Group Successfully"
}
```

### Mass delete customer group

<mark style="color:yellow;">**`POST`**</mark> `https://b2bridge-public-api.b2bridge.io/api/v1/customer-groups/mass-delete`

#### Headers

| KEY                | VALUE            |
| ------------------ | ---------------- |
| Content-Type       | application/json |
| x-b2bridge-api-key | xxx              |

#### Body

```json
{
    "domain": "abc.myshopify.com",
    "ids": [
        9,
        10
    ]
}
```

#### Response <mark style="color:green;">`200`</mark>

<pre class="language-json"><code class="lang-json">{
    "success": true,
    "message": "Deleted customer groups successfully",
    "deleted": [
        9,
        10
    ],
    "failed": []
<strong>}
</strong></code></pre>

### Order Limit Fields

Customer groups now accept four optional fields that set a cart-wide minimum and/or maximum, by order amount or by item quantity (task BR-127). The storefront, Quick Order and Net terms block orders that fall outside the limit. Orders placed by a Sales Rep on behalf of a customer are not limited.

The fields apply only to stores whose account type is Customer Group. Per-product limits are still set in the Price List.

| Endpoint                              | Method | What changes                                                  |
| ------------------------------------- | ------ | ------------------------------------------------------------- |
| /api/v1/customer-groups/save          | POST   | Accepts the fields in data (create and update)                |
| /api/v1/customer-groups/bulk-save     | POST   | Accepts the fields on each item of groups (create and update) |
| /api/v1/customer-groups/get-by-id     | GET    | Returns the fields on group                                   |
| /api/v1/customer-groups/get-by-domain | GET    | Returns the fields on each item of groups                     |

Authentication and plan rules are unchanged: header x-b2bridge-api-key, parameter domain, Advanced or Enterprise plan.

#### Fields

All four fields are optional in a request; order\_limit\_min becomes required once a limit type other than NONE is set.

| Field               | Type           | Values                                            | Default | Notes                                                                                                                                                                   |
| ------------------- | -------------- | ------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| order\_limit\_type  | string         | NONE, AMOUNT, QUANTITY                            | NONE    | AMOUNT = cart subtotal after B2B pricing, before tax and shipping, in store currency. QUANTITY = total units across all line items.                                     |
| order\_limit\_min   | number         | ≥ 0; integer for QUANTITY                         | null    | Required when type is AMOUNT or QUANTITY. Ignored and stored as null when type is NONE.                                                                                 |
| order\_limit\_max   | number or null | ≥ 0 and ≥ order\_limit\_min; integer for QUANTITY | null    | null, empty or omitted = no maximum. Stored as null when type is NONE.                                                                                                  |
| order\_limit\_apply | string         | ALL, PRICE\_LIST                                  | ALL     | ALL counts every product in the cart. PRICE\_LIST counts only products in the price lists assigned to the group; with no price list assigned, the limit never triggers. |

In responses, order\_limit\_min and order\_limit\_max come back as decimal strings (for example "500.5"), because they are stored as numeric.

A customer in several groups gets the strictest combination: the highest min and the lowest max of each type. Amount and quantity limits from different groups are both checked.

#### Behavior on save

Sending none of the four fields leaves the limit alone; sending any of them sets the whole limit.

| Request                                                | Limit fields sent?         | Result                                                                                          |
| ------------------------------------------------------ | -------------------------- | ----------------------------------------------------------------------------------------------- |
| Create (save without id, or bulk-save item without id) | No                         | Group is created with No limit (NONE, ALL)                                                      |
| Create                                                 | Yes                        | Limit is saved; missing order\_limit\_type defaults to NONE, missing order\_limit\_apply to ALL |
| Update (save or bulk-save with id)                     | No                         | Stored limit is kept unchanged                                                                  |
| Update                                                 | Yes                        | Stored limit is replaced by the values sent                                                     |
| Any                                                    | order\_limit\_type: "NONE" | Min and max are cleared to null, even if values were sent                                       |

In bulk-save, an update writes only the four limit fields and the group's price lists; other stored settings such as email templates are not overwritten.

Validation runs on every group before anything is written. If one group in a bulk-save request is invalid, the whole request is rejected and no group changes.

#### Validation errors

An invalid limit returns HTTP 400 with success: false and a message array; each entry reads Rule '\<group name>' is invalid: \<error>.

| Condition                                                  | Error text                                                                                   |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| order\_limit\_type not one of the allowed values           | order\_limit\_type must be "NONE", "AMOUNT" or "QUANTITY"                                    |
| order\_limit\_apply not one of the allowed values          | order\_limit\_apply must be "ALL" or "PRICE\_LIST"                                           |
| Type is AMOUNT/QUANTITY and min is missing, null or ""     | order\_limit\_min is required when order\_limit\_type is "AMOUNT" (or "QUANTITY")            |
| AMOUNT min or max is negative or not a number              | order\_limit\_min must be a number greater than or equal to 0 (same for order\_limit\_max)   |
| QUANTITY min or max is negative, a decimal or not a number | order\_limit\_min must be an integer greater than or equal to 0 (same for order\_limit\_max) |
| Max is lower than min                                      | order\_limit\_max must be greater than or equal to order\_limit\_min                         |

Min and max must be JSON numbers. A numeric string such as "10" is rejected.

#### Examples

Create a group with a minimum order of $500 and a maximum of $1,000, counting only price-list products

```
POST /api/v1/customer-groups/save
x-b2bridge-api-key: <your key>
Content-Type: application/json

{
"domain": "your-store.myshopify.com",
"data": {
"name": "Wholesale",
"customer_tags": "b2b-wholesale",
"payment_options": ["ONLINE"],
"order_limit_type": "AMOUNT",
"order_limit_min": 500,
"order_limit_max": 1000,
"order_limit_apply": "PRICE_LIST"
}
}
{ "success": true, "message": "Created customer group successfully", "payload": { "id": 56 } }
```

#### Change an existing group to at least 10 items, no maximum; then remove the limit

```
{ "domain": "your-store.myshopify.com", "data": { "id": 56, "name": "Wholesale", "customer_tags": "b2b-wholesale", "payment_options": ["ONLINE"], "order_limit_type": "QUANTITY", "order_limit_min": 10, "order_limit_max": null } }

```

```
{ "domain": "your-store.myshopify.com", "data": { "id": 56, "name": "Wholesale", "customer_tags": "b2b-wholesale", "payment_options": ["ONLINE"], "order_limit_type": "NONE" } }
```

#### Bulk save: create one group and update another

```
POST /api/v1/customer-groups/bulk-save

{
"domain": "your-store.myshopify.com",
"groups": [
{ "name": "Retail", "customer_tags": "b2b-retail", "payment_options": ["ONLINE"],
"order_limit_type": "QUANTITY", "order_limit_min": 2, "order_limit_max": 20 },
{ "id": 56, "name": "Wholesale", "customer_tags": "b2b-wholesale", "payment_options": ["ONLINE"],
"order_limit_type": "AMOUNT", "order_limit_min": 250 }
]
}
```

```
{ "success": true, "message": ["Create new rule 'Retail' with ID 58 successfully", "Update rule ID 56 successfully"] }
```

#### Read a group — GET /api/v1/customer-groups/get-by-id?domain=your-store.myshopify.com\&id=58 returns the fields on group:

```
{ "order_limit_type": "QUANTITY", "order_limit_min": "2", "order_limit_max": "20", "order_limit_apply": "ALL" }
```

#### Validation error

```
{ "success": false, "message": ["Rule 'Wholesale' is invalid: order_limit_max must be greater than or equal to order_limit_min"] }
```

{% hint style="success" %}

### Need Help?

If you have questions or run into issues while using any feature, we’re here to help.

* 💬 **Start a** [**Live Chat** with our support team](https://go.crisp.chat/chat/embed/?website_id=a59f354c-f51f-4f84-ae9a-c0e8dd69d2e5) directly from your B2Bridge dashboard.
* 📧 **Email us at** [**support@b2bridge.io**](mailto:support@b2bridge.io) and we’ll get back to you as soon as possible.
  {% endhint %}
