> For the complete documentation index, see [llms.txt](https://docs.sizebay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sizebay.com/fashion-hub/product-integration-api.md).

# Product Integration (API)

This page explains how to create and update product data using the AI Image Service API by Sizebay. You can also explore and test the endpoints in the Swagger documentation.

### 1. Create Product

<mark style="color:green;">`POST`</mark> `https://ai-image-service-dev.internalsizebay.com/products`\
\
**Description:** Submits a product for asynchronous processing. A callback will notify success or failure after processing.&#x20;

#### Headers

| Header      | Type   | Required | Description                |
| ----------- | ------ | -------- | -------------------------- |
| `x-api-key` | string | ✅        | API key for authentication |

#### Body Parameters

| Field                     | Type   | Required | Description                                  |
| ------------------------- | ------ | -------- | -------------------------------------------- |
| `tenantId`                | number | ✅        | Tenant (client) ID                           |
| `collectionName`          | string | ✅        | Product collection name                      |
| `processType`             | string | ✅        | Type: `SIMILAR`, `COMPLEMENTARY`, `ALL`      |
| `brandName`               | string | ✅        | Brand name                                   |
| `specialtyFromPersona`    | string | ✅        | Product style (e.g., "casual fashion")       |
| `productItem.id`          | string | ✅        | Unique ID of the variant (e.g. color + size) |
| `productItem.itemGroupId` | string | ✅        | Common ID for all variants of a product      |
| `localizations`           | object | ✅        | Language-specific title, link, availability  |
| `pricing`                 | object | ✅        | Prices by currency (price, salePrice, date)  |
| `productType`             | string | ✅        | Category hierarchy                           |
| `imageLink`               | string | ✅        | Main image of the variant                    |
| `additionalImageLinks`    | array  | Optional | Additional images for the variant            |
| `gender`                  | string | ✅        | `male`, `female`, `unisex`                   |
| `ageGroup`                | string | ✅        | `adult`, `kids`                              |
| `size`                    | string | ✅        | Sizes, comma-separated (e.g., `S,M,L`)       |
| `sizeSystem`              | string | ✅        | Size system (`BR`, `US`, etc.)               |
| `color`                   | string | ✅        | Product color                                |
| `gtin`                    | string | Optional | Barcode (Global Trade Item Number)           |

#### Callback Notification

After processing, a POST request is sent to your callback URL:

```
{
  "productId": "380145e972ee",
  "status": "success",
  "message": "Required only if status is 'error'"
}
```

> Header `Authorization` will be included in the request.

#### Payload Example

```json
{
  "tenantId": 1234,
  "collectionName": "sizebay-collection",
  "processType": "SIMILAR",
  "brandName": "Sizebay",
  "specialtyFromPersona": "casual fashion",
  "productItem": {
    "id": "380145e972ee",
    "itemGroupId": "edb1e435d172",
    "localizations": {
      "en-US": {
        "title": "Classic White T-Shirt",
        "availability": "in stock",
        "link": "www.example.com/us/product"
      },
      "pt-BR": {
        "title": "Camiseta Branca",
        "availability": "in stock",
        "link": "www.example.com/br/product"
      }
    },
    "pricing": {
      "USD": {
        "price": 25,
        "salePrice": 19.99,
        "salePriceEffectiveDate": "2024-06-10T00:00:00/2024-06-20T23:59:59"
      },
      "BRL": {
        "price": 99.9,
        "salePrice": 79.9,
        "salePriceEffectiveDate": "2024-06-10T00:00:00/2024-06-20T23:59:59"
      }
    },
    "productType": "KIDS > MALE > BOTTOMS",
    "brand": "Sizebay",
    "imageLink": "www.example.com/image.jpg",
    "additionalImageLinks": [
      "www.example.com/image.jpg"
    ],
    "gender": "unisex",
    "ageGroup": "adult",
    "size": "XS,S,M,L,XL",
    "sizeSystem": "BR",
    "color": "Blue",
    "gtin": "00012345678905"
  }
}
```

#### Responses

| Status | Meaning                         |
| ------ | ------------------------------- |
| 202    | Product accepted for processing |
| 400    | Invalid or missing fields       |
| 500    | Internal server error           |

### 2. Update Product

<mark style="color:green;">`PATCH`</mark> `https://ai-image-service-dev.internalsizebay.com/products`<br>

**Description:** Updates an existing product’s title, availability and pricing.

#### Headers

| Header      | Type   | Required | Description                |
| ----------- | ------ | -------- | -------------------------- |
| `x-api-key` | string | ✅        | API key for authentication |

#### Body Parameters

| Field            | Type   | Required | Description                             |
| ---------------- | ------ | -------- | --------------------------------------- |
| `tenantId`       | number | ✅        | Tenant ID                               |
| `collectionName` | string | ✅        | Collection name                         |
| `productId`      | string | ✅        | ID of the product to update             |
| `localizations`  | object | ✅        | Updated title & availability per locale |
| `pricing`        | object | ✅        | Updated prices per currency             |

#### Payload Example

```json
{
  "tenantId": 123,
  "collectionName": "string",
  "productId": "FSW012345",
  "localizations": {
    "en-US": {
      "title": "Classic White T-Shirt",
      "availability": "in stock"
    },
    "pt-BR": {
      "title": "Camiseta Branca",
      "availability": "in stock"
    }
  },
  "pricing": {
    "USD": {
      "price": 25,
      "salePrice": 19.99,
      "salePriceEffectiveDate": "2024-06-10T00:00:00/2024-06-20T23:59:59"
    },
    "BRL": {
      "price": 99.9,
      "salePrice": 79.9,
      "salePriceEffectiveDate": "2024-06-10T00:00:00/2024-06-20T23:59:59"
    }
  }
}
```

#### Responses

| Status | Meaning                      |
| ------ | ---------------------------- |
| 200    | Product updated successfully |
| 400    | Invalid or missing fields    |
| 404    | Product not found            |
| 500    | Internal server error        |

### 3. Swagger – Interactive API Explorer

To simplify integration and testing, you can access the official [**Swagger API Reference**](https://ai-image-service-dev.internalsizebay.com/api/docs)**.**

What you can do there:

| Feature           | Description                                                                 |
| ----------------- | --------------------------------------------------------------------------- |
| Explore endpoints | View all available endpoints with descriptions and example payloads         |
| Test requests     | Use the “Try it out” button to send test requests directly from the browser |
| Validate payloads | Ensure your request structure matches the API’s expected schema             |
| Check responses   | See example success and error responses                                     |
| Use your API key  | Authenticate and test using your tenant’s `x-api-key`                       |

> This tool is ideal for developers and integrators during setup, debugging, and ongoing maintenance.