Skip to content

CatalogItemState ​

Type: schema

Description ​

A product or variant as its events carry it: what the store sells (its SKU, prices, images, attributes and stock) with the product's own details and its marketplace listings. A product with variants shows one of its variants' SKU, images, pricing and stock.

TypeScript Definition ​

typescript
CatalogItemState: {{
            product_id: string;
            /** @description The variant, on a variant's events. On a product's events: for a product with variants, the variant whose SKU, images, pricing and stock it shows; `null` for a product without variants. */
            variant_id: string | null;
            /** @description `null` when none is set. */
            sku: string | null;
            /** @description The variant's slug on a variant's events, the product's otherwise. */
            slug: string;
            product_slug: string;
            /** @description Empty on a product's events. */
            variant_slug: string;
            product_name: string;
            variant_name: string | null;
            /** @enum {string} */
            product_type: "physical" | "digital" | "bundle";
            /**
             * @description The variant's status on a variant's events, the product's otherwise. Only `active` items are sold.
             * @enum {string}
             */
            status: "draft" | "active" | "inactive";
            /** @description Whether `status` is `active`. */
            active: boolean;
            /** @description On a variant's events, whether it is its product's default variant; always `true` on a product's events. */
            is_default: boolean;
            /** @description Whether the product has variants; always `true` on a variant's events. */
            has_variant: boolean;
            short_description: string | null;
            stock_available: boolean;
            on_offer: boolean;
            on_subscription: boolean;
            on_promotion: boolean;
            /** @description Freeform metadata key/value map. */
            metadata: {
                [key: string]: string;
            } | null;
            seo: components["schemas"]["Seo"];
            /** @description HSN/SAC tax classification code. `null` when not configured. */
            hsn_code: string | null;
            category_ids: string[];
            tags: string[] | null;
            /** @description Number of approved reviews; pending, rejected and archived reviews are excluded. */
            reviews_count: number;
            /**
             * Format: double
             * @description Sum of approved review ratings, preserving fractional ratings. Zero when there are no approved reviews. Divide by reviews_count when nonzero to compute the average.
             */
            reviews_rating_sum: number;
            attributes: components["schemas"]["ProductAttribute"][];
            images: components["schemas"]["ProductImage"][];
            /** @description Pricing for the store's default customer group. `null` when no pricing is configured. */
            pricing: components["schemas"]["ProductPricing"] | null;
            promotion: components["schemas"]["ProductPromotion"];
            subscription: components["schemas"]["ProductSubscription"][];
            associated_options: components["schemas"]["AssociatedOption"] | null;
            shipping: components["schemas"]["ProductShipping"];
            /** @description Packing dimensions; `null` when none are configured. */
            packaging: components["schemas"]["Packaging"];
            /** @description Its stock: whether quantities are tracked and backorders allowed, and its quantities summed across warehouses and batches. */
            inventory: {
                track_quantity: boolean;
                allow_backorder: boolean;
                stock_quantity: number;
                reserved_quantity: number;
                sold_quantity: number;
                received_quantity: number;
            };
            /** @description The product's variant option axes (e.g. size, colour) with their values; `null` for a product without variants. */
            variant_options: components["schemas"]["VariantOption"][] | null;
            /**
             * @description The product's status.
             * @enum {string}
             */
            product_status: "draft" | "active" | "inactive";
            product_description: string | null;
            product_short_description: string | null;
            /** @description Whether the product is featured. */
            is_featured: boolean;
            /** @description The product's freeform metadata key/value map. */
            product_metadata: {
                [key: string]: string;
            } | null;
            product_seo: components["schemas"]["Seo"];
            /** @description Its listings on the marketplaces the store sells through: a product's own on a product's events, the variant's on a variant's. */
            marketplace_listing: components["schemas"]["ItemMarketplaceListing"][];
        };
        /** Category */
}

Component References ​

ReferenceResolves To
components["schemas"]["Seo"]Seo
components["schemas"]["ProductAttribute"]ProductAttribute
components["schemas"]["ProductImage"]ProductImage
components["schemas"]["ProductPricing"]ProductPricing
components["schemas"]["ProductPromotion"]ProductPromotion
components["schemas"]["ProductSubscription"]ProductSubscription
components["schemas"]["AssociatedOption"]AssociatedOption
components["schemas"]["ProductShipping"]ProductShipping
components["schemas"]["Packaging"]Packaging
components["schemas"]["VariantOption"]VariantOption
components["schemas"]["ItemMarketplaceListing"]ItemMarketplaceListing

OpenAPI Schema ​

json
{
  "title": "CatalogItemState",
  "description": "A product or variant as its events carry it: what the store sells (its SKU, prices, images, attributes and stock) with the product's own details and its marketplace listings. A product with variants shows one of its variants' SKU, images, pricing and stock.",
  "type": "object",
  "externalDocs": {
    "url": "https://llm-docs.commercengine.io/storefront/schemas/CatalogItemState",
    "description": "API reference for the CatalogItemState schema"
  },
  "required": [
    "product_id",
    "variant_id",
    "sku",
    "slug",
    "product_slug",
    "variant_slug",
    "product_name",
    "variant_name",
    "product_type",
    "status",
    "active",
    "is_default",
    "has_variant",
    "short_description",
    "stock_available",
    "on_offer",
    "on_subscription",
    "on_promotion",
    "metadata",
    "seo",
    "hsn_code",
    "category_ids",
    "tags",
    "reviews_count",
    "reviews_rating_sum",
    "attributes",
    "images",
    "pricing",
    "promotion",
    "subscription",
    "associated_options",
    "shipping",
    "packaging",
    "inventory",
    "variant_options",
    "product_status",
    "product_description",
    "product_short_description",
    "is_featured",
    "product_metadata",
    "product_seo",
    "marketplace_listing"
  ],
  "properties": {
    "product_id": {
      "type": "string"
    },
    "variant_id": {
      "description": "The variant, on a variant's events. On a product's events: for a product with variants, the variant whose SKU, images, pricing and stock it shows; `null` for a product without variants.",
      "type": [
        "string",
        "null"
      ]
    },
    "sku": {
      "description": "`null` when none is set.",
      "type": [
        "string",
        "null"
      ]
    },
    "slug": {
      "description": "The variant's slug on a variant's events, the product's otherwise.",
      "type": "string"
    },
    "product_slug": {
      "type": "string"
    },
    "variant_slug": {
      "description": "Empty on a product's events.",
      "type": "string"
    },
    "product_name": {
      "type": "string"
    },
    "variant_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "product_type": {
      "type": "string",
      "enum": [
        "physical",
        "digital",
        "bundle"
      ]
    },
    "status": {
      "description": "The variant's status on a variant's events, the product's otherwise. Only `active` items are sold.",
      "type": "string",
      "enum": [
        "draft",
        "active",
        "inactive"
      ]
    },
    "active": {
      "description": "Whether `status` is `active`.",
      "type": "boolean"
    },
    "is_default": {
      "description": "On a variant's events, whether it is its product's default variant; always `true` on a product's events.",
      "type": "boolean"
    },
    "has_variant": {
      "description": "Whether the product has variants; always `true` on a variant's events.",
      "type": "boolean"
    },
    "short_description": {
      "type": [
        "string",
        "null"
      ]
    },
    "stock_available": {
      "type": "boolean"
    },
    "on_offer": {
      "type": "boolean"
    },
    "on_subscription": {
      "type": "boolean"
    },
    "on_promotion": {
      "type": "boolean"
    },
    "metadata": {
      "description": "Freeform metadata key/value map.",
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": {
        "type": "string"
      }
    },
    "seo": {
      "$ref": "#/components/schemas/Seo"
    },
    "hsn_code": {
      "description": "HSN/SAC tax classification code. `null` when not configured.",
      "type": [
        "string",
        "null"
      ]
    },
    "category_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "tags": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      }
    },
    "reviews_count": {
      "description": "Number of approved reviews; pending, rejected and archived reviews are excluded.",
      "type": "integer"
    },
    "reviews_rating_sum": {
      "description": "Sum of approved review ratings, preserving fractional ratings. Zero when there are no approved reviews. Divide by reviews_count when nonzero to compute the average.",
      "type": "number",
      "format": "double"
    },
    "attributes": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ProductAttribute"
      }
    },
    "images": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ProductImage"
      }
    },
    "pricing": {
      "description": "Pricing for the store's default customer group. `null` when no pricing is configured.",
      "oneOf": [
        {
          "$ref": "#/components/schemas/ProductPricing"
        },
        {
          "type": "null"
        }
      ]
    },
    "promotion": {
      "$ref": "#/components/schemas/ProductPromotion"
    },
    "subscription": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ProductSubscription"
      }
    },
    "associated_options": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/AssociatedOption",
          "description": "Used when `variant_id` is not null."
        },
        {
          "type": "null",
          "description": "Null when `variant_id` is null."
        }
      ]
    },
    "shipping": {
      "$ref": "#/components/schemas/ProductShipping"
    },
    "packaging": {
      "description": "Packing dimensions; `null` when none are configured.",
      "$ref": "#/components/schemas/Packaging"
    },
    "inventory": {
      "description": "Its stock: whether quantities are tracked and backorders allowed, and its quantities summed across warehouses and batches.",
      "type": "object",
      "properties": {
        "track_quantity": {
          "type": "boolean"
        },
        "allow_backorder": {
          "type": "boolean"
        },
        "stock_quantity": {
          "type": "number"
        },
        "reserved_quantity": {
          "type": "number"
        },
        "sold_quantity": {
          "type": "number"
        },
        "received_quantity": {
          "type": "number"
        }
      },
      "required": [
        "track_quantity",
        "allow_backorder",
        "stock_quantity",
        "reserved_quantity",
        "sold_quantity",
        "received_quantity"
      ]
    },
    "variant_options": {
      "description": "The product's variant option axes (e.g. size, colour) with their values; `null` for a product without variants.",
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/components/schemas/VariantOption"
      }
    },
    "product_status": {
      "description": "The product's status.",
      "type": "string",
      "enum": [
        "draft",
        "active",
        "inactive"
      ]
    },
    "product_description": {
      "type": [
        "string",
        "null"
      ]
    },
    "product_short_description": {
      "type": [
        "string",
        "null"
      ]
    },
    "is_featured": {
      "description": "Whether the product is featured.",
      "type": "boolean"
    },
    "product_metadata": {
      "description": "The product's freeform metadata key/value map.",
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": {
        "type": "string"
      }
    },
    "product_seo": {
      "$ref": "#/components/schemas/Seo"
    },
    "marketplace_listing": {
      "description": "Its listings on the marketplaces the store sells through: a product's own on a product's events, the variant's on a variant's.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ItemMarketplaceListing"
      }
    }
  }
}

Auto-generated from OpenAPI spec and TypeScript definitions

Last updated: