# Add new products and variants

> Create products by SKU with names, price, category, brand, pictures and opening stock, and make sizes or colours variants of a main product.

New products go through the same call as updates: a SKU the shop doesn't have yet is created.

- Connector: `preview_catalog_update`, then `apply_catalog_update` (permission `catalog:write`).
- API: `POST /products/upsert`.

## Required fields for a new SKU

| Field | Notes |
|---|---|
| `sku` | your product code, up to 100 characters |
| `name` | a string (Thai) or `{ "th": "…", "en": "…" }` |
| `price` | THB |
| `category` | a name from `list_categories` / `GET /categories` |
| `brand` | a new brand is added to the shop's list |

Optional: `description`, `usage_information` (how to use or care for it), `images` (picture links, see below), `stock` (the opening count on the shelf; it needs the `stock:write` permission as well as `catalog:write`), `parent_sku` (makes it a variant).

## Example

```json
{
  "dry_run": true,
  "products": [
    { "sku": "TM-010", "name": { "th": "รถดับเพลิงโทมิก้า", "en": "Tomica fire engine" },
      "price": 189, "category": "Toys", "brand": "Tomica", "stock": 12 }
  ]
}
```

## Pictures

Give a product's pictures as links in `images`: 1 to 7, the first is the main picture. They replace the product's pictures, on a new product or an existing one.

- Each picture is downloaded and copied onto SellerSideKick, so the link must be a public web address of the picture itself (JPEG, PNG or WebP, up to 15 MB), not a web page that shows it.
- A picture that can't be fetched makes its row an error, and nothing in that row is saved. A dry run checks each address without downloading it.
- Sending the same links again changes nothing.
- Pictures you have as files (API only): upload them with `POST /images` (`multipart/form-data`, field `images`, up to 7 files of 10 MB each). It answers each file's link; put those in `images`.

```json
{
  "dry_run": true,
  "products": [
    { "sku": "TM-011", "name": "รถตำรวจโทมิก้า", "price": 129, "category": "Toys", "brand": "Tomica",
      "images": ["https://www.example.com/photos/tm-011-front.jpg", "https://www.example.com/photos/tm-011-box.jpg"] }
  ]
}
```

## Variants

A variant is a size, colour or other option of a main product. Create the main product and give each variant `parent_sku`. The main product may be created in the same request:

```json
{
  "products": [
    { "sku": "SHIRT-01", "name": "เสื้อยืดลายแมว", "price": 290, "category": "Clothing", "brand": "Nichi" },
    { "sku": "SHIRT-01-M", "name": "เสื้อยืดลายแมว ไซซ์ M", "price": 290, "category": "Clothing", "brand": "Nichi", "parent_sku": "SHIRT-01", "stock": 20 },
    { "sku": "SHIRT-01-L", "name": "เสื้อยืดลายแมว ไซซ์ L", "price": 290, "category": "Clothing", "brand": "Nichi", "parent_sku": "SHIRT-01", "stock": 15 }
  ]
}
```

- `parent_sku` must name a main product on your SellerSideKick store, or one created in the same request. It can't be another variant or a product that exists only on a marketplace.
- `stock` and `parent_sku` are for **new** products only. Sending them for an existing SKU is an error row; change stock with [Update stock counts](https://docs.sellersidekick.ai/update-stock).

## Common error rows

- **Unknown category:** map the sheet's category to one of the shop's names.
- **The SKU exists only on a marketplace:** add it to the SellerSideKick store from the dashboard first.
- **The same SKU twice** in one request: keep one row per SKU.
- **Missing required field** on a new SKU: add `name`, `price`, `category` and `brand`.
- **A picture can't be used:** the message names the picture and why (not a public address, the server answered 404, larger than 15 MB). Fix or drop that link.

New products appear on the SellerSideKick store and the chat bot can recommend them. A new product's opening stock reaches a marketplace listing once a listing with the same SKU is linked to it.
