Tags & Routing
Developer Guide
What are tags?
Tags are short string labels attached to cart line items. When a rate request reaches the ShipRateAPI API, the tags on each item are used to match carrier routing rules configured in the admin portal — for example, restricting certain carriers to items tagged cold-storage, or requiring a hazmat surcharge for items tagged dangerous-goods.
Tags are per-item, not per-cart. A cart containing both a standard item and a fragile item will have routing rules evaluated independently for each, and the resulting set of available carriers reflects the union of all constraints.
How tags are set — per platform
| Platform | Method |
|---|---|
| Magento 2 | Layer 1: shiprate_tags product attribute (comma-separated)Layer 2: Admin attribute mapping rules — map any EAV attribute value to a tag |
| Shopify | Native Shopify product Tags field — ShipRateAPI-recognised tags are forwarded automatically |
| BigCommerce | Product Custom Field named shiprate_tags with a comma-separated value |
| Custom / REST | Pass tags directly in the items[].tags array of the API payload |
Magento 2 — attribute mapping rules
The attribute mapping table (under Stores → Configuration → Shipping Methods → ShipRateAPI → Attribute Tag Mapping) lets you derive tags from existing product attributes without touching each product. This is useful when you already have structured data in attributes such as hazmat_class, temperature_zone, or product_category_code.
Example rules:
| Attribute Code | Operator | Value | Tag applied |
|---|---|---|---|
temperature_zone | equals | chilled | cold-storage |
hazmat_class | not equals | (empty) | dangerous-goods |
product_name | contains | glass | fragile |
Attribute codes are validated against the Magento EAV catalog when you save the config. Rules with an invalid attribute code are rejected with a descriptive error before the config is persisted. At runtime, if an attribute cannot be read (e.g. it was deleted after the config was saved), the rule is skipped with a warning logged — the checkout flow is not interrupted.
Tags in the API payload
Tags appear in the items[].tags array. Duplicates are removed and empty strings are filtered before the payload is sent. A product with no tags sends an empty array.
"items": [
{
"sku": "CHILLED-001",
"name": "Organic Milk 2L",
"qty": 1,
"price": 1.80,
"weight": 2.1,
"tags": ["cold-storage", "perishable"]
},
{
"sku": "STANDARD-002",
"name": "Reusable Bag",
"qty": 2,
"price": 0.99,
"weight": 0.05,
"tags": []
}
]Configuring routing rules in the portal
Once tags are flowing in the API payload, use the ShipRateAPI admin portal to create carrier routing rules that reference them. Navigate to Shipping Rules → Tag Rules to restrict carriers, apply surcharges, or set delivery windows based on which tags are present in a cart. Rules are evaluated in priority order and can be combined with zone and weight conditions.