Subsidiaries API

This guide covers the API endpoints for managing subsidiaries in the Revenue Recognition System. Subsidiaries represent distinct business units within an organization and are used to track financial information separately for different parts of the business.

Subsidiaries can be organized in hierarchical relationships, allowing for a parent-child structure that matches your organizational needs.

Schema

Field	Type	Description	Required
id	UUID	Unique identifier (system-generated)	Read-only
organizationId	UUID	Organization this subsidiary belongs to	Read-only
name	String	Name of the subsidiary	Yes
code	String	Unique code for the subsidiary	Yes
description	String	Optional description	No
parentId	UUID	Parent subsidiary (for hierarchical structures)	No
isActive	Boolean	Whether the subsidiary is active (default: true)	No
createdAt	DateTime	When the record was created	Read-only
updatedAt	DateTime	When the record was last updated	Read-only

Authentication

All subsidiary API endpoints require authentication with a valid session. The session must include an organization context, which determines which subsidiaries are visible and modifiable. Organization context is provided through the x-stytch-organization-id header.

Endpoints

Create Subsidiary

Create a new subsidiary within your organization.

Name
Endpoint
Type
POST /api/v1/subsidiaries
Description
Name
Content-Type
Type
application/json
Description

Request Body

Name
name
Type
string
Required
Description
Name of the subsidiary
Name
code
Type
string
Required
Description
Unique code for the subsidiary within your organization
Name
description
Type
string
Description
Optional description of the subsidiary
Name
parentId
Type
string (UUID)
Description
ID of the parent subsidiary, if this is a child subsidiary
Name
isActive
Type
boolean
Description
Whether the subsidiary is active

Request

curl -X POST https://api.example.com/api/v1/subsidiaries \
  -H "Content-Type: application/json" \
  -H "x-stytch-organization-id: ba3b8cdf-efc1-4a60-88be-ac203d263fe2" \
  -d '{
    "name": "West Coast Operations",
    "code": "WCO",
    "description": "Subsidiary handling west coast sales and operations",
    "isActive": true
  }'

Response

{
  "subsidiary": {
    "id": "f67f0ea2-77bd-4578-8c76-0116d473cc27",
    "organizationId": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
    "name": "West Coast Operations",
    "code": "WCO",
    "description": "Subsidiary handling west coast sales and operations",
    "parentId": null,
    "isActive": true,
    "createdAt": "2025-05-11T12:33:59.048Z",
    "updatedAt": "2025-05-11T12:33:59.048Z"
  }
}

List Subsidiaries

Retrieve a paginated list of subsidiaries in your organization.

Name
Endpoint
Type
GET /api/v1/subsidiaries
Description

Query Parameters

Name
page
Type
number
Description
Page number for pagination
Name
limit
Type
number
Description
Number of items per page (max: 100)
Name
orderBy
Type
string
Description
Field to sort by (name, code, createdAt)
Name
orderDirection
Type
string
Description
Sort direction (asc, desc)
Name
isActive
Type
boolean
Description
Filter by active status
Name
parentId
Type
string (UUID)
Description
Filter by parent subsidiary (use "null" for top-level subsidiaries)

Request

curl -X GET "https://api.example.com/api/v1/subsidiaries?page=1&limit=10&isActive=true" \
  -H "x-stytch-organization-id: ba3b8cdf-efc1-4a60-88be-ac203d263fe2"

Response

{
  "data": [
    {
      "id": "f67f0ea2-77bd-4578-8c76-0116d473cc27",
      "organizationId": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
      "name": "West Coast Operations",
      "code": "WCO",
      "description": "Subsidiary handling west coast sales and operations",
      "parentId": null,
      "isActive": true,
      "createdAt": "2025-05-11T12:33:59.048Z",
      "updatedAt": "2025-05-11T12:33:59.048Z"
    },
    {
      "id": "a23c7de4-9821-4f56-9ab3-0c245b88e129",
      "organizationId": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
      "name": "East Coast Division",
      "code": "ECD",
      "description": "East coast sales and support",
      "parentId": null,
      "isActive": true,
      "createdAt": "2025-05-10T15:22:31.452Z",
      "updatedAt": "2025-05-10T15:22:31.452Z"
    }
  ],
  "total": 8,
  "page": 1,
  "limit": 10,
  "totalPages": 1
}

Get Subsidiary

Retrieve a specific subsidiary by ID.

Name
Endpoint
Type
GET /api/v1/subsidiaries/{id}
Description

Path Parameters

Name
id
Type
string (UUID)
Required
Description
ID of the subsidiary to retrieve

Request

curl -X GET https://api.example.com/api/v1/subsidiaries/f67f0ea2-77bd-4578-8c76-0116d473cc27 \
  -H "x-stytch-organization-id: ba3b8cdf-efc1-4a60-88be-ac203d263fe2"

Response

{
  "subsidiary": {
    "id": "f67f0ea2-77bd-4578-8c76-0116d473cc27",
    "organizationId": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
    "name": "West Coast Operations",
    "code": "WCO",
    "description": "Subsidiary handling west coast sales and operations",
    "parentId": null,
    "isActive": true,
    "createdAt": "2025-05-11T12:33:59.048Z",
    "updatedAt": "2025-05-11T12:33:59.048Z"
  }
}

Update Subsidiary

Update an existing subsidiary.

Name
Endpoint
Type
PUT /api/v1/subsidiaries/{id}
Description
Name
Content-Type
Type
application/json
Description

Path Parameters

Name
id
Type
string (UUID)
Required
Description
ID of the subsidiary to update

Request Body

Name
name
Type
string
Description
Name of the subsidiary
Name
code
Type
string
Description
Unique code for the subsidiary
Name
description
Type
string
Description
Description of the subsidiary
Name
parentId
Type
string (UUID) | null
Description
ID of the parent subsidiary, or null to make it a top-level subsidiary
Name
isActive
Type
boolean
Description
Whether the subsidiary is active

Request

curl -X PUT https://api.example.com/api/v1/subsidiaries/f67f0ea2-77bd-4578-8c76-0116d473cc27 \
  -H "Content-Type: application/json" \
  -H "x-stytch-organization-id: ba3b8cdf-efc1-4a60-88be-ac203d263fe2" \
  -d '{
    "name": "West Coast Operations Division",
    "description": "Updated description for west coast operations",
    "isActive": true
  }'

Response

{
  "subsidiary": {
    "id": "f67f0ea2-77bd-4578-8c76-0116d473cc27",
    "organizationId": "ba3b8cdf-efc1-4a60-88be-ac203d263fe2",
    "name": "West Coast Operations Division",
    "code": "WCO",
    "description": "Updated description for west coast operations",
    "parentId": null,
    "isActive": true,
    "createdAt": "2025-05-11T12:33:59.048Z",
    "updatedAt": "2025-05-11T13:45:22.183Z"
  }
}

Delete Subsidiary

Delete a subsidiary. Note that subsidiaries with child subsidiaries cannot be deleted.

Name
Endpoint
Type
DELETE /api/v1/subsidiaries/{id}
Description

Path Parameters

Name
id
Type
string (UUID)
Required
Description
ID of the subsidiary to delete

Request

curl -X DELETE https://api.example.com/api/v1/subsidiaries/f67f0ea2-77bd-4578-8c76-0116d473cc27 \
  -H "x-stytch-organization-id: ba3b8cdf-efc1-4a60-88be-ac203d263fe2"

Response

{
  "success": true,
  "message": "Subsidiary deleted successfully"
}

Error Responses

The API returns standard HTTP status codes and error messages in a consistent format.

{
  "message": "Error description",
  "code": "ERROR_CODE",
  "details": { ... }
}

Common errors include:

Status Code	Error Code	Description
400	VALIDATION_ERROR	Request data failed validation
400	DUPLICATE_SUBSIDIARY_CODE	A subsidiary with the provided code already exists
400	PARENT_SUBSIDIARY_NOT_FOUND	The specified parent subsidiary does not exist
400	INVALID_PARENT_REFERENCE	A subsidiary cannot be its own parent
400	CIRCULAR_REFERENCE	The parent relationship would create a circular reference
400	SUBSIDIARY_HAS_CHILDREN	Cannot delete a subsidiary that has child subsidiaries
401	MISSING_ORGANIZATION_CONTEXT	Organization context is required for this operation
404	SUBSIDIARY_NOT_FOUND	The requested subsidiary was not found

Hierarchical Relationships

Subsidiaries can be organized in a hierarchical structure using the parentId field. When a subsidiary has a parentId, it indicates that it is a child of another subsidiary. This allows for creating organizational structures that match your business needs.

Some important constraints on hierarchical relationships:

A subsidiary cannot be its own parent
Circular references are not allowed (e.g., A → B → C → A)
Subsidiaries with children cannot be deleted (you must delete or reassign the children first)

Example: Creating a Hierarchical Structure

// Create parent subsidiary
const parent = await apiClient.subsidiaries.create({
  name: "Global Operations",
  code: "GLOBAL",
  description: "Parent subsidiary for all regional operations"
});

// Create child subsidiary referencing the parent
const child = await apiClient.subsidiaries.create({
  name: "Asia Pacific Division",
  code: "APAC",
  description: "Asia Pacific regional operations",
  parentId: parent.subsidiary.id
});

Code Example

Here's an example of how to use the subsidiaries API with the client library:

import { apiClient } from '@/lib/db-adapter';

// List all subsidiaries
async function listAllSubsidiaries() {
  try {
    const result = await apiClient.subsidiaries.list({
      isActive: true,
      orderBy: 'name',
      orderDirection: 'asc'
    });
    
    console.log(`Found ${result.total} subsidiaries`);
    return result.data;
  } catch (error) {
    console.error('Error listing subsidiaries:', error);
    throw error;
  }
}

// Create a new subsidiary
async function createSubsidiary(data) {
  try {
    const result = await apiClient.subsidiaries.create({
      name: data.name,
      code: data.code,
      description: data.description,
      parentId: data.parentId
    });
    
    console.log('Subsidiary created:', result.subsidiary);
    return result.subsidiary;
  } catch (error) {
    console.error('Error creating subsidiary:', error);
    throw error;
  }
}