Artos API

Product Variants

Product variants represent the specific purchasable items in your store catalog, with unique combinations of product options like size, color, and material.

The Product Variant Object

The product variant object contains all the essential information about specific product variants. Here's an overview of the key properties:

  • Name
    id
    Type
    string
    Description

    Unique identifier for the variant (UUID format)

  • Name
    name
    Type
    string
    Description

    The variant name (often same as parent product)

  • Name
    sku
    Type
    string
    Description

    Stock keeping unit code for inventory tracking

  • Name
    price
    Type
    string|number
    Description

    Price of the variant

  • Name
    stock
    Type
    number | null
    Description

    Available inventory (null if not tracking inventory)

  • Name
    taxRate
    Type
    object
    Description

    Tax information applied to this variant

  • Name
    productOptions
    Type
    array
    Description

    The specific options that define this variant (e.g., brand, color)

  • Name
    files
    Type
    array
    Description

    Images specific to this variant with nested file information

  • Name
    labelValues
    Type
    array
    Description

    Categories or tags associated with this variant

  • Name
    product
    Type
    object
    Description

    Reference to the parent product

{
  "id": "175a8bff-e4a8-4d7f-bc7c-a60e0fe4c8c3",
  "name": "Tommy Hilfiger Watch Gold",
  "sku": "tommy-hilfiger-watch-gold-t",
  "taxRate": {
    "id": "34dcdb62-b26d-4a7f-88ca-613cb5036347",
    "name": "Standard Tax",
    "rate": 24,
    "isDefault": true,
    "createdAt": "2025-04-28T13:25:10.170Z",
    "updatedAt": "2025-04-28T13:25:11.084Z"
  },
  "price": "120.00",
  "stock": null,
  "productOptions": [
    {
      "id": "8c9f249d-bc5d-4a6c-bf86-d08e2acc0312",
      "name": "Tommy Hilfiger",
      "code": "tommy-hilfiger",
      "createdAt": "2025-04-30T19:27:33.823Z",
      "updatedAt": "2025-04-30T19:27:33.823Z"
    },
    {
      "id": "c2dcb40f-12dc-4bba-913b-f4ceb5e79523",
      "name": "Gold",
      "code": "gold",
      "createdAt": "2025-05-09T13:18:26.360Z",
      "updatedAt": "2025-05-09T13:18:26.360Z"
    }
  ],
  "labelValues": [],
  "files": [
    {
      "id": "b2f76e9f-1412-480a-b56b-7083b50e891b",
      "createdAt": "2025-04-30T19:37:10.582Z",
      "updatedAt": "2025-04-30T19:37:10.582Z",
      "priority": 1,
      "file": {
        "id": "3a46508a-b8d0-4c67-bc5d-b54c5f252c2f",
        "createdAt": "2025-04-30T19:37:09.672Z",
        "updatedAt": "2025-04-30T19:37:09.672Z",
        "originalName": "Tommy Hilfiger Watch Gold.jpeg",
        "fileName": "1746041828851-461837653-Tommy Hilfiger Watch Gold.jpeg",
        "mimeType": "image/jpeg",
        "fileSize": 65662,
        "path": "https://artos-bucket.s3.eu-north-1.amazonaws.com/1746041828851-461837653-Tommy%20Hilfiger%20Watch%20Gold.jpeg"
      }
    }
  ],
  "product": {
    "variants": [],
    "files": [],
    "optionGroups": [],
    "labelValues": []
  }
}
GET

List all variants

Retrieve a list of all product variants in your store with optional filtering and pagination.

Query Parameters

  • Name
    page
    Type
    integer
    Description

    Page number for pagination

  • Name
    limit
    Type
    integer
    Description

    Number of variants per page (max 100)

  • Name
    product
    Type
    string
    Description

    Filter by parent product ID

  • Name
    sortBy
    Type
    string
    Description

    Field and direction to sort results (e.g., 'createdAt:DESC')

Request

GET
https://api.artosapp.com/store/product-variants
# cURL example
curl "https://api.artosapp.com/store/product-variants?limit=10&page=1&sortBy=createdAt:DESC" \
  -H "x-store-id: your-store-id"

{
  "data": [
    {
      "id": "18e5b797-38d0-4525-a436-e8128edaeb9a",
      "name": "Tom Ford Jaden Unisex Sunglasses with Gold Metal Frame - White",
      "sku": "tom-ford-jaden-unisex-sunglasses-with-gold-metal-frame-white-white-tom-ford-metallic",
      "taxRate": {
        "id": "34dcdb62-b26d-4a7f-88ca-613cb5036347",
        "name": "Standard Tax",
        "rate": 24,
        "isDefault": true,
        "createdAt": "2025-04-28T13:25:10.170Z",
        "updatedAt": "2025-04-28T13:25:11.084Z"
      },
      "price": 420,
      "stock": 15,
      "productOptions": [
        {
          "id": "88341b15-71a9-4d29-9c4a-674e7687154f",
          "name": "Metallic",
          "code": "metallic",
          "createdAt": "2025-04-30T17:11:52.147Z",
          "updatedAt": "2025-04-30T17:11:52.147Z"
        },
        {
          "id": "29975b9d-9aff-4bde-afcb-d752fadf0cf8",
          "name": "White",
          "code": "white",
          "createdAt": "2025-05-22T10:40:25.669Z",
          "updatedAt": "2025-05-22T10:40:25.669Z"
        },
        {
          "id": "856e63f9-2ec5-4ef7-8433-52e38a66bee0",
          "name": "Tom Ford",
          "code": "tom-ford",
          "createdAt": "2025-04-30T17:12:09.724Z",
          "updatedAt": "2025-04-30T17:12:09.724Z"
        }
      ],
      "labelValues": [],
      "files": [
        {
          "id": "40167021-a75a-4373-844b-c212f7453869",
          "createdAt": "2025-05-22T10:41:28.570Z",
          "updatedAt": "2025-05-22T10:41:28.570Z",
          "priority": 1,
          "file": {
            "id": "80b1d187-8bb5-492f-baf5-c9a4d24e6f73",
            "path": "https://artos-bucket.s3.eu-north-1.amazonaws.com/1746040463638-101245128-Tom%20Ford%20Sunglasses%20Aviator.jpeg",
            "mimeType": "image/jpeg",
            "fileSize": 9824,
            "fileName": "1746040463638-101245128-Tom Ford Sunglasses Aviator.jpeg",
            "originalName": "Tom Ford Sunglasses Aviator.jpeg",
            "createdAt": "2025-04-30T19:14:24.200Z",
            "updatedAt": "2025-04-30T19:14:24.200Z"
          }
        }
      ],
      "product": {
        "variants": [],
        "files": [],
        "optionGroups": [],
        "labelValues": []
      }
    }
  ],
  "meta": {
    "itemsPerPage": 10,
    "totalItems": 78,
    "currentPage": 1,
    "totalPages": 8,
    "sortBy": [
      [
        "createdAt",
        "DESC"
      ]
    ]
  },
  "links": {
    "current": "http://api.artosapp.com/store/product-variants?page=1&limit=10&sortBy=createdAt:DESC",
    "next": "http://api.artosapp.com/store/product-variants?page=2&limit=10&sortBy=createdAt:DESC",
    "last": "http://api.artosapp.com/store/product-variants?page=8&limit=10&sortBy=createdAt:DESC"
  }
}
GET

Retrieve a variant

Retrieve a specific variant by its ID, including all its details.

Path Parameters

  • Name
    variantId
    Type
    string
    Description

    Unique identifier of the variant (UUID format)

This endpoint returns complete details about a specific product variant, including its pricing, stock status, associated options, and images. Use this when you need detailed information for a specific purchasable item in your store.

Request

GET
https://api.artosapp.com/store/product-variants/${variantId}
# cURL example
curl "https://api.artosapp.com/store/product-variants/175a8bff-e4a8-4d7f-bc7c-a60e0fe4c8c3" \
  -H "x-store-id: your-store-id"

{
  "id": "175a8bff-e4a8-4d7f-bc7c-a60e0fe4c8c3",
  "name": "Tommy Hilfiger Watch Gold",
  "sku": "tommy-hilfiger-watch-gold-t",
  "taxRate": {
    "id": "34dcdb62-b26d-4a7f-88ca-613cb5036347",
    "name": "Standard Tax",
    "rate": 24,
    "isDefault": true,
    "createdAt": "2025-04-28T13:25:10.170Z",
    "updatedAt": "2025-04-28T13:25:11.084Z"
  },
  "price": "120.00",
  "stock": null,
  "productOptions": [
    {
      "id": "8c9f249d-bc5d-4a6c-bf86-d08e2acc0312",
      "name": "Tommy Hilfiger",
      "code": "tommy-hilfiger",
      "createdAt": "2025-04-30T19:27:33.823Z",
      "updatedAt": "2025-04-30T19:27:33.823Z"
    },
    {
      "id": "c2dcb40f-12dc-4bba-913b-f4ceb5e79523",
      "name": "Gold",
      "code": "gold",
      "createdAt": "2025-05-09T13:18:26.360Z",
      "updatedAt": "2025-05-09T13:18:26.360Z"
    }
  ],
  "labelValues": [],
  "files": [
    {
      "id": "b2f76e9f-1412-480a-b56b-7083b50e891b",
      "createdAt": "2025-04-30T19:37:10.582Z",
      "updatedAt": "2025-04-30T19:37:10.582Z",
      "priority": 1,
      "file": {
        "id": "3a46508a-b8d0-4c67-bc5d-b54c5f252c2f",
        "createdAt": "2025-04-30T19:37:09.672Z",
        "updatedAt": "2025-04-30T19:37:09.672Z",
        "originalName": "Tommy Hilfiger Watch Gold.jpeg",
        "fileName": "1746041828851-461837653-Tommy Hilfiger Watch Gold.jpeg",
        "mimeType": "image/jpeg",
        "fileSize": 65662,
        "path": "https://artos-bucket.s3.eu-north-1.amazonaws.com/1746041828851-461837653-Tommy%20Hilfiger%20Watch%20Gold.jpeg"
      }
    }
  ],
  "product": {
    "variants": [],
    "files": [],
    "optionGroups": [],
    "labelValues": []
  }
}
Products

Was this page helpful?