Skip to main content

Get Regular Goods page

GET 
/catalog/goods/regular

Returns a paginated list of regular goods (catalog items). This surface only includes retail regular business type; there is no business_type filter. Each good includes a variations array (sellable SKUs). When the good has a single variation, that variation's name is null — use the good-level name for display. When there are multiple variations, each variation's name is required (non-null). When status is omitted, only active goods are returned.

Optional has_category filters by whether a good has a catalog category (good.category_id is non-null): false — only uncategorized goods; do not send category_id in the same request (400 / validation_error if you do). true — only categorized goods; you may combine with category_id to narrow to specific categories. When omitted, there is no filter by category presence ( category_id still restricts by listed categories when provided).

Request​

Query Parameters

    cursor string

    Possible values: <= 128 characters

    Pagination cursor (opaque token). Invalid or expired cursors yield 400 with code invalid_cursor.

    status string

    Possible values: [active, inactive, all]

    Default value: active

    Filter items (goods) by lifecycle status

    category_id uuid[]

    Filter goods belonging to any of the given categories. Must not be used together with has_category=false (otherwise 400 with validation_error).

    has_category boolean

    Filter by whether the good has a catalog category assigned (good.category_id is non-null).

    • true — only goods in a category; optional category_id restricts to goods in any of the listed categories
    • false — only goods with no category (category_id is null); do not send category_id
    • omitted — no filter by category presence ( category_id may still apply)

    When has_category=false and category_id is also supplied, the API returns 400 with validation_error.

    text_filter string

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

    Case-insensitive text match (per service defaults) against fields exposed by the target list operation. For categories: category name and description. For regular goods: good-level and variation-level name and description, and values in each variation's codes (codes[].value, e.g. SKU or barcode).

    order_by string

    Possible values: [created_at_asc, created_at_desc, updated_at_asc, updated_at_desc, name_asc, name_desc]

    Default value: created_at_asc

Responses​

OK

Schema

    cursor stringnullable

    Token of the next page of the list. null when there is no next page.

    items

    object[]

    required

  • Array [

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

    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 this good (all variations share the same item). Parent fee metadata is not duplicated here — use GET /fees and find the fee whose fee_items[] contains vat.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; 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.

    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

  • ]

  • ]

  • ]

Loading...