# Hierarchy & Groups

In Corporate Catering (Canteen) contexts, customers are often organized into a strict hierarchy to manage subsidies, reporting, and access rights.

#### Organizational Mapping

Depth 0

Group

Mapped to field `class`.

Depth 1

Section

Mapped to field `section`.

Depth 2

Sub-Section

Mapped to field `subSection`.

### Retrieving the Hierarchy

To place a customer in the correct organizational unit, you must traverse the guest group tree.

#### 1\. Traverse by Depth

### `GET /guest_groups` - Get Guest Groups

Navigate the organizational tree by increasing the \`depth\`.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| brandId | integer | Yes | Brand ID |
| depth | integer | Yes | 0 for Company, 1 for Service, 2 for Sub-service. |
| parentGuestGroupId | integer | No | Required when querying depth > 0 to filter children of a specific group. |

#### Response

```json
[
  {
    "guestGroupId": 7787,
    "name": "Morning Beaurepaire",
    "depth": 0,
    "guestsCount": 1
  },
  {
    "guestGroupId": 687,
    "name": "DFR",
    "depth": 0,
    "guestsCount": 0
  }
]
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| \[\] | object | {…} | Object containing fields. |
| \[\].guestGroupId | integer | 7787 | Identifier of the associated guest group. |
| \[\].name | string | "Morning Beaurepaire" | The name value. |
| \[\].depth | integer | 0 | The depth value. |
| \[\].guestsCount | integer | 1 | The guests count value. |

Example: Drilling down to Depth 1 (Services)

**GET /guest_groups?brandId=496&depth=1&parentGuestGroupId=687**

```bash
[
  {
    "guestGroupId": 691,
    "name": "DFR Externe",
    "parentGuestGroupId": 687,
    "depth": 1
  },
  {
    "guestGroupId": 690,
    "name": "DFR Partenaire",
    "parentGuestGroupId": 687,
    "depth": 1
  }
]
```

#### 2\. Flattened View

Alternatively, retrieve a flattened list of all active entities and their tree structure in a single call.

### `GET /brands/{brandId}/active_students_entities` - Get Active Entities

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| brandId | integer | Yes | Brand ID |

#### Response

```json
{
  "status": 200,
  "code": "students_entities_found",
  "message": "Student entities found",
  "data": {
    "sections": [
      "Operations",
      "SALES",
      "DFR Partenaire"
    ],
    "subSections": [
      "POST PAIEMENT",
      "DFR RHL Admin"
    ],
    "classes": [
      "Innovorder Operations",
      "DFR"
    ],
    "entities": [
      {
        "name": "Innovorder Operations",
        "children": [
          {
            "name": "Operations",
            "children": []
          }
        ]
      }
    ]
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "students\_entities\_found" | Machine-readable application code for the result. |
| message | string | "Student entities found" | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.sections | array | \[…\] | List of sections entries. |
| data.sections\[\] | string | "Operations" | The sections value. |
| data.subSections | array | \[…\] | List of sub sections entries. |
| data.subSections\[\] | string | "POST PAIEMENT" | The sub sections value. |
| data.classes | array | \[…\] | List of classes entries. |
| data.classes\[\] | string | "Innovorder Operations" | The classes value. |
| data.entities | array | \[…\] | List of entities entries. |
| data.entities\[\] | object | {…} | Object containing entities fields. |
| data.entities\[\].name | string | "Innovorder Operations" | The name value. |
| data.entities\[\].children | array | \[…\] | List of children entries. |
| data.entities\[\].children\[\] | object | {…} | Object containing children fields. |
| data.entities\[\].children\[\].name | string | "Operations" | The name value. |
| data.entities\[\].children\[\].children | array | \[\] | List of children entries. |

#### 3\. Get Pricing Rules

Once you have the target `guestGroupId` (the deepest level, e.g., the subsection), you must retrieve the valid pricing rules for that group. The `guestGroupId` filter is optional on the API side, but required in this flow to scope the rules to the selected group. See the [Pricing Rules](https://developers.innovorder.io/docs/promotions-and-pricing/pricing-rules.md) section for the complete endpoint reference.

### `GET /pricing_rules` - Get Pricing Rules

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| brandId | integer | Yes | Brand ID |
| guestGroupId | integer | No | Guest group filter. Optional for the API, but pass the ID of the group selected above to scope the rules in this flow. |

#### Response

```json
{
  "status": 200,
  "code": "pricing_rules_found",
  "message": "Pricing rules found.",
  "data": [
    {
      "pricingRuleId": 11469,
      "code": "DFR RHL RH",
      "applyScope": [
        "FEE",
        "PRODUCT"
      ],
      "entranceFees": [
        {
          "entranceFeeId": 3018,
          "code": "ADM DFR",
          "amount": 400
        }
      ]
    }
  ]
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "pricing\_rules\_found" | Machine-readable application code for the result. |
| message | string | "Pricing rules found." | Human-readable result message. Do not use this value for program logic. |
| data | array | \[…\] | Endpoint-specific response payload. |
| data\[\] | object | {…} | Endpoint-specific response payload. |
| data\[\].pricingRuleId | integer | 11469 | Identifier of the associated pricing rule. |
| data\[\].code | string | "DFR RHL RH" | Machine-readable application code for the result. |
| data\[\].applyScope | array | \[…\] | List of apply scope entries. |
| data\[\].applyScope\[\] | string | "FEE" | The apply scope value. |
| data\[\].entranceFees | array | \[…\] | List of entrance fees entries. |
| data\[\].entranceFees\[\] | object | {…} | Object containing entrance fees fields. |
| data\[\].entranceFees\[\].entranceFeeId | integer | 3018 | Identifier of the associated entrance fee. |
| data\[\].entranceFees\[\].code | string | "ADM DFR" | Machine-readable application code for the result. |
| data\[\].entranceFees\[\].amount | integer | 400 | The amount value. |

### Creating Hierarchy

The creation and management of Companies, Services, and Sub-services are typically handled via the **Innovorder Backoffice** to ensure structural integrity. However, if your integration requires programmatic creation of these entities, please contact your account manager to enable the administrative endpoints for \`POST /guest\_groups\`.

### Reading Hierarchy from Customer Data

When retrieving customer profiles, the hierarchy they belong to is flattened into specific fields within the response.

#### Field Mapping

-   `class` Corresponds to **Depth 0** (Group / Company). 
-   `section` Corresponds to **Depth 1** (Section / Service). 
-   `subSection` Corresponds to **Depth 2** (Sub-Section / Team). 
-   `guestGroupId` The unique identifier of the leaf node in the hierarchy tree. 

### Guest Groups (CRUD)

Manage guest groups programmatically. Guest groups form the organizational hierarchy (Company, Service, Sub-service) used in corporate catering contexts.

### `GET /guest_groups/{groupId}` - Get Guest Group by ID

Retrieve a single guest group by its unique identifier.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| groupId | integer | Yes | The unique identifier of the guest group. |

#### Response

```json
{
  "status": 200,
  "code": "guest_groups_succeed",
  "message": "Guest group retrieved.",
  "data": {
    "guestGroupId": 687,
    "name": "DFR",
    "depth": 0,
    "parentGuestGroupId": null,
    "brandId": 496,
    "pricingRules": [
      {
        "pricingRuleId": 11469,
        "code": "DFR RHL RH"
      }
    ]
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "guest\_groups\_succeed" | Machine-readable application code for the result. |
| message | string | "Guest group retrieved." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.guestGroupId | integer | 687 | Identifier of the associated guest group. |
| data.name | string | "DFR" | The name value. |
| data.depth | integer | 0 | The depth value. |
| data.parentGuestGroupId | null | null | Identifier of the associated parent guest group. |
| data.brandId | integer | 496 | Identifier of the brand. |
| data.pricingRules | array | \[…\] | List of pricing rules entries. |
| data.pricingRules\[\] | object | {…} | Object containing pricing rules fields. |
| data.pricingRules\[\].pricingRuleId | integer | 11469 | Identifier of the associated pricing rule. |
| data.pricingRules\[\].code | string | "DFR RHL RH" | Machine-readable application code for the result. |

### `POST /guest_groups` - Create Guest Group

Create a new guest group within a brand. Optionally specify a parent group to create nested hierarchy levels.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| brandId | integer | Yes | The brand ID. |

#### Request Body

```json
{
  "name": "Engineering",
  "pricingRules": [
    11469
  ],
  "parentGuestGroupId": 687,
  "depth": 1
}
```

##### Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| name | string | "Engineering" | The name value. |
| pricingRules | array | \[…\] | List of pricing rules entries. |
| pricingRules\[\] | integer | 11469 | The pricing rules value. |
| parentGuestGroupId | integer | 687 | Identifier of the associated parent guest group. |
| depth | integer | 1 | The depth value. |

#### Response

```json
{
  "status": 200,
  "code": "guest_group_created_successfully",
  "message": "Guest group created.",
  "data": {
    "guestGroupId": 8001,
    "name": "Engineering",
    "depth": 1,
    "parentGuestGroupId": 687,
    "brandId": 496,
    "pricingRules": [
      {
        "pricingRuleId": 11469,
        "code": "DFR RHL RH"
      }
    ]
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "guest\_group\_created\_successfully" | Machine-readable application code for the result. |
| message | string | "Guest group created." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.guestGroupId | integer | 8001 | Identifier of the associated guest group. |
| data.name | string | "Engineering" | The name value. |
| data.depth | integer | 1 | The depth value. |
| data.parentGuestGroupId | integer | 687 | Identifier of the associated parent guest group. |
| data.brandId | integer | 496 | Identifier of the brand. |
| data.pricingRules | array | \[…\] | List of pricing rules entries. |
| data.pricingRules\[\] | object | {…} | Object containing pricing rules fields. |
| data.pricingRules\[\].pricingRuleId | integer | 11469 | Identifier of the associated pricing rule. |
| data.pricingRules\[\].code | string | "DFR RHL RH" | Machine-readable application code for the result. |

### `PUT /guest_groups` - Update Guest Group

Update an existing guest group. The group to update is specified via query parameter.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| groupId | integer | Yes | The ID of the guest group to update (query parameter). |

#### Request Body

```json
{
  "name": "Engineering - Updated",
  "pricingRules": [
    11469,
    11470
  ]
}
```

##### Request Body Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| name | string | "Engineering - Updated" | The name value. |
| pricingRules | array | \[…\] | List of pricing rules entries. |
| pricingRules\[\] | integer | 11469 | The pricing rules value. |

#### Response

```json
{
  "status": 200,
  "code": "guest_group_updated_successfully",
  "message": "Guest group updated.",
  "data": {
    "guestGroupId": 8001,
    "name": "Engineering - Updated",
    "depth": 1,
    "parentGuestGroupId": 687,
    "brandId": 496,
    "pricingRules": [
      {
        "pricingRuleId": 11469,
        "code": "DFR RHL RH"
      },
      {
        "pricingRuleId": 11470,
        "code": "DFR INVITE"
      }
    ]
  }
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "guest\_group\_updated\_successfully" | Machine-readable application code for the result. |
| message | string | "Guest group updated." | Human-readable result message. Do not use this value for program logic. |
| data | object | {…} | Endpoint-specific response payload. |
| data.guestGroupId | integer | 8001 | Identifier of the associated guest group. |
| data.name | string | "Engineering - Updated" | The name value. |
| data.depth | integer | 1 | The depth value. |
| data.parentGuestGroupId | integer | 687 | Identifier of the associated parent guest group. |
| data.brandId | integer | 496 | Identifier of the brand. |
| data.pricingRules | array | \[…\] | List of pricing rules entries. |
| data.pricingRules\[\] | object | {…} | Object containing pricing rules fields. |
| data.pricingRules\[\].pricingRuleId | integer | 11469 | Identifier of the associated pricing rule. |
| data.pricingRules\[\].code | string | "DFR RHL RH" | Machine-readable application code for the result. |

### `DELETE /guest_groups` - Delete Guest Group

Delete a guest group by its ID. The group ID is passed as a query parameter.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| groupId | integer | Yes | The ID of the guest group to delete (query parameter). |

#### Response

```json
{
  "status": 200,
  "code": "guest_group_deleted_successfully",
  "message": "Guest group deleted."
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "guest\_group\_deleted\_successfully" | Machine-readable application code for the result. |
| message | string | "Guest group deleted." | Human-readable result message. Do not use this value for program logic. |

* * *

#### Import Guest Groups

Bulk import guest groups from a file. The endpoint accepts a file upload in multipart/form-data format.

### `POST /guest_groups/import` - Import Guest Groups

Upload a file to bulk import guest groups for a brand. Returns the created groups or error details if the import fails.

#### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| brandId | integer | Yes | The brand ID to import guest groups into. |

#### Request Body

```json
multipart/form-data with a 'file' field containing the import file.
```

#### Response

```json
{
  "status": 200,
  "code": "guest_groups_imported",
  "message": "Guest groups imported successfully.",
  "data": [
    {
      "guestGroupId": 8002,
      "name": "Marketing",
      "depth": 1,
      "parentGuestGroupId": 687,
      "brandId": 496
    },
    {
      "guestGroupId": 8003,
      "name": "Sales",
      "depth": 1,
      "parentGuestGroupId": 687,
      "brandId": 496
    }
  ]
}
```

##### Response Properties

Every field in the example is listed below. Explicit requiredness is shown when the endpoint contract defines it.

| Property | Type | Example | Description |
| --- | --- | --- | --- |
| status | integer | 200 | HTTP status code returned by the API. |
| code | string | "guest\_groups\_imported" | Machine-readable application code for the result. |
| message | string | "Guest groups imported successfully." | Human-readable result message. Do not use this value for program logic. |
| data | array | \[…\] | Endpoint-specific response payload. |
| data\[\] | object | {…} | Endpoint-specific response payload. |
| data\[\].guestGroupId | integer | 8002 | Identifier of the associated guest group. |
| data\[\].name | string | "Marketing" | The name value. |
| data\[\].depth | integer | 1 | The depth value. |
| data\[\].parentGuestGroupId | integer | 687 | Identifier of the associated parent guest group. |
| data\[\].brandId | integer | 496 | Identifier of the brand. |