Public API v2: Auto Tag

Rules that tag customers and orders, add notes or mark a customer tax exempt when an event happens.


Scopes	`auto-tag:read`, `auto-tag:write`
Plan	Your current plan must include Auto Tag; otherwise `403`
Takes effect	Applies as soon as it is saved. No upload.

Every response has the same envelope (success, status, data, meta; see Responses). Returns below describes data. The examples are real calls; the rules were created disabled.

Good to know

Rules apply as soon as they are saved; there is no upload for Auto Tag.
A condition has field or form_field. form_field is a field of the registration form form_id and goes with customer_created only. The form is not checked: an unknown form_id saves a rule that never matches.
Each event takes the fields the app offers for it. Paid-order totals need paid_orders_days (1–365); weight fields need unit (g, kg, lb, oz).
Tags in an action value are comma-separated. mark_tax_exempt takes no value and appears once at most.

The rule object

What every read returns. Lists come back as [] when empty, never null.

idstringread-only

Rule id.

namestring

Rule name.

priorityinteger

Lower number wins; see Rules.

statusenum

disabled rules are kept but not applied. One of disabled, enabled.

eventenum

One of customer_created, order_created, order_paid, order_fulfilled, order_cancelled.

form_idstring or null

matchenum

One of all, any.

conditions[object]

Show fields

fieldenum or null

One of customer_name, customer_email, customer_first_name, customer_last_name, customer_tags, customer_orders_count, customer_total_spent, shipping_city, shipping_country, shipping_province, shipping_postcode, billing_city, billing_country, billing_province, billing_postcode, default_address_city, default_address_country, default_address_province, default_address_postcode, product_name, product_sku, order_items_count, order_quantity, order_amount, paid_orders_amount, paid_orders_count, order_weight, paid_orders_weight.

form_fieldobject or null

form_field.namestring

form_field.labelstring

operationenum

One of contains, not_contains, equals, not_equals, greater_than, less_than, greater_than_or_equal, less_than_or_equal, starts_with.

valuestring or null

unitenum or null

One of g, kg, lb, oz.

paid_orders_daysinteger or null

actions[object]

Show fields

typeenum

One of add_customer_tags, remove_customer_tags, add_customer_note, add_order_note, add_order_tags, remove_order_tags, mark_tax_exempt.

valuestring or null

created_atstring or nullread-only

UTC, ending in Z.

updated_atstring or nullread-only

UTC, ending in Z.

{
  "id": "28",
  "name": "Tag EU wholesalers",
  "priority": 1,
  "status": "disabled",
  "event": "customer_created",
  "form_id": "12",
  "match": "all",
  "conditions": [
    {
      "field": null,
      "form_field": {
        "name": "country-field",
        "label": "Country"
      },
      "operation": "equals",
      "value": "Germany",
      "unit": null,
      "paid_orders_days": null
    },
    {
      "field": "customer_email",
      "form_field": null,
      "operation": "contains",
      "value": "@acme.de",
      "unit": null,
      "paid_orders_days": null
    }
  ],
  "actions": [
    {
      "type": "add_customer_tags",
      "value": "eu,wholesale"
    },
    {
      "type": "mark_tax_exempt",
      "value": null
    }
  ],
  "created_at": "2026-10-21T09:34:27.000Z",
  "updated_at": "2026-10-21T09:34:27.000Z"
}

List rules

GET/api/v2/auto-tag/rules

Scope auto-tag:readCost 10

List rules, newest first, with their conditions and actions.

Query parameters

limitinteger

1–250, default 50. See Paging.

cursorstring

next_cursor or prev_cursor of the last page; leave out for the first page. Keep the same filters on every page.

filter_statusenum

One of disabled, enabled.

filter_namestring

Part of the name, any case. 1–200 characters.

filter_eventenum

One of customer_created, order_created, order_paid, order_fulfilled, order_cancelled.

Returns

data[Rule]

The rules of this page; [] when there are none.

meta.paginationobject

limit, next_cursor, prev_cursor and links to the next and previous pages.

Request
Response

curl -X GET "https://solution-public-api.bss-b2b.solutions/api/v2/auto-tag/rules?limit=2&filter_name=Tag" \
  -H "X-API-Key: $B2B_API_KEY" \
  -H "X-Shop-Domain: your-store.myshopify.com"

{
  "success": true,
  "status": "success",
  "data": [
    {
      "id": "28",
      "name": "Tag EU wholesalers",
      "priority": 1,
      "status": "disabled",
      "event": "customer_created",
      "form_id": "12",
      "match": "all",
      "conditions": [
        {
          "field": null,
          "form_field": {
            "name": "country-field",
            "label": "Country"
          },
          "operation": "equals",
          "value": "Germany",
          "unit": null,
          "paid_orders_days": null
        },
        {
          "field": "customer_email",
          "form_field": null,
          "operation": "contains",
          "value": "@acme.de",
          "unit": null,
          "paid_orders_days": null
        }
      ],
      "actions": [
        {
          "type": "add_customer_tags",
          "value": "eu,wholesale"
        },
        {
          "type": "mark_tax_exempt",
          "value": null
        }
      ],
      "created_at": "2026-10-21T09:34:27.000Z",
      "updated_at": "2026-10-21T09:34:27.000Z"
    }
  ],
  "meta": {
    "timestamp": "2026-10-21T09:34:30.293Z",
    "version": "v2",
    "request_id": "8b50c4f6-c5fd-4a43-bfc6-5cdbf4b821d8",
    "rate_limit": {
      "cost": 10,
      "limit": 600,
      "remaining": 590,
      "restore_rate": 10
    },
    "pagination": {
      "limit": 2,
      "next_cursor": null,
      "prev_cursor": null,
      "links": {
        "self": "/api/v2/auto-tag/rules?limit=2&filter_name=Tag",
        "next": null,
        "prev": null
      }
    }
  }
}

Create a rule

POST/api/v2/auto-tag/rules

Scope auto-tag:writeCost 11

Create a rule.

The body of POST /rules, PUT /rules/{id} and each element of bulk-upsert (add id to replace a rule). PUT replaces the whole rule: optional fields left out go back to their defaults. Fields not listed here are refused with 422.

Arguments

namestringrequired

Rule name. 1–200 characters.

priorityintegerrequired

Lower number wins; see Rules. 0–99.

statusenumrequired

disabled rules are kept but not applied. One of disabled, enabled.

eventenumrequired

customer_created: A customer signs up through a registration form (form_id).
order_created, order_paid, order_fulfilled, order_cancelled: An order is placed, paid, fulfilled or cancelled.

form_idstring

The registration form the rule watches; required with customer_created, else left out. Numeric id as a string.

matchenumrequired

all conditions, or any one of them.

all, any: Every condition must match, or any one of them.

conditions[object]required

1–50 items.

Show fields

fieldenum

Leave out with form_field. One of customer_name, customer_email, customer_first_name, customer_last_name, customer_tags, customer_orders_count, customer_total_spent, shipping_city, shipping_country, shipping_province, shipping_postcode, billing_city, billing_country, billing_province, billing_postcode, default_address_city, default_address_country, default_address_province, default_address_postcode, product_name, product_sku, order_items_count, order_quantity, order_amount, paid_orders_amount, paid_orders_count, order_weight, paid_orders_weight.

form_fieldobject

A field of the registration form form_id; only with customer_created.

form_field.namestringrequired

The name (version 1) or id of the field in the form. Not empty.

form_field.labelstringrequired

Not empty.

operationenumrequired

One of contains, not_contains, equals, not_equals, greater_than, less_than, greater_than_or_equal, less_than_or_equal, starts_with.

valuestringrequired

A number for number fields and paid-order totals. 0–300 characters.

unitenum

Required with the weight fields, else left out. One of g, kg, lb, oz.

paid_orders_daysinteger

How many days back the paid-order totals count; required with them, else left out. 1–365.

actions[object]required

1–50 items.

Show fields

typeenumrequired

One of add_customer_tags, remove_customer_tags, add_customer_note, add_order_note, add_order_tags, remove_order_tags, mark_tax_exempt.

valuestring

Tags (comma-separated) or the note to add; left out with mark_tax_exempt. 1–300 characters.

Returns

dataRule

The new rule.

Request
Response

curl -X POST "https://solution-public-api.bss-b2b.solutions/api/v2/auto-tag/rules" \
  -H "X-API-Key: $B2B_API_KEY" \
  -H "X-Shop-Domain: your-store.myshopify.com" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Tag EU wholesalers",
  "priority": 1,
  "status": "disabled",
  "event": "customer_created",
  "form_id": "12",
  "match": "all",
  "conditions": [
    {
      "form_field": {
        "name": "country-field",
        "label": "Country"
      },
      "operation": "equals",
      "value": "Germany"
    },
    {
      "field": "customer_email",
      "operation": "contains",
      "value": "@acme.de"
    }
  ],
  "actions": [
    {
      "type": "add_customer_tags",
      "value": "eu,wholesale"
    },
    {
      "type": "mark_tax_exempt"
    }
  ]
}'

{
  "success": true,
  "status": "success",
  "data": {
    "id": "28",
    "name": "Tag EU wholesalers",
    "priority": 1,
    "status": "disabled",
    "event": "customer_created",
    "form_id": "12",
    "match": "all",
    "conditions": [
      {
        "field": null,
        "form_field": {
          "name": "country-field",
          "label": "Country"
        },
        "operation": "equals",
        "value": "Germany",
        "unit": null,
        "paid_orders_days": null
      },
      {
        "field": "customer_email",
        "form_field": null,
        "operation": "contains",
        "value": "@acme.de",
        "unit": null,
        "paid_orders_days": null
      }
    ],
    "actions": [
      {
        "type": "add_customer_tags",
        "value": "eu,wholesale"
      },
      {
        "type": "mark_tax_exempt",
        "value": null
      }
    ],
    "created_at": "2026-10-21T09:34:27.000Z",
    "updated_at": "2026-10-21T09:34:27.000Z"
  },
  "meta": {
    "timestamp": "2026-10-21T09:34:27.672Z",
    "version": "v2",
    "request_id": "bb6c1859-eb0d-45f5-ab56-a713d0344cd4",
    "rate_limit": {
      "cost": 11,
      "limit": 600,
      "remaining": 589,
      "restore_rate": 10
    }
  }
}

Get a rule

GET/api/v2/auto-tag/rules/{id}

Scope auto-tag:readCost 10

Get a rule.

Path parameters

idstringrequired

Rule id.

Returns

dataRule

The rule. An id that does not exist answers 404 RESOURCE_NOT_FOUND.

Request
Response

curl -X GET "https://solution-public-api.bss-b2b.solutions/api/v2/auto-tag/rules/28" \
  -H "X-API-Key: $B2B_API_KEY" \
  -H "X-Shop-Domain: your-store.myshopify.com"

{
  "success": true,
  "status": "success",
  "data": {
    "id": "28",
    "name": "Tag EU wholesalers",
    "priority": 1,
    "status": "disabled",
    "event": "customer_created",
    "form_id": "12",
    "match": "all",
    "conditions": [
      {
        "field": null,
        "form_field": {
          "name": "country-field",
          "label": "Country"
        },
        "operation": "equals",
        "value": "Germany",
        "unit": null,
        "paid_orders_days": null
      },
      {
        "field": "customer_email",
        "form_field": null,
        "operation": "contains",
        "value": "@acme.de",
        "unit": null,
        "paid_orders_days": null
      }
    ],
    "actions": [
      {
        "type": "add_customer_tags",
        "value": "eu,wholesale"
      },
      {
        "type": "mark_tax_exempt",
        "value": null
      }
    ],
    "created_at": "2026-10-21T09:34:27.000Z",
    "updated_at": "2026-10-21T09:34:27.000Z"
  },
  "meta": {
    "timestamp": "2026-10-21T09:34:28.979Z",
    "version": "v2",
    "request_id": "2a0516ed-0478-42e2-8d77-40d699374b43",
    "rate_limit": {
      "cost": 10,
      "limit": 600,
      "remaining": 590,
      "restore_rate": 10
    }
  }
}

Replace a rule

PUT/api/v2/auto-tag/rules/{id}

Scope auto-tag:writeCost 11

Replace a rule with all its conditions and actions.

Path parameters

idstringrequired

Rule id.

Arguments

The same fields as Create a rule.

Returns

dataRule

The rule after the change.

Request
Response

curl -X PUT "https://solution-public-api.bss-b2b.solutions/api/v2/auto-tag/rules/28" \
  -H "X-API-Key: $B2B_API_KEY" \
  -H "X-Shop-Domain: your-store.myshopify.com" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Tag EU wholesalers (updated)",
  "priority": 2,
  "status": "disabled",
  "event": "customer_created",
  "form_id": "12",
  "match": "all",
  "conditions": [
    {
      "form_field": {
        "name": "country-field",
        "label": "Country"
      },
      "operation": "equals",
      "value": "Germany"
    },
    {
      "field": "customer_email",
      "operation": "contains",
      "value": "@acme.de"
    }
  ],
  "actions": [
    {
      "type": "add_customer_tags",
      "value": "eu,wholesale"
    },
    {
      "type": "mark_tax_exempt"
    }
  ]
}'

{
  "success": true,
  "status": "success",
  "data": {
    "id": "28",
    "name": "Tag EU wholesalers (updated)",
    "priority": 2,
    "status": "disabled",
    "event": "customer_created",
    "form_id": "12",
    "match": "all",
    "conditions": [
      {
        "field": null,
        "form_field": {
          "name": "country-field",
          "label": "Country"
        },
        "operation": "equals",
        "value": "Germany",
        "unit": null,
        "paid_orders_days": null
      },
      {
        "field": "customer_email",
        "form_field": null,
        "operation": "contains",
        "value": "@acme.de",
        "unit": null,
        "paid_orders_days": null
      }
    ],
    "actions": [
      {
        "type": "add_customer_tags",
        "value": "eu,wholesale"
      },
      {
        "type": "mark_tax_exempt",
        "value": null
      }
    ],
    "created_at": "2026-10-21T09:34:27.000Z",
    "updated_at": "2026-10-21T09:34:31.000Z"
  },
  "meta": {
    "timestamp": "2026-10-21T09:34:31.613Z",
    "version": "v2",
    "request_id": "e4810b68-0346-4c7d-b5d6-395188e94c3b",
    "rate_limit": {
      "cost": 11,
      "limit": 600,
      "remaining": 589,
      "restore_rate": 10
    }
  }
}

Delete a rule

DEL/api/v2/auto-tag/rules/{id}

Scope auto-tag:writeCost 11

Delete a rule.

Path parameters

idstringrequired

Rule id.

Returns

data.idstring

Id of the deleted rule.

data.deletedboolean

true.

Request
Response

curl -X DELETE "https://solution-public-api.bss-b2b.solutions/api/v2/auto-tag/rules/28" \
  -H "X-API-Key: $B2B_API_KEY" \
  -H "X-Shop-Domain: your-store.myshopify.com"

{
  "success": true,
  "status": "success",
  "data": {
    "id": "28",
    "deleted": true
  },
  "meta": {
    "timestamp": "2026-10-21T09:34:35.560Z",
    "version": "v2",
    "request_id": "696520ea-21cc-41fe-8b14-5b72a8955142",
    "rate_limit": {
      "cost": 11,
      "limit": 600,
      "remaining": 589,
      "restore_rate": 10
    }
  }
}

Create or replace rules in bulk

POST/api/v2/auto-tag/rules/bulk-upsert

Scope auto-tag:writeCost ceil(10 + 0.4 × rules)

Create or replace up to 250 rules; each one succeeds or fails on its own.

See Bulk & idempotency.

Arguments

rules[object]required

1–250 rules, each with the fields of Create a rule.

Show fields

idstring

Set it to replace that rule, as Replace a rule does; leave it out to create one.

Returns

data.results[object]

One entry per rule, in the order sent.

Show fields

indexinteger

Position of the rule in rules.

idstring

Rule id.

resultenum

created, updated or error.

errorobject

code and message, only when result is error.

data.summaryobject

total, succeeded, failed.

Request
Response

curl -X POST "https://solution-public-api.bss-b2b.solutions/api/v2/auto-tag/rules/bulk-upsert" \
  -H "X-API-Key: $B2B_API_KEY" \
  -H "X-Shop-Domain: your-store.myshopify.com" \
  -H "Content-Type: application/json" \
  -d '{
  "rules": [
    {
      "name": "Tag EU wholesalers B",
      "priority": 1,
      "status": "disabled",
      "event": "customer_created",
      "form_id": "12",
      "match": "all",
      "conditions": [
        {
          "form_field": {
            "name": "country-field",
            "label": "Country"
          },
          "operation": "equals",
          "value": "Germany"
        },
        {
          "field": "customer_email",
          "operation": "contains",
          "value": "@acme.de"
        }
      ],
      "actions": [
        {
          "type": "add_customer_tags",
          "value": "eu,wholesale"
        },
        {
          "type": "mark_tax_exempt"
        }
      ]
    },
    {
      "name": "Tag EU wholesalers (bulk)",
      "priority": 1,
      "status": "disabled",
      "event": "customer_created",
      "form_id": "12",
      "match": "all",
      "conditions": [
        {
          "form_field": {
            "name": "country-field",
            "label": "Country"
          },
          "operation": "equals",
          "value": "Germany"
        },
        {
          "field": "customer_email",
          "operation": "contains",
          "value": "@acme.de"
        }
      ],
      "actions": [
        {
          "type": "add_customer_tags",
          "value": "eu,wholesale"
        },
        {
          "type": "mark_tax_exempt"
        }
      ],
      "id": "28"
    }
  ]
}'

{
  "success": true,
  "status": "success",
  "data": {
    "results": [
      {
        "index": 0,
        "id": "29",
        "result": "created"
      },
      {
        "index": 1,
        "id": "28",
        "result": "updated"
      }
    ],
    "summary": {
      "total": 2,
      "succeeded": 2,
      "failed": 0
    }
  },
  "meta": {
    "timestamp": "2026-10-21T09:34:32.941Z",
    "version": "v2",
    "request_id": "040db577-3e9b-497e-a17f-1b7262e9c797",
    "rate_limit": {
      "cost": 11,
      "limit": 600,
      "remaining": 589,
      "restore_rate": 10
    }
  }
}

Delete rules in bulk

POST/api/v2/auto-tag/rules/bulk-delete

Scope auto-tag:writeCost ceil(10 + 0.4 × rules)

Delete up to 250 rules; an unknown id fails on its own.

See Bulk & idempotency.

Arguments

ids[string]required

1–250 rule ids.

Returns

data.results[object]

One entry per id: index, id, result (deleted or error) and error (code, message) when it failed.

data.summaryobject

total, succeeded, failed.

Request
Response

curl -X POST "https://solution-public-api.bss-b2b.solutions/api/v2/auto-tag/rules/bulk-delete" \
  -H "X-API-Key: $B2B_API_KEY" \
  -H "X-Shop-Domain: your-store.myshopify.com" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "29",
    "999999999"
  ]
}'

{
  "success": true,
  "status": "success",
  "data": {
    "results": [
      {
        "index": 0,
        "id": "29",
        "result": "deleted"
      },
      {
        "index": 1,
        "id": "999999999",
        "result": "error",
        "error": {
          "code": "RESOURCE_NOT_FOUND",
          "message": "Resource not found"
        }
      }
    ],
    "summary": {
      "total": 2,
      "succeeded": 1,
      "failed": 1
    }
  },
  "meta": {
    "timestamp": "2026-10-21T09:34:34.251Z",
    "version": "v2",
    "request_id": "44ec14fa-d9e7-4a88-8802-4d04bdfd570f",
    "rate_limit": {
      "cost": 11,
      "limit": 600,
      "remaining": 589,
      "restore_rate": 10
    }
  }
}