Create Category

POST 
/catalog/categories

Creates a catalog category for the company resolved from gateway context. status is optional and defaults to active when omitted.

Request

application/json

Body

required

name stringrequired

Possible values: >= 2 characters and <= 128 characters

Display name

status CategoryStatusesDTO (string)

Possible values: [active, inactive, unknown]

Default value: active

List of catalog category statuses

description stringnullable

Possible values: >= 2 characters and <= 1024 characters

Additional information

external_data

object

External system reference data linked to this entity.

id stringrequired

Possible values: >= 4 characters and <= 128 characters

Unique identifier in the external system

property name* any

External system reference data linked to this entity.

parent_id uuidnullable

Parent category identifier. Maximum nesting level 2.

Responses

201

Created

application/json

Schema

Schema

name stringrequired

Possible values: >= 2 characters and <= 128 characters

Display name

status CategoryStatusesDTO (string)required

Possible values: [active, inactive, unknown]

Default value: active

List of catalog category statuses

description stringnullable

Possible values: >= 2 characters and <= 1024 characters

Additional information

external_data

object

nullable

External system reference data; null when no external link exists.

id stringrequired

Possible values: >= 4 characters and <= 128 characters

Unique identifier in the external system

property name* anynullable

External system reference data; null when no external link exists.

image_url stringnullable

Possible values: <= 2048 characters

Link to main image

parent_id uuidnullable

Parent category identifier (nesting depth as in catalog domain)

created_at date-timerequired

Creation date and time. Format: ISO 8601

updated_at date-timerequired

Update date and time. Format: ISO 8601

archived_at date-timenullable

Archiving date and time. Format: ISO 8601

id uuidrequired

Possible values: >= 36 characters and <= 36 characters

Global unique identifier. Format: UUID (id) v4 ISO/IEC 11578:1996

Example (from schema)

{
  "name": "Coffee",
  "status": "active",
  "description": "string",
  "external_data": {
    "id": "external-system-id-001"
  },
  "image_url": "string",
  "parent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-07-28T10:03:43.355Z",
  "updated_at": "2026-07-28T10:03:43.355Z",
  "archived_at": "2026-07-28T10:03:43.355Z",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

400

Bad request — malformed syntax, invalid parameters, or failed validation. Typical code values: validation_error, invalid_request. List endpoints that accept a cursor parameter additionally return invalid_cursor when the cursor is invalid or expired.

application/problem+json

Schema

Schema

title stringrequired

Short human-readable summary

type stringrequired

URI reference identifying the problem category

instance stringnullable

URI reference identifying the specific request that caused this error (e.g. the request path).

trace_id stringrequired

Correlation id for support (report when contacting support)

status int32required

HTTP status code

code stringrequired

Machine-readable code for client branching

detail stringnullable

Human-readable explanation (optional)

reason string

Stable extension when code is existing_entity_conflict. For a duplicate external_data.id within the company, the value is duplicate_external_data_id.

errors

object

nullable

Present when code is validation_error. Keys are field names; values are arrays of human-readable error messages for that field.

property name*

string[]

nullable

Array [

string

]

Example (from schema)

{
  "title": "string",
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "instance": "/api/catalog/goods/regular",
  "trace_id": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00",
  "status": 0,
  "code": "validation_error",
  "detail": "string",
  "reason": "duplicate_external_data_id",
  "errors": {
    "uom_id": [
      "'uom_id' must not be empty."
    ],
    "vat": [
      "'vat' must not be empty."
    ],
    "variations": [
      "'variations' must contain between 1 and 150 items."
    ]
  }
}

validation

{
  "title": "One or more errors occurred.",
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "trace_id": "00-00000000000000000000000000000000-00000000-00",
  "status": 400,
  "instance": "/api/catalog/goods/regular",
  "code": "validation_error",
  "errors": {
    "name": [
      "'name' must not be empty."
    ]
  }
}

401

Missing or invalid credentials before the gateway forwards context (when applicable). The response has no body (empty payload).

403

Caller is not allowed to access this resource or company. The response has no body (empty payload).

404

Resource not found or not visible for the resolved company. The response has no body (empty payload).

409

Conflict with the current state of the resource. Returned when external_data.id is not unique within the company (category, good, or variation). Typical top-level code: existing_entity_conflict. Typical reason: duplicate_external_data_id.

application/problem+json

Schema

Schema

title stringrequired

Short human-readable summary

type stringrequired

URI reference identifying the problem category

instance stringnullable

URI reference identifying the specific request that caused this error (e.g. the request path).

trace_id stringrequired

Correlation id for support (report when contacting support)

status int32required

HTTP status code

code stringrequired

Machine-readable code for client branching

detail stringnullable

Human-readable explanation (optional)

reason string

Stable extension when code is existing_entity_conflict. For a duplicate external_data.id within the company, the value is duplicate_external_data_id.

errors

object

nullable

Present when code is validation_error. Keys are field names; values are arrays of human-readable error messages for that field.

property name*

string[]

nullable

Array [

string

]

Example (from schema)

{
  "title": "string",
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "instance": "/api/catalog/goods/regular",
  "trace_id": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00",
  "status": 0,
  "code": "validation_error",
  "detail": "string",
  "reason": "duplicate_external_data_id",
  "errors": {
    "uom_id": [
      "'uom_id' must not be empty."
    ],
    "vat": [
      "'vat' must not be empty."
    ],
    "variations": [
      "'variations' must contain between 1 and 150 items."
    ]
  }
}

duplicateExternalDataId

{
  "title": "One or more validation errors occurred.",
  "detail": "Duplicate resource by external_data.id found.",
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "trace_id": "00-00000000000000000000000000000000-00000000-00",
  "status": 409,
  "code": "existing_entity_conflict",
  "reason": "duplicate_external_data_id"
}

415

Request body Content-Type is not supported.

application/problem+json

Schema

Schema

title stringrequired

Short human-readable summary

type stringrequired

URI reference identifying the problem category

instance stringnullable

URI reference identifying the specific request that caused this error (e.g. the request path).

trace_id stringrequired

Correlation id for support (report when contacting support)

status int32required

HTTP status code

code stringrequired

Machine-readable code for client branching

detail stringnullable

Human-readable explanation (optional)

reason string

Stable extension when code is existing_entity_conflict. For a duplicate external_data.id within the company, the value is duplicate_external_data_id.

errors

object

nullable

Present when code is validation_error. Keys are field names; values are arrays of human-readable error messages for that field.

property name*

string[]

nullable

Array [

string

]

Example (from schema)

{
  "title": "string",
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "instance": "/api/catalog/goods/regular",
  "trace_id": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00",
  "status": 0,
  "code": "validation_error",
  "detail": "string",
  "reason": "duplicate_external_data_id",
  "errors": {
    "uom_id": [
      "'uom_id' must not be empty."
    ],
    "vat": [
      "'vat' must not be empty."
    ],
    "variations": [
      "'variations' must contain between 1 and 150 items."
    ]
  }
}

unsupportedMediaType

{
  "title": "Unsupported Media Type",
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.16",
  "trace_id": "00-00000000000000000000000000000000-00000000-00",
  "status": 415,
  "code": "invalid_request"
}

429

Rate limit exceeded.

Response Headers

• Retry-After

  integer

  Seconds to wait before retrying

application/problem+json

Schema

Schema

title stringrequired

Short human-readable summary

type stringrequired

URI reference identifying the problem category

instance stringnullable

URI reference identifying the specific request that caused this error (e.g. the request path).

trace_id stringrequired

Correlation id for support (report when contacting support)

status int32required

HTTP status code

code stringrequired

Machine-readable code for client branching

detail stringnullable

Human-readable explanation (optional)

reason string

Stable extension when code is existing_entity_conflict. For a duplicate external_data.id within the company, the value is duplicate_external_data_id.

errors

object

nullable

Present when code is validation_error. Keys are field names; values are arrays of human-readable error messages for that field.

property name*

string[]

nullable

Array [

string

]

Example (from schema)

{
  "title": "string",
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "instance": "/api/catalog/goods/regular",
  "trace_id": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00",
  "status": 0,
  "code": "validation_error",
  "detail": "string",
  "reason": "duplicate_external_data_id",
  "errors": {
    "uom_id": [
      "'uom_id' must not be empty."
    ],
    "vat": [
      "'vat' must not be empty."
    ],
    "variations": [
      "'variations' must contain between 1 and 150 items."
    ]
  }
}

rateLimit

{
  "title": "Too Many Requests",
  "type": "https://tools.ietf.org/html/rfc6585#section-4",
  "trace_id": "00-00000000000000000000000000000000-00000000-00",
  "status": 429,
  "code": "unexpected_error"
}

500

Unexpected server error.

application/problem+json

Schema

Schema

title stringrequired

Short human-readable summary

type stringrequired

URI reference identifying the problem category

instance stringnullable

URI reference identifying the specific request that caused this error (e.g. the request path).

trace_id stringrequired

Correlation id for support (report when contacting support)

status int32required

HTTP status code

code stringrequired

Machine-readable code for client branching

detail stringnullable

Human-readable explanation (optional)

reason string

Stable extension when code is existing_entity_conflict. For a duplicate external_data.id within the company, the value is duplicate_external_data_id.

errors

object

nullable

Present when code is validation_error. Keys are field names; values are arrays of human-readable error messages for that field.

property name*

string[]

nullable

Array [

string

]

Example (from schema)

{
  "title": "string",
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "instance": "/api/catalog/goods/regular",
  "trace_id": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00",
  "status": 0,
  "code": "validation_error",
  "detail": "string",
  "reason": "duplicate_external_data_id",
  "errors": {
    "uom_id": [
      "'uom_id' must not be empty."
    ],
    "vat": [
      "'vat' must not be empty."
    ],
    "variations": [
      "'variations' must contain between 1 and 150 items."
    ]
  }
}

unexpected

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",
  "trace_id": "00-00000000000000000000000000000000-00000000-00",
  "status": 500,
  "code": "internal_server_error"
}

503

Service temporarily unavailable.

application/problem+json

Schema

Schema

title stringrequired

Short human-readable summary

type stringrequired

URI reference identifying the problem category

instance stringnullable

URI reference identifying the specific request that caused this error (e.g. the request path).

trace_id stringrequired

Correlation id for support (report when contacting support)

status int32required

HTTP status code

code stringrequired

Machine-readable code for client branching

detail stringnullable

Human-readable explanation (optional)

reason string

Stable extension when code is existing_entity_conflict. For a duplicate external_data.id within the company, the value is duplicate_external_data_id.

errors

object

nullable

Present when code is validation_error. Keys are field names; values are arrays of human-readable error messages for that field.

property name*

string[]

nullable

Array [

string

]

Example (from schema)

{
  "title": "string",
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "instance": "/api/catalog/goods/regular",
  "trace_id": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00",
  "status": 0,
  "code": "validation_error",
  "detail": "string",
  "reason": "duplicate_external_data_id",
  "errors": {
    "uom_id": [
      "'uom_id' must not be empty."
    ],
    "vat": [
      "'vat' must not be empty."
    ],
    "variations": [
      "'variations' must contain between 1 and 150 items."
    ]
  }
}

unavailable

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.6.4",
  "trace_id": "00-00000000000000000000000000000000-00000000-00",
  "status": 503
}

Loading...