product_Base

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/product_Base",
  "title": "product_Base",
  "type": "object",
  "description": "Shared `Product` properties used in:\n* `POST`\n* `PUT`\n* `GET`",
  "x-internal": false,
  "x-examples": {
    "example-1": {
      "id": 0,
      "name": "Smith Journal 13",
      "type": "physical",
      "sku": "SM-13",
      "description": "<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>",
      "weight": 0,
      "width": 0,
      "depth": 0,
      "height": 0,
      "price": 0,
      "cost_price": 0,
      "retail_price": 0,
      "sale_price": 0,
      "map_price": 0,
      "tax_class_id": 0,
      "product_tax_code": "string",
      "categories": [
        0
      ],
      "brand_id": 0,
      "inventory_level": 0,
      "inventory_warning_level": 0,
      "inventory_tracking": "none",
      "fixed_cost_shipping_price": 0,
      "is_free_shipping": true,
      "is_visible": true,
      "is_featured": true,
      "related_products": [
        0
      ],
      "warranty": "string",
      "bin_picking_number": "string",
      "layout_file": "string",
      "upc": "string",
      "search_keywords": "string",
      "availability_description": "string",
      "availability": "available",
      "gift_wrapping_options_type": "any",
      "gift_wrapping_options_list": [
        0
      ],
      "sort_order": -2147483648,
      "condition": "New",
      "is_condition_shown": true,
      "order_quantity_minimum": 0,
      "order_quantity_maximum": 0,
      "page_title": "string",
      "meta_keywords": [
        "string"
      ],
      "meta_description": "string",
      "view_count": 0,
      "preorder_release_date": "2019-08-24T14:15:22Z",
      "preorder_message": "string",
      "is_preorder_only": true,
      "is_price_hidden": true,
      "price_hidden_label": "string",
      "custom_url": {
        "url": "string",
        "is_customized": true
      },
      "open_graph_type": "product",
      "open_graph_title": "string",
      "open_graph_description": "string",
      "open_graph_use_meta_description": true,
      "open_graph_use_product_name": true,
      "open_graph_use_image": true,
      "brand_name": "Common Good",
      "gtin": "string",
      "mpn": "string",
      "date_last_imported": "2015-07-03T18:16:02+00:00",
      "reviews_rating_sum": 3.2,
      "reviews_count": 4,
      "total_sold": 80,
      "custom_fields": [
        {
          "id": 6,
          "name": "ISBN",
          "value": "1234567890123"
        }
      ],
      "bulk_pricing_rules": [
        {
          "id": 0,
          "quantity_min": 10,
          "quantity_max": 50,
          "type": "price",
          "amount": 10
        }
      ],
      "images": [
        {
          "image_file": "string",
          "is_thumbnail": true,
          "sort_order": -2147483648,
          "description": "string",
          "image_url": "string",
          "id": 0,
          "product_id": 0,
          "url_zoom": "string",
          "url_standard": "string",
          "url_thumbnail": "string",
          "url_tiny": "string",
          "date_modified": "2019-08-24T14:15:22Z"
        }
      ],
      "videos": [
        {
          "title": "Writing Great Documentation",
          "description": "A video about documenation",
          "sort_order": 1,
          "type": "youtube",
          "video_id": "z3fRu9pkuXE",
          "id": 0,
          "product_id": 0,
          "length": "string"
        }
      ]
    }
  },
  "properties": {
    "name": {
      "maxLength": 250,
      "minLength": 1,
      "type": "string",
      "description": "A unique product name.\n",
      "example": "Smith Journal 13",
      "x-required": [
        "post"
      ]
    },
    "type": {
      "type": "string",
      "description": "The product type. One of: `physical` - a physical stock unit, `digital` - a digital download.\n",
      "example": "physical",
      "enum": [
        "physical",
        "digital"
      ],
      "x-required": [
        "post"
      ]
    },
    "sku": {
      "maxLength": 255,
      "minLength": 0,
      "type": "string",
      "description": "A unique user-defined alphanumeric product code/stock keeping unit (SKU).\n",
      "example": "SM-13"
    },
    "description": {
      "type": "string",
      "description": "The product description, which can include HTML formatting.\n",
      "example": "<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>"
    },
    "weight": {
      "maximum": 9999999999,
      "minimum": 0,
      "type": "number",
      "description": "Weight of the product, which can be used when calculating shipping costs. This is based on the unit set on the store\n",
      "format": "float"
    },
    "width": {
      "maximum": 9999999999,
      "minimum": 0,
      "type": "number",
      "description": "Width of the product, which can be used when calculating shipping costs.\n",
      "format": "float"
    },
    "depth": {
      "maximum": 9999999999,
      "minimum": 0,
      "type": "number",
      "description": "Depth of the product, which can be used when calculating shipping costs.\n",
      "format": "float"
    },
    "height": {
      "maximum": 9999999999,
      "minimum": 0,
      "type": "number",
      "description": "Height of the product, which can be used when calculating shipping costs.\n",
      "format": "float"
    },
    "price": {
      "minimum": 0,
      "type": "number",
      "description": "The price of the product. The price should include or exclude tax, based on the store settings.\n",
      "format": "float"
    },
    "cost_price": {
      "minimum": 0,
      "type": "number",
      "description": "The cost price of the product. Stored for reference only; it is not used or displayed anywhere on the store.\n",
      "format": "float"
    },
    "retail_price": {
      "minimum": 0,
      "type": "number",
      "description": "The retail cost of the product. If entered, the retail cost price will be shown on the product page.\n",
      "format": "float"
    },
    "sale_price": {
      "minimum": 0,
      "type": "number",
      "description": "If entered, the sale price will be used instead of value in the price field when calculating the product\u02bcs cost.\n",
      "format": "float"
    },
    "map_price": {
      "type": "number",
      "description": "Minimum Advertised Price"
    },
    "tax_class_id": {
      "maximum": 255,
      "minimum": 0,
      "type": "number",
      "description": "The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.)\n"
    },
    "product_tax_code": {
      "maxLength": 255,
      "minLength": 0,
      "type": "string",
      "description": "Tax Codes, such as AvaTax System Tax Codes, identify products and services that fall into special sales-tax categories. By using these codes, merchants who subscribe to a tax provider integration, such as BigCommerce\u02bcs Avalara Premium, can calculate sales taxes more accurately. Stores without a tax provider will ignore the code when calculating sales tax. Do not pass more than one code. The codes are case-sensitive. For details, please see the tax provider\u02bcs documentation.\n"
    },
    "categories": {
      "type": "array",
      "description": "An array of IDs for the categories to which this product belongs. When updating a product, if an array of categories is supplied, all product categories will be overwritten. Does not accept more than 1,000 ID values.\n",
      "x-required": [
        "post"
      ],
      "items": {
        "type": "number"
      },
      "maximum": 1000,
      "minimum": 0
    },
    "brand_id": {
      "maximum": 1000000000,
      "minimum": 0,
      "type": "integer",
      "description": "You can add a product to an existing brand during a product /PUT or /POST. Use either the `brand_id` or the `brand_name` field. The response body can include `brand_id`.\n"
    },
    "brand_name": {
      "type": "string",
      "description": "You can create the brand during a product PUT or POST request. If the brand already exists, the product /PUT or /POST request adds the product to the brand. If not, the product /PUT or /POST request creates the brand and then adds the product to the brand. Brand name is not case-sensitive; \"Common Good\" and \"Common good\" are the same. Use either the `brand_id` or the `brand_name` field. The response body does not include `brand_name`.",
      "example": "Common Good"
    },
    "inventory_level": {
      "maximum": 2147483647,
      "minimum": 0,
      "type": "integer",
      "description": "Current inventory level of the product. You must track inventory by _product_ for this to take effect (see the `inventory_tracking` field). The Catalog API returns the inventory for only the default location.\n\nThe inventory for a product cannot exceed 2,147,483,647 in the catalog. If you exceed the limit, the store sets the inventory level to the limit.\n\nThe Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). "
    },
    "inventory_warning_level": {
      "maximum": 2147483647,
      "minimum": 0,
      "type": "integer",
      "description": "Inventory warning level for the product. When the product\u02bcs inventory level drops below the warning level, the store owner will be informed. Simple inventory tracking must be enabled (see the `inventory_tracking` field) for this to take any effect.\n"
    },
    "inventory_tracking": {
      "type": "string",
      "description": "The type of inventory tracking for the product. Values are: `none` - inventory levels will not be tracked; `product` - inventory levels will be tracked using the `inventory_level` and `inventory_warning_level` fields; `variant` - inventory levels will be tracked based on variants, which maintain their own warning levels and inventory levels.\n",
      "enum": [
        "none",
        "product",
        "variant"
      ]
    },
    "fixed_cost_shipping_price": {
      "minimum": 0,
      "type": "number",
      "description": "A fixed shipping cost for the product. If defined, this value will be used during checkout instead of normal shipping-cost calculation.\n",
      "format": "float"
    },
    "is_free_shipping": {
      "type": "boolean",
      "description": "Flag used to indicate whether the product has free shipping. If `true`, the shipping cost for the product will be zero.\n"
    },
    "is_visible": {
      "type": "boolean",
      "description": "Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the product will be displayed. If `false`, the product will be hidden from view.\n"
    },
    "is_featured": {
      "type": "boolean",
      "description": "Flag to determine whether the product should be included in the `featured products` panel when viewing the store.\n"
    },
    "related_products": {
      "type": "array",
      "description": "An array of IDs for the related products.\n",
      "items": {
        "type": "integer"
      }
    },
    "warranty": {
      "maxLength": 65535,
      "minLength": 0,
      "type": "string",
      "description": "Warranty information displayed on the product page. Can include HTML formatting.\n"
    },
    "bin_picking_number": {
      "maxLength": 255,
      "minLength": 0,
      "type": "string",
      "description": "The BIN picking number for the product.\n"
    },
    "layout_file": {
      "maxLength": 500,
      "minLength": 0,
      "type": "string",
      "description": "The layout template file used to render this product category. This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations).\n"
    },
    "upc": {
      "type": "string",
      "maxLength": 32,
      "minLength": 0,
      "description": "The product UPC code, which is used in feeds for shopping comparison sites and external channel integrations.\n"
    },
    "search_keywords": {
      "maxLength": 65535,
      "minLength": 0,
      "type": "string",
      "description": "A comma-separated list of keywords that can be used to locate the product when searching the store.\n"
    },
    "availability_description": {
      "maxLength": 255,
      "minLength": 0,
      "type": "string",
      "description": "Availability text displayed on the checkout page, under the product title. Tells the customer how long it will normally take to ship this product, such as: 'Usually ships in 24 hours.'\n"
    },
    "availability": {
      "type": "string",
      "description": "Availability of the product. (Corresponds to the product\u02bcs [Purchasability](https://support.bigcommerce.com/s/article/Adding-Products-v3?language=en_US#sections) section in the control panel.) Supported values: `available` - the product is available for purchase; `disabled` - the product is listed on the storefront, but cannot be purchased; `preorder` - the product is listed for pre-orders.\n",
      "enum": [
        "available",
        "disabled",
        "preorder"
      ]
    },
    "gift_wrapping_options_type": {
      "type": "string",
      "description": "Type of gift-wrapping options. Values: `any` - allow any gift-wrapping options in the store; `none` - disallow gift-wrapping on the product; `list` \u2013 provide a list of IDs in the `gift_wrapping_options_list` field.\n\nAlways included in the response body; not applicable for the `include_fields` and `exclude_fields` query parameters.\n",
      "enum": [
        "any",
        "none",
        "list"
      ]
    },
    "gift_wrapping_options_list": {
      "type": "array",
      "description": "A list of gift-wrapping option IDs.\n\nAlways included in the response body; not applicable for the `include_fields` and `exclude_fields` query parameters.\n",
      "items": {
        "type": "integer"
      }
    },
    "sort_order": {
      "type": "integer",
      "description": "Priority to give this product when included in product lists on category pages and in search results. Lower integers will place the product closer to the top of the results.\n",
      "maximum": 2147483647,
      "minimum": -2147483648
    },
    "condition": {
      "type": "string",
      "description": "The product condition. Will be shown on the product page if the `is_condition_shown` field\u02bcs value is `true`. Possible values: `New`, `Used`, `Refurbished`.\n",
      "enum": [
        "New",
        "Used",
        "Refurbished"
      ]
    },
    "is_condition_shown": {
      "type": "boolean",
      "description": "Flag used to determine whether the product condition is shown to the customer on the product page.\n"
    },
    "order_quantity_minimum": {
      "maximum": 1000000000,
      "minimum": 0,
      "type": "integer",
      "description": "The minimum quantity an order must contain, to be eligible to purchase this product.\n"
    },
    "order_quantity_maximum": {
      "maximum": 1000000000,
      "minimum": 0,
      "type": "integer",
      "description": "The maximum quantity an order can contain when purchasing the product.\n"
    },
    "page_title": {
      "maxLength": 255,
      "minLength": 0,
      "type": "string",
      "description": "Custom title for the product page. If not defined, the product name will be used as the meta title.\n"
    },
    "meta_keywords": {
      "type": "array",
      "maxLength": 65535,
      "minLength": 0,
      "description": "Custom meta keywords for the product page. If not defined, the store\u02bcs default keywords will be used.\n",
      "items": {
        "type": "string"
      }
    },
    "meta_description": {
      "maxLength": 65535,
      "minLength": 0,
      "type": "string",
      "description": "Custom meta description for the product page. If not defined, the store\u02bcs default meta description will be used.\n"
    },
    "view_count": {
      "maximum": 1000000000,
      "minimum": 0,
      "type": "integer",
      "description": "The number of times the product has been viewed.\n",
      "deprecated": true
    },
    "preorder_release_date": {
      "type": "string",
      "description": "Pre-order release date. See the `availability` field for details on setting a product\u02bcs availability to accept pre-orders.\n",
      "format": "date-time",
      "nullable": true
    },
    "preorder_message": {
      "maxLength": 255,
      "minLength": 0,
      "type": "string",
      "description": "Custom expected-date message to display on the product page. If undefined, the message defaults to the storewide setting. Can contain the `%%DATE%%` placeholder, which will be substituted for the release date.\n"
    },
    "is_preorder_only": {
      "type": "boolean",
      "description": "If set to true then on the preorder release date the preorder status will automatically be removed.\nIf set to false, then on the release date the preorder status **will not** be removed. It will need to be changed manually either in the\ncontrol panel or using the API. Using the API set `availability` to `available`.\n"
    },
    "is_price_hidden": {
      "type": "boolean",
      "description": "False by default, indicating that this product\u02bcs price should be shown on the product page. If set to `true`, the price is hidden. (NOTE: To successfully set `is_price_hidden` to `true`, the `availability` value must be `disabled`.)\n"
    },
    "price_hidden_label": {
      "maxLength": 200,
      "minLength": 0,
      "type": "string",
      "description": "By default, an empty string. If `is_price_hidden` is `true`, the value of `price_hidden_label` is displayed instead of the price. (NOTE: To successfully set a non-empty string value with `is_price_hidden` set to `true`, the `availability` value must be `disabled`.)\n"
    },
    "custom_url": {
      "$ref": "#/components/schemas/customUrl_Full"
    },
    "open_graph_type": {
      "type": "string",
      "description": "Type of product, defaults to `product`.\n",
      "enum": [
        "product",
        "album",
        "book",
        "drink",
        "food",
        "game",
        "movie",
        "song",
        "tv_show"
      ]
    },
    "open_graph_title": {
      "type": "string",
      "description": "Title of the product, if not specified the product name will be used instead.\n"
    },
    "open_graph_description": {
      "type": "string",
      "description": "Description to use for the product, if not specified then the meta_description will be used instead.\n"
    },
    "open_graph_use_meta_description": {
      "type": "boolean",
      "description": "Flag to determine if product description or open graph description is used.\n"
    },
    "open_graph_use_product_name": {
      "type": "boolean",
      "description": "Flag to determine if product name or open graph name is used.\n"
    },
    "open_graph_use_image": {
      "type": "boolean",
      "description": "Flag to determine if product image or open graph image is used.\n"
    },
    "gtin": {
      "type": "string",
      "description": "Global Trade Item Number"
    },
    "mpn": {
      "type": "string",
      "description": "Manufacturer Part Number"
    },
    "date_last_imported": {
      "type": "string",
      "description": "the date when the Product had been imported"
    },
    "reviews_rating_sum": {
      "type": "integer",
      "description": "The total (cumulative) rating for the product.\n",
      "example": 3
    },
    "reviews_count": {
      "type": "integer",
      "description": "The number of times the product has been rated.\n",
      "example": 4
    },
    "total_sold": {
      "type": "integer",
      "description": "The total quantity of this product sold.\n",
      "example": 80
    },
    "custom_fields": {
      "type": "array",
      "minimum": 0,
      "maximum": 255,
      "description": "200 maximum custom fields per product. 255 maximum characters per custom field. The default rate limit for this endpoint is 40 concurrent requests.",
      "items": {
        "$ref": "#/components/schemas/productCustomField_Put"
      }
    },
    "bulk_pricing_rules": {
      "type": "array",
      "items": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "description": "Unique ID of the *Bulk Pricing Rule*. Read-Only.",
                "readOnly": true
              }
            },
            "required": [
              "id"
            ]
          },
          {
            "$ref": "#/components/schemas/bulkPricingRule_Full"
          }
        ]
      }
    },
    "images": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/productImage_Full"
      }
    },
    "videos": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/productVideo_Full"
      }
    },
    "variants": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/productVariant_Full"
      }
    }
  },
  "required": [
    "name",
    "type",
    "weight",
    "price"
  ]
}