SubizDeveloper Docs
Products

API 4.0

Product format

Understand the product object: price, stock, availability, variants, and images.

A Product is an item in your Subiz catalog. Order items can be linked to catalog products. This page describes the product object. All IDs and values below are illustrative.

To work with products, see Create a product, List products, Get product details, and Update a product.

Product

Selected fields of a Product:

{
  "id": "product_example",
  "account_id": "account_example",
  "source_id": "shop-sku-mug-01",
  "name": "Ceramic mug",
  "sku": "MUG-01",
  "barcode": "8930000000001",
  "description": "A 350 ml ceramic mug.",
  "category": "kitchen",
  "brand": "Example Home",
  "url": "https://shop.example.com/products/ceramic-mug",
  "price": 120000,
  "market_price": 150000,
  "currency": "VND",
  "stock": 25,
  "availability": "in_stock",
  "visibility": "published",
  "condition": "new",
  "images": [
    "https://example.com/images/mug.jpg"
  ],
  "props": [
    {
      "key": "color",
      "value": "white"
    }
  ],
  "product_group_id": "product_example",
  "created": 1763107200000,
  "updated": 1763107200000
}
Field Type Description
id string Subiz product ID. Generated by Subiz.
source_id string ID of the product in your system. Used to avoid duplicates.
name string Required. Product name.
sku, barcode string Stock-keeping unit and barcode.
description string Product description.
category string Category. At most 255 bytes.
brand string Brand name.
url string Product page on your website.
price number Selling price.
market_price number Reference price before discount, such as a list price.
currency string Currency of the prices.
stock integer Units in stock.
availability string See Availability.
visibility string published (default) or hidden.
condition string new, refurbished, or used.
image, images string, array Main image URL and additional image URLs.
videos array Video URLs.
props array Attributes as key/value pairs, such as color or size.
note string Internal note.
weight, weight_unit number, string Weight and its unit, g or kg.
dimension_length, dimension_width, dimension_height number Package size.
product_group_id string Variant group. See Variants.
created, updated integer Unix timestamps in milliseconds. Set by Subiz.
created_by, updated_by string ID of the agent who created or last changed the product. Set by Subiz.

Empty fields are omitted, and the object has more fields than shown.

Availability

availability is one of these values. An empty value is allowed.

Value Meaning
in_stock In stock.
out_of_stock Out of stock.
online_only Sold online only.
pre_order Available for pre-order.
pre_sale Available for pre-sale.
sold_out Sold out.

Subiz lowercases and trims the value. Any other value is rejected.

Images

When you send a new image URL in image or images, Subiz downloads it, stores a resized JPEG copy, and saves the copy’s URL instead of yours. The image URLs you read back are therefore different from the ones you sent. If an image cannot be downloaded, the request fails.

Variants

Variants of the same product, such as sizes or colors, share a product_group_id. A product without a group gets its own id as product_group_id.

When you save a product, Subiz copies these fields to every other product in the same group: name, description, url, handle, category, brand, note, condition, visibility, images, videos, and options. Keep fields that differ per variant, such as sku, price, stock, and props, on each variant.

Get product details also returns num_variants and up to five other_variants.

Products in orders

An order item holds a copy of the product at the time of the order. Changing a product does not change existing orders. See Order format.