Catalogs Introduction

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/elastic-path/main/json-schema/catalog.json",
  "title": "Catalogs Introduction",
  "description": "Use the catalog-view Service API to create your catalogs.",
  "version": "26.0508.7574130",
  "$defs": {
    "amount": {
      "type": "object",
      "description": "The three-letter ISO code for the currency associated with this price.",
      "title": "Amount",
      "properties": {
        "amount": {
          "description": "The price in the lowest denomination for the specified currency. This is a product's list price.",
          "type": "integer",
          "example": 100,
          "format": "int64",
          "x-omitempty": false,
          "x-go-name": "Amount"
        },
        "includes_tax": {
          "description": "Whether this price includes tax.",
          "type": "boolean",
          "example": false,
          "default": false,
          "x-go-name": "IncludesTax"
        }
      },
      "x-go-name": "PriceAmount"
    },
    "available-prices": {
      "description": "If pricebook segmentation is enabled, this will show all the available prices for the product in the CV delta file and will show selected available prices via the admin api",
      "type": "array",
      "items": {
        "type": "object",
        "x-go-name": "AvailablePrice",
        "properties": {
          "pricebook_id": {
            "description": "A unique identifier of a price book.",
            "type": "string"
          },
          "shopper_attributes": {
            "$ref": "#/components/schemas/shopper_attributes"
          },
          "sales": {
            "type": "object",
            "title": "Sales",
            "description": "A set of sale specifications",
            "additionalProperties": {
              "$ref": "#/components/schemas/sale"
            }
          },
          "price": {
            "$ref": "#/components/schemas/currencies"
          },
          "tiers": {
            "$ref": "#/components/schemas/tiers"
          }
        }
      }
    },
    "alternative-prices": {
      "description": "If pricebook segmentation is enabled, this will show all the alternative prices for the product. Will just include 'List Price' initially",
      "type": "array",
      "items": {
        "type": "object",
        "x-go-name": "alternativePrice",
        "properties": {
          "name": {
            "description": "A name to signify what the alternative price means to the shopper... i.e. 'List Price'",
            "type": "string"
          },
          "pricebook_id": {
            "description": "A unique identifier of a price book.",
            "type": "string"
          },
          "shopper_attributes": {
            "$ref": "#/components/schemas/shopper_attributes"
          },
          "sale_id": {
            "description": "The unique identifier of a sale.",
            "type": "string",
            "x-go-name": "SaleID"
          },
          "sale_expires": {
            "description": "The expiration date and time of the sale, provided in UTC.",
            "type": "string",
            "format": "date-time",
            "example": "2025-07-07T14:30:00Z",
            "x-go-name": "SaleExpires",
            "nullable": true
          },
          "price": {
            "$ref": "#/components/schemas/currencies"
          },
          "display_price": {
            "$ref": "#/components/schemas/display-price"
          },
          "original_display_price": {
            "$ref": "#/components/schemas/display-price"
          },
          "original_price": {
            "$ref": "#/components/schemas/currencies"
          },
          "tiers": {
            "description": "You can use tiers to allow your store to offer different pricing for minimum quantities of items that your shoppers purchase.",
            "type": "object",
            "additionalProperties": {
              "description": "The name of the tier, such as `Pencils`.",
              "type": "object",
              "properties": {
                "original_price": {
                  "$ref": "#/components/schemas/currencies"
                },
                "price": {
                  "$ref": "#/components/schemas/currencies"
                },
                "display_price": {
                  "$ref": "#/components/schemas/display-price"
                },
                "original_display_price": {
                  "$ref": "#/components/schemas/display-price"
                }
              },
              "x-go-name": "AlternativePriceTier"
            },
            "x-go-name": "AlternativePriceTiers"
          }
        }
      }
    },
    "prioritized-pricebooks": {
      "description": "If you want multiple price books for different scenarios, such as seasonal sales, business versus retail pricing, and reward programs, when creating a catalog, you can specify up to five price books. You must configure a priority for your price books. Product prices are displayed in the catalog acco",
      "type": "array",
      "maxItems": 5,
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "description": "A unique identifier of a price book.",
            "type": "string",
            "format": "uuid"
          },
          "priority": {
            "description": "Priority is a number and the price book with the highest number has the highest priority.",
            "type": "integer"
          }
        },
        "required": [
          "priority",
          "id"
        ],
        "x-go-name": "PrioritizedPricebook"
      }
    },
    "catalog": {
      "type": "object",
      "title": "Catalog",
      "description": "Creates a catalog with the following attributes.",
      "properties": {
        "id": {
          "type": "string",
          "description": "A unique identifier of a catalog.",
          "example": "8dbb35b2-ef04-477e-974d-e5f3abe6faae"
        },
        "attributes": {
          "type": "object",
          "properties": {
            "name": {
              "description": "The name of a catalog.",
              "type": "string",
              "example": "catalog-123"
            },
            "description": {
              "description": "A brief description of the catalog, such as the purpose of the catalog.",
              "type": "string",
              "example": "Catalog for Store 123",
              "default": ""
            },
            "hierarchy_ids": {
              "description": "The unique identifiers of the hierarchies associated with a catalog.",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "pricebook_id": {
              "description": "The unique identifier of a price book associated with a catalog. If no price book is selected, the catalog is displayed without prices.",
              "type": "string"
            },
            "pricebook_ids": {
              "$ref": "#/components/schemas/prioritized-pricebooks"
            },
            "locales": {
              "description": "Product Experience Manager supports localization of products and hierarchies. If you store supports multiple languages, you can localize product names and descriptions.",
              "type": "object",
              "additionalProperties": {
                "description": "A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.",
                "type": "object",
                "additionalProperties": {
                  "description": "A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.",
                  "type": "string"
                }
              }
            },
            "created_at": {
              "description": "The date and time a catalog is created.",
              "type": "string",
              "example": "2020-09-22T09:00:00",
              "format": "date-time"
            },
            "updated_at": {
              "description": "The date and time a catalog was updated.",
              "type": "string",
              "example": "2020-09-22T09:00:00",
              "format": "date-time"
            },
            "owner": {
              "description": "The owner of this resource, can be either `organization` or `store`.",
              "type": "string",
              "enum": [
                "store",
                "organization"
              ],
              "x-go-name": "Owner",
              "default": "store",
              "nullable": true
            },
            "enable_price_segmentation": {
              "description": "This indicates whether the catalog will support price segmentation using catalog rules to define which pricebook(s) to use for pricing",
              "type": "boolean",
              "example": true,
              "default": false,
              "x-go-name": "EnablePriceSegmentation"
            },
            "include_draft_products": {
              "description": "When `true`, publishing this catalog includes products in `draft` status in the catalog release. When `false` or omitted, only `live` products are included in the release (default).",
              "type": "boolean",
              "example": false,
              "default": false,
              "x-go-name": "IncludeDraftProducts"
            }
          },
          "required": [
            "name",
            "hierarchy_ids",
            "created_at",
            "updated_at"
          ]
        },
        "relationships": {
          "description": "Relationships are established between different catalog entities. For example, a catalog rule and a price book are related to a catalog, as both are associated with it.",
          "type": "object",
          "title": "CatalogRelationships",
          "properties": {
            "rules": {
              "description": "The catalog rules related to a catalog.",
              "type": "object",
              "properties": {
                "links": {
                  "$ref": "#/components/schemas/related-link"
                }
              }
            },
            "releases": {
              "description": "When a catalog is published, a catalog release is created. This is a URL to all catalog published releases available for this catalog.",
              "type": "object",
              "properties": {
                "links": {
                  "$ref": "#/components/schemas/related-link"
                },
                "meta": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "description": "The number releases available for a catalog.",
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        },
        "type": {
          "type": "string",
          "example": "catalog",
          "enum": [
            "catalog"
          ]
        }
      },
      "required": [
        "id",
        "type",
        "attributes"
      ]
    },
    "catalog-create-data": {
      "type": "object",
      "title": "CatalogCreateData",
      "description": "Creates a catalog with the following attributes.",
      "properties": {
        "data": {
          "type": "object",
          "properties": {
            "attributes": {
              "type": "object",
              "properties": {
                "name": {
                  "description": "The name of the catalog.",
                  "type": "string",
                  "minLength": 1,
                  "example": "catalog-123"
                },
                "description": {
                  "description": "A brief description of the catalog.",
                  "type": "string",
                  "example": "Catalog for Store 123",
                  "nullable": true
                },
                "hierarchy_ids": {
                  "description": "The unique identifiers of the hierarchies to associate with a catalog.",
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "pricebook_id": {
                  "description": "The unique identifier of the price book to associate with this catalog. You can specify either a `pricebook_id` or `pricebook_ids` but not both. If you specify both a `pricebook_id` and `pricebook_ids`, a `422 Unprocessable Entity` error is displayed.\n",
                  "type": "string"
                },
                "pricebook_ids": {
                  "$ref": "#/components/schemas/prioritized-pricebooks"
                },
                "locales": {
                  "description": "Product Experience Manager supports localization of products and hierarchies. If you store supports multiple languages, you can localize product names and descriptions.",
                  "type": "object",
                  "additionalProperties": {
                    "description": "A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.",
                    "type": "object",
                    "additionalProperties": {
                      "description": "A [three-letter language code](https://www.iso.org/iso-639-language-code) that represents the name of language you have used.",
                      "type": "string"
                    }
                  }
                },
                "enable_price_segmentation": {
                  "description": "This indicates whether the catalog will support price segmentation using catalog rules to define which pricebook(s) to use for pricing",
                  "type": "boolean",
                  "example": true,
                  "default": false,
                  "x-go-name": "EnablePriceSegmentation"
                },
                "include_draft_products": {
                  "description": "When `true`, publishing this catalog includes products in `draft` status in the catalog release. When `false` or omitted, only `live` products are included in the release (default).",
                  "type": "boolean",
                  "example": false,
                  "default": false,
                  "x-go-name": "IncludeDraftProducts"
                }
              },
              "required": [
                "name",
                "hierarchy_ids"
              ]
            },
            "type": {
              "description": "Represents the type of object being returned. Always `Catalog`.",
              "type": "string",
              "example": "catalog",
              "enum": [
                "catalog"
              ]
            }
          },
          "required": [
            "type",
            "attributes"
          ]
        }
      },
      "required": [
        "data"
      ]
    },
    "catalog-data": {
      "type": "object",
      "title": "CatalogData",
      "description": "Container for a single catalog.",
      "properties": {
        "data": {
          "$ref": "#/components/schemas/catalog"
        },
        "links": {
          "$ref": "#/components/schemas/links"
        }
      },
      "required": [
        "data"
      ]
    },
    "catalog-list-data": {
      "type": "object",
      "title": "CatalogListData",
      "description": "Container for a list of catalogs.",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/catalog"
          }
        },
        "meta": {
          "$ref": "#/components/schemas/page-meta"
        },
        "links": {
          "$ref": "#/components/schemas/links"
        }
      },
      "required": [
        "data"
      ]
    },
    "catalog-update-data": {
      "type": "object",
      "title": "CatalogUpdateData",
      "description": "A catalog combines price books, product lists, and hierarchies.",
      "properties": {
        "data": {
          "type": "object",
          "properties": {
            "attributes": {
              "type": "object",
              "properties": {
                "name": {
                  "description": "The name of the catalog.",
                  "type": "string",
                  "minLength": 1,
                  "example": "catalog-123",
                  "nullable": true
                },
                "description": {
                  "description": "A brief description of the catalog.",
                  "type": "string",
                  "example": "Catalog for Store 123",
                  "nullable": true
                },
                "hierarchy_ids": {
                  "description": "The unique identifiers of the hierarchies to associate with a catalog.",
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "nullable": true
                },
                "pricebook_id": {
                  "description": "The unique identifier of a price book to associate with a catalog. You can specify a `pricebook_id` or a `pricebook_ids` but not both. If you specify both, a `422 unprocessable entity` error is displayed.",
                  "type": "string",
                  "nullable": true
                },
                "pricebook_ids": {
                  "$ref": "#/components/schemas/prioritized-pricebooks"
                },
                "locales": {
                  "description": "Product Experience Manager supports localization of products and hierarchies. If you store supports multiple languages, you can localize product names and descriptions.",
                  "type": "object",
                  "additionalProperties": {
                    "description": "A [three-letter language code](https://www.loc.gov/standards/iso639-2/) that represents the name of language you have used.",
                    "type": "object",
                    "additionalProperties": {
                      "description": "A [three-letter language code](https://www.loc.gov/standards/iso639-2/) that represents the name of language you have used.",
                      "type": "string"
                    }
                  }
                },
                "enable_price_segmentation": {
                  "description": "This indicates whether the catalog will support price segmentation using catalog rules to define which pricebook(s) to use for pricing",
                  "type": "boolean",
                  "example": true,
                  "default": false,
                  "x-go-name": "EnablePriceSegmentation"
                },
                "include_draft_products": {
                  "description": "When `true`, publishing this catalog includes products in `draft` status in the catalog release. When `false` or omitted, only `live` products are included in the release (default).",
                  "type": "boolean",
                  "example": false,
                  "default": false,
                  "x-go-name": "IncludeDraftProducts"
                }
              }
            },
            "id": {
              "description": "The unique identifier of the catalog to be updated.",
              "type": "string",
              "x-go-name": "ID",
              "example": "8dbb35b2-ef04-477e-974d-e5f3abe6faae"
            },
            "type": {
              "description": "This represents the type of object being returned. Always `catalog`.",
              "type": "string",
              "example": "catalog",
              "enum": [
                "catalog"
              ]
            }
          },
          "required": [
            "type",
            "id",
            "attributes"
          ]
        }
      },
      "required": [
        "data"
      ]
    },
    "component-product": {
      "type": "object",
      "title": "Component Product",
      "description": "The unique identifier of the component, for example, `games`.",
      "properties": {
        "name": {
          "description": "The component name is the name that is displayed in your storefront.",
          "type": "string",
          "x-go-name": "Name"
        },
        "min": {
          "description": "The minimum number of product options a shopper can select from this component.",
          "type": "integer",
          "x-go-name": "Min",
          "nullable": true
        },
        "max": {
          "description": "The maximum number of product options a shopper can select from this component.",
          "type": "integer",
          "x-go-name": "Max",
          "nullable": true
        },
        "sort_order": {
          "description": "The sort order of the components. The `create a bundle` and `update a bundle` endpoints do not sort the components. You can use the `sort_order` attribute when programming your storefront to display the components in the order that you want.",
          "type": "integer",
          "x-go-name": "Sort Order",
          "nullable": true
        },
        "options": {
          "description": "The product options included in a component. This can be the ID of another bundle.",
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/component-product-option"
          },
          "x-go-name": "Options"
        }
      }
    },
    "component-product-option": {
      "type": "object",
      "title": "Component Product Option",
      "description": "The product options included in a component. This can be the ID of another bundle.",
      "properties": {
        "id": {
          "description": "A unique identifier of the product you want to add to a component.",
          "type": "string",
          "format": "uuid",
          "x-go-name": "ID"
        },
        "type": {
          "description": "This represents the type of object being returned. Always `product`.",
          "type": "string",
          "x-go-name": "Type",
          "default": "product",
          "example": "product",
          "enum": [
            "product"
          ]
        },
        "quantity": {
          "description": "The number of this product option that a shopper must purchase.",
          "type": "integer",
          "example": 2,
          "x-go-name": "Quantity"
        },
        "min": {
          "description": "The minimum quantity of this product option that a shopper can select.",
          "type": "integer",
          "x-go-name": "Min",
          "nullable": true
        },
        "max": {
          "description": "The maximum quantity of this product option that a shopper can select.",
          "type": "integer",
          "x-go-name": "Max",
          "nullable": true
        },
        "sort_order": {
          "description": "The sort order of the options. The `create a bundle` and `update a bundle` endpoints do not sort the options. You can use the `sort_order` attribute when programming your storefront to display the options in the order that you want.",
          "type": "integer",
          "example": 15,
          "x-go-name": "Sort Order",
          "nullable": true
        },
        "default": {
          "description": "The boolean indicates whether the current option is a default option for the component.",
          "type": "boolean",
          "example": true,
          "default": false,
          "x-go-name": "Default",
          "nullable": true
        },
        "product_should_be_substituted_with_child": {
          "description": "Indicates that the parent product added to a bundle is not directly purchasable. When set to true, the child products of the parent product should be displayed as options for selection in the bundle.",
          "type": "boolean",
          "example": true,
          "x-go-name": "Is Parent Product",
          "nullable": true
        },
        "excluded_children": {
          "description": "Merchants can exclude specific child products from a parent product when configuring a bundle.",
          "type": "array",
          "items": {
            "type": "string"
          },
          "example": [
            "2d491d1c-729d-43d7-a2d2-e0a56edab43d"
          ],
          "x-go-name": "Excluded Children",
          "x-omitempty": true
        }
      }
    },
    "components": {
      "type": "object",
      "title": "Components",
      "description": "A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity.",
      "additionalProperties": {
        "$ref": "#/components/schemas/component-product"
      }
    },
    "custom-input-validation-rule-options": {
      "type": "object",
      "description": "The length of the custom input text field.",
      "x-go-name": "CustomInputValidationRuleOptions",
      "properties": {
        "max_length": {
          "description": "The number of characters the custom text field can be. You can specify a maximum length up to 255 characters, as the limit is 255 characters.",
          "type": "integer",
          "x-go-name": "MaxLength",
          "example": 255
        }
      }
    },
    "custom-input-validation-rule": {
      "type": "object",
      "title": "Custom Input Validation Rule",
      "description": "The validation rules for the custom text.",
      "x-go-name": "CustomInputValidationRule",
      "properties": {
        "type": {
          "description": "This represents the type of object being returned. Must be `string`.",
          "type": "string",
          "x-go-name": "Type",
          "default": "string",
          "example": "string",
          "enum": [
            "string"
          ]
        },
        "options": {
          "$ref": "#/components/schemas/custom-input-validation-rule-options"
        }
      }
    },
    "custom-input": {
      "type": "object",
      "title": "Custom Input",
      "description": "The name of the custom input. You can rename the input to something more representative of the input that shoppers are adding, for example, `message` or `front`.",
      "properties": {
        "name": {
          "description": "The name for the custom text field that is displayed in your storefront.",
          "type": "string",
          "x-go-name": "Name",
          "example": "Message"
        },
        "validation_rules": {
          "description": "The validation rules for the custom text.",
          "type": "array",
          "x-go-name": "ValidationRules",
          "items": {
            "$ref": "#/components/schemas/custom-input-validation-rule"
          }
        },
        "required": {
          "description": "This is `true` or `false` depending on whether the custom text is required.",
          "type": "boolean",
          "x-go-name": "Required",
          "example": false,
          "default": false,
          "nullable": true
        }
      }
    },
    "custom_inputs": {
      "type": "object",
      "title": "Custom Inputs",
      "description": "You can allow your shoppers to add custom text to a product when adding product items to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized or you sell greetings cards that can be printed with your shoppers personalized messages.  You can do this ",
      "additionalProperties": {
        "$ref": "#/components/schemas/custom-input"
      }
    },
    "currencies": {
      "type": "object",
      "description": "A collection of one or more currencies objects that consists of the [**three-letter ISO code**](https://www.iso.org/iso-3166-country-codes.html) of the currencies associated with this price and the amount. This is the product's price.",
      "title": "Currencies",
      "additionalProperties": {
        "$ref": "#/components/schemas/amount"
      }
    },
    "shopper_attributes": {
      "type": "object",
      "description": "A collection of key-value string pairs, viewable by shoppers.",
      "title": "ShopperAttributes",
      "additionalProperties": {
        "type": "string"
      }
    },
    "diff-list-data": {
      "type": "object",
      "title": "DiffListData",
      "description": "A list of differences between two releases.",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/product-diff"
          }
        },
        "links": {
          "$ref": "#/components/schemas/links"
        }
      }
    },
    "display-price": {
      "type": "object",
      "description": "A price formatted for display.",
      "x-omitempty": true,
      "properties": {
        "with_tax": {
          "$ref": "#/components/schemas/formatted-price"
        },
        "without_tax": {
          "$ref": "#/components/schemas/formatted-price"
        }
      }
    },
    "error": {
      "type": "object",
      "title": "APIError",
      "description": "APIError is a json-api style part of an error response.",
      "properties": {
        "detail": {
          "type": "string",
          "example": "not processable",
          "x-go-name": "Detail"
        },
        "status": {
          "type": "string",
          "example": "422",
          "x-go-name": "Status"
        },
        "title": {
          "type": "string",
          "example": "There was a problem processing your request.",
          "x-go-name": "Title"
        }
      },
      "x-go-name": "APIError"
    },
    "error-response": {
      "type": "object",
      "title": "ErrorResponse",
      "description": "ErrorResponse is a json-api style Error response.",
      "properties": {
        "errors": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/error"
          },
          "x-go-name": "Errors"
        }
      },
      "x-go-name": "ErrorResponse"
    },
    "extension": {
      "type": "object",
      "title": "Extension",
      "description": "The name of the product template.",
      "additionalProperties": {
        "description": "The product attributes available for this template.",
        "type": "object"
      }
    },
    "extensions": {
      "type": "object",
      "title": "Extensions",
      "description": "With extension templates, you can attach a specific set of custom fields to your products in Product Experience Manager. For example, a **Book** template might contain the attributes, such as **ISBN**, **Author**, **Number of pages**, **Year Published**, or **Condition (New/Used)**.",
      "additionalProperties": {
        "$ref": "#/components/schemas/extension"
      }
    },
    "file-reference": {
      "description": "In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.",
      "type": "object",
      "properties": {
        "type": {
          "description": "This represents the type of object being returned. Always `file`.",
          "type": "string",
          "example": "file",
          "enum": [
            "file"
          ]
        },
        "id": {
          "description": "A unique identifier for a file.",
          "type": "string",
          "format": "uuid"
        },
        "created_at": {
          "description": "The date and time a file is created.",
          "type": "string",
          "format": "date-time",
          "example": "1970-01-01T00:00:00.000",
          "x-go-name": "CreatedAt"
        }
      },
      "x-go-name": "FileRelationship"
    },
    "files-relationship": {
      "description": "In Product Experience Manager, products can have associated rich media assets, such as product images or a file containing additional product details.",
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/file-reference"
          }
        }
      },
      "x-omitempty": true
    },
    "component-products-relationship": {
      "description": "A bundle is a purchasable product, comprising of one or more products that you want to sell together. You can create multiple components within a bundle. Each component must have at least one or more options. Each option is a product and a quantity. You can link to the products that make up your bun",
      "type": "object",
      "properties": {
        "

# --- truncated at 32 KB (139 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/json-schema/catalog.json