Group-Specific Fields

Makaira supports customer group-specific field overrides for B2B scenarios, multi-channel setups, and personalized pricing.

Target location: This content could be added as a new section under Use Cases or as part of a B2B documentation section.

Overview

Any field can have a group-specific override using the pattern:

groups.<groupname>.<fieldname>

When a GROUP constraint is set in the API request, Makaira checks for group-specific values first.

How It Works

1. Customer makes a request with GROUP constraint
2. Makaira checks if groups.<group>.<field> exists
3. If yes, uses the group-specific value
4. If no, falls back to the root field value

Commonly Overridden Fields

Import Example

{
  "id": "product-001",
  "type": "product",
  "active": true,
  "onstock": true,
  "price": 99.99,
  "stock": 100,
  "groups": {
    "wholesale": {
      "active": true,
      "onstock": true,
      "price": 79.99,
      "stock": 1000,
      "hideOnLists": false
    },
    "retail": {
      "active": true,
      "onstock": true,
      "price": 99.99,
      "stock": 50
    },
    "vip": {
      "active": true,
      "price": 69.99,
      "hideOnLists": false
    },
    "internal": {
      "active": false
    }
  }
}

API Request with Group

To use group-specific values, include the GROUP constraint:

{
  "searchPhrase": "t-shirt",
  "isSearch": true,
  "constraints": {
    "query.shop_id": "shop1",
    "query.language": "de",
    "query.group": "wholesale"
  }
}

Use Cases

B2B Pricing

Different prices for different customer tiers:

{
  "id": "product-001",
  "price": 99.99,
  "groups": {
    "wholesale": {"price": 79.99},
    "distributor": {"price": 59.99},
    "retail": {"price": 99.99}
  }
}

Group-Specific Visibility

Hide products from certain groups:

{
  "id": "product-001",
  "active": true,
  "groups": {
    "consumer": {"active": true},
    "b2b_only": {"active": true},
    "internal": {"active": false}
  }
}

Group-Specific Stock

Different stock pools per channel:

{
  "id": "product-001",
  "stock": 100,
  "onstock": true,
  "groups": {
    "online": {"stock": 50, "onstock": true},
    "store_pickup": {"stock": 25, "onstock": true},
    "wholesale": {"stock": 500, "onstock": true}
  }
}

Regional Availability

Products available only in certain regions:

{
  "id": "product-001",
  "active": true,
  "groups": {
    "de": {"active": true},
    "at": {"active": true},
    "ch": {"active": false}
  }
}

Visibility Filter Logic

When a group is set, visibility filters check both the root field AND the group override:

Logic for active field:

1. Check root active field
2. If groups.<group>.active exists, it overrides the root value
3. Product is visible only if the effective active value is true

Example:

Root: active = true
Group "wholesale": active = false
→ Product is HIDDEN for wholesale customers

Stock Ranking with Groups

When "Out of stock at the end" is enabled in Ranking Mix:

1. Makaira checks for groups.<group>.stock
2. If exists, uses group-specific stock for ranking
3. If not, falls back to root stock field

{
  "id": "product-001",
  "stock": 100,
  "groups": {
    "wholesale": {"stock": 0}
  }
}

For wholesale customers, this product would be pushed to the bottom of results (stock = 0).

Custom Group Fields

You can add any custom field as a group override:

{
  "id": "product-001",
  "delivery_days_int": 3,
  "min_order_quantity_int": 1,
  "groups": {
    "wholesale": {
      "delivery_days_int": 1,
      "min_order_quantity_int": 10
    },
    "dropship": {
      "delivery_days_int": 5,
      "min_order_quantity_int": 1
    }
  }
}

Best Practices

1. Define all groups consistently - Use the same group names across all products.

2. Set defaults at root level - Always provide root field values as fallback.

3. Only override what changes - Don't duplicate values that are the same as root.

4. Document your groups - Maintain a list of group names and their purposes.

5. Test group visibility - Verify that group-specific filtering works as expected.

Limitations

• Group names are case-sensitive
• Group fields must match the type of the root field
• Not all fields support group overrides (check specific documentation)
• Group overrides are only applied when GROUP constraint is set