API Product Integration

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

Endpoint: POST /products Description: Submits a product for asynchronous processing. A callback will notify success or failure after processing.

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, etc.
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

{
  "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

Endpoint: PATCH /products 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

{
  "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.

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.