Company group ( company_group )

A company_group is a logical grouping of companies . It lets you apply shared policies — shared credit limit, compliance rule, pricing segment — to a set of companies without duplicating configuration on each company.

Role

The group has no fixed business semantics: it is a named container whose use is defined by your processes. Common examples:

Grands comptes — companies benefiting from a higher credit limit or extended payment terms.
Strategic partners — suppliers eligible for priority financing programs.
Watchlist — companies subject to enhanced compliance monitoring.
Segment tarifaire — buyers subject to specific commercial terms.

The relationship is many-to-many: one company may belong to several groups, and one group may contain any number of companies.

Identifier and structure

Each group has a stable identifier prefixed with cgp_. Its structure is deliberately minimal — business data lives on companies and processes, not on the group itself.

JSON

"company_group":{8 items"object":"company_group"
"id":"cgp_7fa1b2c3d4e5f6a7"
"name":"Large Accounts FR"
"description":"Buyers with a credit limit above EUR 500k"
"source_reference":"SEGMENT-GC-FR"
"metadata":{}0 items
"created_at":"2026-01-08T09:00:00.000Z"
"updated_at":"2026-01-08T09:00:00.000Z"
}

{
"object": "company_group",
"id": "cgp_7fa1b2c3d4e5f6a7",
"name": "Large Accounts FR",
"description": "Buyers with a credit limit above EUR 500k",
"source_reference": "SEGMENT-GC-FR",
"metadata": {},
"created_at": "2026-01-08T09:00:00.000Z",
"updated_at": "2026-01-08T09:00:00.000Z"
}

Fields

Field	Type	Required	Description
`id`	`string`	yes	Group identifier (prefix `cgp_`).
`object`	`string`	yes	Always "company_group".
`merchant_id`	`string`	yes	Merchant owning the group.
`name`	`string`	yes	Free-form group name.
`description`	`string`	no	Optional description.
`source_reference`	`string`	no	Reference in your system.
`metadata`	`object`	no	Flat map of `string \| number \| boolean` scalars, following the API metadata convention.
`created_at`	`datetime`	yes	Creation date.
`updated_at`	`datetime`	yes	Last update date.

Member management

Membership can be managed from either side of the relationship, whichever is more convenient.

From the group

Endpoint	Effet
`GET /v1/company-groups/:id/companies`	Paginated list of member companies (summary: `id`, `display_name`, `suspended`).
`POST /v1/company-groups/:id/company-links`	Atomically replaces the complete member list. Send `{ "company_ids": ["cmp_…", …] }`. Companies absent from the list are removed; new ones are added.
`DELETE /v1/company-groups/:id/company-links/:company_id`	Removes one company from the group without affecting others.

From the company

Endpoint	Effet
`GET /v1/companies/:id/company-groups`	List of groups to which the company belongs.
`POST /v1/companies/:id/company-group-links`	Atomically replaces the complete set of groups for the company. Send `{ "company_group_ids": ["cgp_…", …] }`.
`DELETE /v1/companies/:id/company-group-links/:company_group_id`	Removes the company from one group without affecting others.

Both replacement operations (company-links) are atomic and differential: only actual changes trigger events. Adding an existing member or removing an absent company is silent.

HTTP

POST /v1/company-groups/cgp_7fa1/company-links

{1 item"company_ids":[3 items0:"cmp_3a8f"
1:"cmp_4b9e"
2:"cmp_5c0f"
]
}

{
"company_ids": ["cmp_3a8f", "cmp_4b9e", "cmp_5c0f"]
}

Each change relative to the previous state emits an event company.assigned_to_group or company.removed_from_group.

To filter the company list by group when calling GET /v1/companies, use the parameter group_id :

HTTP

GET /v1/companies?group_id=cgp_7fa1

Deletion

A group can be deleted only when it contains no company. Attempting to delete a group with members returns an error 409 :

HTTP

DELETE /v1/company-groups/cgp_7fa1
409 Conflict

{1 item"error":{1 item"message":"Cannot delete a group that still has companies assigned to it"
}
}

{
"error": {
  "message": "Cannot delete a group that still has companies assigned to it"
}
}

To delete a non-empty group, empty it first through POST /v1/company-groups/:id/company-links with { "company_ids": [] }, then delete it.

In processes

The node check_company_group_membership checks whether a company belongs to a given group and routes the process accordingly:

Node	Role	Key inputs / outputs
`check_company_group_membership`	Checks company membership in a group and routes accordingly	Accepts: company, company_group_id · Route `in_group` / `not_in_group` · Produces: `is_member`

This node is typically used to apply differentiated rules by company segment: automatic approval for trusted-group members, enhanced verification for companies under monitoring, special credit terms for large accounts.

Events

The group emits its own lifecycle events, and every membership change produces an event on the company concerned.

Event	Trigger
`company_group.created`	The group was just created.
`company_group.updated`	The group was updated (name, description…).
`company_group.deleted`	The group was deleted.
`company.assigned_to_group`	A company was added to the group.
`company.removed_from_group`	A company was removed from the group.

Membership events (company.assigned_to_group and company.removed_from_group) have the following payload:

JSON

{2 items"company_id":"cmp_3a8f…"
"company_group_id":"cgp_7fa1…"
}

{
"company_id": "cmp_3a8f…",
"company_group_id": "cgp_7fa1…"
}

For an atomic replacement affecting multiple companies, one separate event is emitted per actual change — not one grouped event.

← PreviousContact role Next →Checkout session