# Product format

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

API 4.0

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](/developers/api-reference/products/create), [List products](/developers/api-reference/products/list), [Get product details](/developers/api-reference/products/retrieve), and [Update a product](/developers/api-reference/products/update).

## Product

Selected fields of a `Product`:

```json
{
  "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](#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](#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](/developers/api-reference/products/retrieve) 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](/developers/orders/format#order-item).