Product Variant

Version 1.0

The Product Variant Entity enhances the Product Entity by managing specific product variations, such as sizes, colors, and configurations. It captures crucial details like variant pricing and inventory levels. This dynamic entity empowers merchants to present diverse product options, ensuring a customizable shopping experience. By seamlessly integrating with the Product Entity, it contributes to a cohesive system, maintaining consistency and accuracy across channels. The Product Variant Entity plays a pivotal role in enriching the customer experience and facilitating successful e-commerce operations.

# Endpoints
POST
/v1/products/987654321/variants# Create a product variant for a single product
GET
/v1/products/987654321/variants/123456789# Retrieve a single product variant for a specific product
GET
/v1/products/987654321/variants/count# Retrieve a count of product variants for a specific product
PATCH
/v1/products/987654321/variants/123456789# Update a single product variant for a specific product
DELETE
/v1/products/987654321/variants/123456789# Delete a single product variant for a specific product

Product Variant Entity

  • Name
    variant_id
    Type
    string
    Required
    Description

    Every product variant is assigned a unique identifier - an unsigned 64-bit integer known as the Variant ID. This specific number is exclusive and distinct across the entire Qooly platform.

  • Name
    product_id
    Type
    string
    Required
    Description

    This property indicates the Product ID to which the variant belongs. It establishes a connection between the variant and its parent product.

  • Name
    name
    Type
    varchar(255)
    Required
    Description

    This property indicates the name of the product variant.

  • Name
    sku
    Type
    varchar(64)
    Required
    Description

    This property indicates the Stock Keeping Unit (SKU) of the product variant. It serves as a unique identifier for inventory tracking.

  • Name
    price
    Type
    decimal(10,2)
    Required
    Description

    This property indicates the price of the product variant.

  • Name
    currency
    Type
    varchar(3)
    Required
    Description

    This property indicates the currency code (ISO 4217) used for pricing the product variant.

  • Name
    inventory
    Type
    int
    Default: 0
    Description

    This property indicates the available inventory quantity of the product variant.

  • Name
    weight
    Type
    decimal(10,2)
    Description

    This property indicates the weight of the product variant.

  • Name
    weight_unit
    Type
    varchar(8)
    Description

    This property indicates the weight unit of the product variant.

  • Name
    size_unit
    Type
    varchar(8)
    Description

    This property indicates the size unit of the product variant, used for length, width, and height.

  • Name
    length
    Type
    decimal(10,2)
    Description

    This property indicates the length of the product variant.

  • Name
    width
    Type
    decimal(10,2)
    Description

    This property indicates the width of the product variant.

  • Name
    height
    Type
    decimal(10,2)
    Description

    This property indicates the height of the product variant.

  • Name
    is_published
    Type
    boolean
    Default: FALSE
    Description

    This property indicates whether the product variant is published to the platforms or not. If the product variant is published, the value is true. If the product variant is not published, the value is false.

  • Name
    status
    Type
    varchar(16)
    Default: DRAFT
    Description

    This property indicates the status of the product variant.

    DraftThe product variant is in draft mode. This is the default status for new variants.
    EnabledThe product variant is enabled. This means that the variant is available for purchase through channels.
    DisabledThe product variant is disabled. This means that the variant is not available for purchase through channels.
    ArchivedThe product variant is archived for future reference.
  • Name
    metadata_id
    Type
    foreignId
    Description

    This serves as a unique, distinct identifier, specific to each metadata in Qooly's system. As a distinct numerical value, the 'metadata_id' provides a reliable reference to every individual metadata, irrespective of the number of metadata on the platform.

  • Name
    country_of_origin
    Type
    varchar(2)
    Description

    This property indicates the country of origin of the product variant. This is a two-letter country code.

  • Name
    commodity_description
    Type
    varchar(255)
    Description

    This property indicates the commodity description of the product variant.

  • Name
    taxable
    Type
    boolean
    Default: FALSE
    Description

    This property indicates whether the product variant is taxable or not. If the product variant is taxable, the value is true. If the product variant is not taxable, the value is false.

  • Name
    tax_code
    Type
    varchar(16)
    Description

    This property indicates the tax code of the product variant.

  • Name
    created_at
    Type
    timestamp
    Description

    This property indicates the time in ISO 8601 format when the product variant was created.

  • Name
    updated_at
    Type
    timestamp
    Description

    This property indicates the time in ISO 8601 format when the product variant was last updated.

  • Name
    created_by
    Type
    foreignId
    Description

    This property indicates the user who created the product variant.

  • Name
    updated_by
    Type
    foreignId
    Description

    This property indicates the user who updated the product variant recently.

The Product Variant resource

JSON
{
  "variant_id": "987654321",
  "product_id": "123456789",
  "name": "Variant A",
  "sku": "VAR123",
  "price": 49.99,
  "currency": "USD",
  "inventory": 100,
  "weight": 0.75,
  "weight_unit": "kg",
  "size_unit": "cm",
  "length": 5.0,
  "width": 3.0,
  "height": 10.0,
  "is_published": false,
  "status": "DRAFT",
  "metadata_id": "456789012",
  "country_of_origin": "US",
  "commodity_description": "A high-quality electronic gadget.",
  "taxable": false,
  "tax_code": "TAX123",
  "created_at": "2024-01-19T10:45:00Z",
  "updated_at": "2024-01-19T12:30:00Z",
  "created_by": "789012345",
  "updated_by": "987654321"
}

Create a product variant

This endpoint allows you to create a single product variant for a specific product.

Required Fields

  • Name
    name
    Type
    varchar(255)
    Required
    Description

    This property indicates the name of the product variant.

  • Name
    sku
    Type
    varchar(64)
    Description

    This property indicates the stock keeping unit (SKU) of the product variant.

  • Name
    price
    Type
    decimal
    Required
    Description

    This property indicates the price of the product variant.

Examples

Create a single product variant

POST
/v1/products/987654321/variants
curl --request POST \
  --url https://api.qooly.io/v1/products/987654321/variants \
  --header 'Content-Type: application/json' \
  --data '{
    "product_id": "123456789",
    "name": "Variant A",
    "sku": "VAR123",
    "price": 49.99,
    "currency": "USD",
    "inventory": 100,
    "weight": 0.75,
    "weight_unit": "kg",
    "size_unit": "cm",
    "length": 5.0,
    "width": 3.0,
    "height": 10.0,
    "is_published": false,
    "status": "DRAFT",
    "metadata_id": "456789012",
    "country_of_origin": "US",
    "commodity_description": "A high-quality electronic gadget.",
    "taxable": false,
    "tax_code": "TAX123"
  }'

Create a single product variant

POST
/v1/products/987654321/variants
curl --request POST \
  --url https://api.qooly.io/v1/products/987654321/variants \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Variant A",
    "sku": "VAR123",
    "price": 49.99,
    "currency": "USD",
    "inventory": 100,
    "weight": 0.75,
    "weight_unit": "kg",
    "size_unit": "cm",
    "length": 5.0,
    "width": 3.0,
    "height": 10.0,
    "is_published": false,
    "status": "DRAFT",
    "metadata_id": "456789012",
    "country_of_origin": "US",
    "commodity_description": "A high-quality electronic gadget.",
    "taxable": false,
    "tax_code": "TAX123"
  }'
JSON
{
  "variant_id": "987654321",
  "name": "Variant A",
  "sku": "VAR123",
  "price": 49.99,
  "currency": "USD",
  "inventory": 100,
  "weight": 0.75,
  "weight_unit": "kg",
  "size_unit": "cm",
  "length": 5.0,
  "width": 3.0,
  "height": 10.0,
  "is_published": false,
  "status": "DRAFT",
  "metadata_id": "456789012",
  "country_of_origin": "US",
  "commodity_description": "A high-quality electronic gadget.",
  "taxable": false,
  "tax_code": "TAX123",
  "created_at": "2024-01-19T10:45:00Z",
  "updated_at": "2024-01-19T12:30:00Z",
  "created_by": "789012345",
  "updated_by": "987654321"
}

Retrieve a single product variant

This endpoint allows you to retrieve a single product variant.

Required Parameters

  • Name
    product_id
    Type
    string
    Required
    Description

    This property indicates the ID of the product to which the variant belongs.

  • Name
    variant_id
    Type
    string
    Required
    Description

    This property indicates the ID of the product variant to be retrieved.

Examples

Retrieve a single product variant

GET
/v1/products/987654321/variants/123456789
curl --request GET \
  --url https://api.qooly.io/v1/products/987654321/variants/123456789

Retrieve a single product variant

GET
/v1/products/987654321/variants/123456789
curl --request GET \
  --url https://api.qooly.io/v1/products/987654321/variants/123456789
JSON
{
  "variant_id": "123456789",
  "product_id": "987654321",
  "name": "Variant A",
  "sku": "VAR123",
  "price": 49.99,
  "currency": "USD",
  "inventory": 100,
  "weight": 0.75,
  "weight_unit": "kg",
  "size_unit": "cm",
  "length": 5.0,
  "width": 3.0,
  "height": 10.0,
  "is_published": false,
  "status": "DRAFT",
  "metadata_id": "456789012",
  "country_of_origin": "US",
  "commodity_description": "A high-quality electronic gadget.",
  "taxable": false,
  "tax_code": "TAX123",
  "created_at": "2024-01-19T10:45:00Z",
  "updated_at": "2024-01-19T12:30:00Z",
  "created_by": "789012345",
  "updated_by": "987654321"
}

Update a single product variant

This endpoint allows you to update a single product variant.

Required Parameters

  • Name
    product_id
    Type
    string
    Required
    Description

    This property indicates the ID of the product to which the variant belongs.

  • Name
    variant_id
    Type
    string
    Required
    Description

    This property indicates the ID of the product variant to be updated.

Examples

Update a single product variant

PATCH
/v1/products/987654321/variants/123456789
curl --request PATCH \
  --url https://api.qooly.io/v1/products/987654321/variants/123456789 \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "New Variant Name",
    "price": 59.99,
    "inventory": 150
  }'
JSON
{
  "variant_id": "123456789",
  "product_id": "987654321",
  "name": "New Variant Name",
  "sku": "VAR123",
  "price": 59.99,
  "currency": "USD",
  "inventory": 150,
  "weight": 0.75,
  "weight_unit": "kg",
  "size_unit": "cm",
  "length": 5.0,
  "width": 3.0,
  "height": 10.0,
  "is_published": false,
  "status": "DRAFT",
  "metadata_id": "456789012",
  "country_of_origin": "US",
  "commodity_description": "A high-quality electronic gadget.",
  "taxable": false,
  "tax_code": "TAX123",
  "created_at": "2024-01-19T10:45:00Z",
  "updated_at": "2024-01-19T14:30:00Z",
  "created_by": "789012345",
  "updated_by": "987654321"
}

Update a single product variant

PATCH
/v1/products/987654321/variants/123456789
curl --request PATCH \
  --url https://api.qooly.io/v1/products/987654321/variants/123456789 \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "New Variant Name"
  }'
JSON
{
  "variant_id": "123456789",
  "product_id": "987654321",
  "name": "New Variant Name",
  "sku": "VAR123",
  "price": 49.99,
  "currency": "USD",
  "inventory": 100,
  "weight": 0.75,
  "weight_unit": "kg",
  "size_unit": "cm",
  "length": 5.0,
  "width": 3.0,
  "height": 10.0,
  "is_published": false,
  "status": "DRAFT",
  "metadata_id": "456789012",
  "country_of_origin": "US",
  "commodity_description": "A high-quality electronic gadget.",
  "taxable": false,
  "tax_code": "TAX123",
  "created_at": "2024-01-19T10:45:00Z",
  "updated_at": "2024-01-19T14:30:00Z",
  "created_by": "789012345",
  "updated_by": "987654321"
}

Delete a single product variant

This endpoint allows you to delete a single product variant.

Required Parameters

  • Name
    product_id
    Type
    string
    Required
    Description

    This property indicates the ID of the product to which the variant belongs.

  • Name
    variant_id
    Type
    string
    Required
    Description

    This property indicates the ID of the product variant to be deleted.

Examples

Delete a single product variant

DELETE
/v1/products/987654321/variants/123456789
curl --request DELETE \
  --url https://api.qooly.io/v1/products/987654321/variants/123456789

Delete a single product variant

DELETE
/v1/products/987654321/variants/123456789
curl --request DELETE \
  --url https://api.qooly.io/v1/products/987654321/variants/123456789
JSON
{}