Create Regular Good

POST 
/catalog/goods/regular

Creates a regular (retail) good for the company resolved from gateway context.

Provide variations (1–150 items). Per-variation name is optional in the schema; when there is more than one variation, each element must include a non-empty name (otherwise 400 / validation_error). With exactly one variation, omit name on that element — use the good-level name for display.

Code entries in codes use CodeEntryDTO. Violations return 400 with validation_error.

Request

application/json

Body

required

name stringrequired

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

Display name

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.

category_id uuidnullable

Category identifier. Null to place the good at root level.

uom_id uuidrequired

Unit of measure identifier. Use GET /uoms to discover available values.

vat

object

required

VAT fee item (tax rate) applied to this good; all variations share the same VAT. Use GET /fees and choose an id from one of the returned fees' fee_items[].

fee_item_id uuidrequired

Fee item identifier (matches id in fee_items[] returned by GET /fees).

variations

object[]

required

Possible values: >= 1, <= 150

Sellable variations of the good.

Array [

name string

Possible values: non-empty and <= 128 characters

Variation display name; required when the good has multiple variations.

description stringnullable

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

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.

status stringrequired

Possible values: [active, inactive]

Default value: active

Variation lifecycle status at creation time.

default_price

object

Price (amount + currency). Is used to represent monetary amounts in various currencies. The minimum value includes 0.

value int64required

Amount in minimum currency units

currency_code stringrequired

ISO 4217 currency code. Available values: AED

codes

object[]

Possible values: <= 20

Typed identifiers (barcodes and SKUs) for the variation. Each entry uses CodeEntryDTO (type + value).

Array [

type stringrequired

Possible values: [ean_8, ean_13, itf_14, upc_a, sku, other]

Type of code; use other when the value does not map to a listed barcode or SKU kind.

value stringrequired

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

]

]

Responses

201

Created

application/json

Schema

Schema

id uuidrequired

Good identifier (same as catalog item id)

name stringrequired

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

description stringnullable

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

external_data

object

nullable

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.

status GoodStatusPublicDTO (string)required

Possible values: [active, inactive, unknown]

Good lifecycle status

category_id uuidnullable
business_type RegularGoodBusinessTypePublicDTO (string)required

Possible values: [regular]

Business type for goods returned from /catalog/goods/regular. The API always returns regular on this surface.

uom

object

required

Unit of measure

id uuidrequired

UOM identifier; matches uom_id in good

name stringrequired

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

Full name

symbol stringrequired

Possible values: non-empty and <= 16 characters

Short display label

exponent integerrequired

Possible values: <= 3

Decimal exponent (e.g. 3 means quantities are in thousandths)

vat

object

required

VAT fee item for the good (all variations share the same item). Values align with the matching entry in GET /fees → fee_items[] for fee_item_id.

fee_item_id uuidrequired

Fee item identifier; matches id in fee_items[].

fee_item_name stringrequired

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

Fee item display name (e.g. tax rate label).

fee_item_percentage double

Possible values: <= 100

Tax rate in percent (decimal, e.g. 5 or 5.25). Omitted when the fee item is exempt or non-percentage.

variations

object[]

required

Possible values: >= 1, <= 150

Sellable variations of the good.

Array [

id uuidrequired

Variation identifier

name stringnullable

Possible values: <= 128 characters

Variation display name; null when this is the only variation on the good.

description stringnullable

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

external_data

object

nullable

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.

status PublicVariationStatuses (string)required

Possible values: [active, inactive]

Variation lifecycle status for public responses

default_price

object

Price (amount + currency). Is used to represent monetary amounts in various currencies. The minimum value includes 0.

value int64required

Amount in minimum currency units

currency_code stringrequired

ISO 4217 currency code. Available values: AED

image_url stringnullable

Possible values: <= 2048 characters

Link to variation image when available.

codes

object[]

required

Possible values: <= 20

Array [

type stringrequired

Possible values: [ean_8, ean_13, itf_14, upc_a, sku, other]

Type of code; use other when the value does not map to a listed barcode or SKU kind.

value stringrequired

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

]

]

Example (from schema)

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Latte",
  "description": "string",
  "external_data": {
    "id": "external-system-id-001"
  },
  "status": "active",
  "category_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "business_type": "regular",
  "uom": {
    "id": "33333333-3333-4333-8333-333333333333",
    "name": "Kilogram",
    "symbol": "kg",
    "exponent": 0
  },
  "vat": {
    "fee_item_id": "66666666-6666-4666-8666-666666666666",
    "fee_item_name": "5%",
    "fee_item_percentage": 5
  },
  "variations": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "description": "string",
      "external_data": {
        "id": "external-system-id-001"
      },
      "status": "active",
      "default_price": {
        "value": 100,
        "currency_code": "AED"
      },
      "image_url": "string",
      "codes": [
        {
          "type": "ean_8",
          "value": "string"
        }
      ]
    }
  ]
}

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...