Customers: Hierarchy & Groups · Innovorder API Documentation

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

[
  {
    "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 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

classCorresponds to Depth 0 (Group / Company).
sectionCorresponds to Depth 1 (Section / Service).
subSectionCorresponds to Depth 2 (Sub-Section / Team).
guestGroupIdThe 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.