Artos API

Products

Products are the core of your Artos store. This guide explains how to use the Artos Store API to access your product catalog, including listing products and getting product details.

The Product Object

The product model contains all the essential information about items in your catalog. Here's an overview of the key properties:

  • Name
    id
    Type
    string
    Description

    Unique identifier for the product (UUID format)

  • Name
    name
    Type
    string
    Description

    The product name

  • Name
    description
    Type
    string
    Description

    Detailed product description

  • Name
    slug
    Type
    string
    Description

    URL-friendly identifier for the product

  • Name
    variants
    Type
    array of objects
    Description

    Array of product variants with different combinations of options

  • Name
    files
    Type
    array of objects
    Description

    Product images and their metadata. These are general product images not tied to specific variants.

  • Name
    optionGroups
    Type
    array of objects
    Description

    Groups of options (e.g., Size, Color) available for this product

  • Name
    labelValues
    Type
    array of objects
    Description

    Categories or tags associated with the product

{
  "id": "b05982b8-d3fc-40a8-ad81-6b235e4e09a3",
  "name": "Hugo Boss Casual Shirt",
  "description": "High quality shirt made by hugo boss brand",
  "slug": "hugo-boss-casual-shirt",
  "variants": [
    {
      "id": "4f2ad95a-8fc9-4361-9a00-77ab7fb49d7a",
      "name": "Hugo Boss Casual Shirt",
      "sku": "hugo-boss-casual-shirt-slim-fit-hugo-boss-cotton-white-small",
      "price": 70,
      "stock": null,
      "productOptions": [
        {
          "id": "085ce7bf-3f03-49eb-8362-37d37928d2bb",
          "name": "Small",
          "code": "small"
        },
        {
          "id": "737a99c0-b1b1-4ac8-9a7d-982438ff4506",
          "name": "White",
          "code": "white"
        }
      ],
      "files": [
        {
          "id": "aec1e840-9a80-4494-b2fb-4af67c9a7725",
          "priority": 1,
          "file": {
            "path": "https://artos-bucket.s3.eu-north-1.amazonaws.com/image.jpeg",
            "mimeType": "image/jpeg"
          }
        }
      ]
    }
  ],
  "files": [
    {
      "id": "6a7537c4-829d-436f-9785-363e2a123717",
      "priority": 1,
      "file": {
        "path": "https://artos-bucket.s3.eu-north-1.amazonaws.com/image.jpeg",
        "mimeType": "image/jpeg"
      }
    }
  ],
  "optionGroups": [
    {
      "id": "c7522d4e-8235-49f7-aabd-a2acd46d6900",
      "name": "Color",
      "code": "color",
      "options": [
        {
          "id": "737a99c0-b1b1-4ac8-9a7d-982438ff4506",
          "name": "White",
          "code": "white"
        },
        {
          "id": "03a90c05-83df-42a9-abc0-6275163fdd37",
          "name": "Pink",
          "code": "pink"
        }
      ]
    },
    {
      "id": "32684bc8-5a00-4235-9ddc-9749339a1f62",
      "name": "Size",
      "code": "size",
      "options": [
        {
          "id": "085ce7bf-3f03-49eb-8362-37d37928d2bb",
          "name": "Small",
          "code": "small"
        },
        {
          "id": "cb155b20-a536-42da-b33a-db7f61b09718",
          "name": "Medium",
          "code": "medium"
        }
      ]
    }
  ],
  "labelValues": [
    {
      "id": "b4eee3b7-46ce-46bc-88c1-acf831a33bf8",
      "name": "Men",
      "code": "men"
    }
  ]
}
GET

List all products

Retrieve a list of products in your store with optional filtering and pagination.

Query Parameters

  • Name
    page
    Type
    integer
    Description

    Page number for pagination (default: 1)

  • Name
    limit
    Type
    integer
    Description

    Number of products per page (default: 20, max 100)

  • Name
    search
    Type
    string
    Description

    Search in product names and descriptions

  • Name
    label
    Type
    string
    Description

    Filter products by label code (e.g., 'men', 'shoes')

  • Name
    optionGroup
    Type
    string
    Description

    Filter products by option group code (e.g., 'size', 'color')

  • Name
    option
    Type
    string
    Description

    Filter products by specific option code within an option group

Request

GET
https://api.artosapp.com/store/products
# cURL example
curl "https://api.artosapp.com/store/products?limit=20&page=1" \
  -H "x-store-id: your-store-id"

{
  "data": [
    {
      "id": "b05982b8-d3fc-40a8-ad81-6b235e4e09a3",
      "name": "Hugo Boss Casual Shirt",
      "description": "High quality shirt made by hugo boss brand",
      "slug": "hugo-boss-casual-shirt",
      "variants": [
        {
          "id": "4f2ad95a-8fc9-4361-9a00-77ab7fb49d7a",
          "name": "Hugo Boss Casual Shirt",
          "sku": "hugo-boss-casual-shirt-slim-fit-hugo-boss-cotton-white-small",
          "price": 70,
          "stock": null,
          "productOptions": [
            {
              "id": "085ce7bf-3f03-49eb-8362-37d37928d2bb",
              "name": "Small",
              "code": "small"
            },
            {
              "id": "737a99c0-b1b1-4ac8-9a7d-982438ff4506",
              "name": "White",
              "code": "white"
            }
          ]
        }
      ],
      "labelValues": [
        {
          "id": "b4eee3b7-46ce-46bc-88c1-acf831a33bf8",
          "name": "Men",
          "code": "men"
        }
      ]
    }
  ],
  "meta": {
    "itemsPerPage": 20,
    "totalItems": 43,
    "currentPage": 1,
    "totalPages": 3
  },
  "links": {
    "current": "?page=1&limit=20",
    "next": "?page=2&limit=20"
  }
}
GET

Retrieve a product

Retrieve a specific product by its ID, including all its variants.

Path Parameters

  • Name
    productId
    Type
    string
    Description

    Unique identifier of the product (UUID format)

This endpoint returns the complete product details including variants, options, and images information. Use this when you need to display a product detail page or when you need all information about a specific product.

Using Options and Labels

The response includes two important structures for filtering and categorization:

  • optionGroups: Contains filterable attributes like "Color", "Size", and "Brands". Use these to create interactive filters in your frontend (like color swatches, size selectors, or brand filters).

  • labelValues: These represent product categories or tags (like "Men", "Watches"). Use these to organize products in your navigation sidebar or for category-based browsing.

When building your e-commerce frontend, display labelValues as category navigation in the sidebar, while using optionGroups to create interactive product filters that let customers narrow down their product selection.

Request

GET
https://api.artosapp.com/store/products/${productId}
# cURL example
curl "https://api.artosapp.com/store/products/b05982b8-d3fc-40a8-ad81-6b235e4e09a3" \
  -H "x-store-id: your-store-id"

{
  "id": "40f50f98-f165-4611-b597-8ff51ca0548f",
  "name": "Tommy Hilfiger Watch",
  "description": "Men's watch by the brand Tommy Hilfiger, with a metallic gold strap and a black dial with chronographs that add the classic American cool style.",
  "slug": "tommy-hilfiger-watch",
  "variants": [
    {
      "id": "175a8bff-e4a8-4d7f-bc7c-a60e0fe4c8c3",
      "name": "Tommy Hilfiger Watch Gold",
      "sku": "tommy-hilfiger-watch-gold-t",
      "price": "120.00",
      "stock": null,
      "productOptions": [
        {
          "id": "c2dcb40f-12dc-4bba-913b-f4ceb5e79523",
          "name": "Gold",
          "code": "gold"
        },
        {
          "id": "8c9f249d-bc5d-4a6c-bf86-d08e2acc0312",
          "name": "Tommy Hilfiger",
          "code": "tommy-hilfiger"
        }
      ],
      "files": [
        {
          "id": "b2f76e9f-1412-480a-b56b-7083b50e891b",
          "priority": 1,
          "file": {
            "path": "https://artos-bucket.s3.eu-north-1.amazonaws.com/1746041828851-461837653-Tommy%20Hilfiger%20Watch%20Gold.jpeg",
            "mimeType": "image/jpeg"
          }
        }
      ]
    }
  ],
  "files": [
    {
      "id": "a83bcf36-4b59-4303-9170-610f89b20016",
      "priority": 1,
      "file": {
        "path": "https://artos-bucket.s3.eu-north-1.amazonaws.com/1746041240602-114552390-Tommy%20Hilfiger%20Watch%20Black.jpeg",
        "mimeType": "image/jpeg"
      }
    }
  ],
  "optionGroups": [
    {
      "id": "61598e68-ed20-4f0c-950b-228da1ce7741",
      "name": "Color",
      "code": "color",
      "options": [
        {
          "id": "aa5a52f5-5051-4b0d-91f2-944a4cd09f69",
          "name": "Black",
          "code": "black"
        },
        {
          "id": "36462eee-ad87-4cab-a119-13c0eeec82f5",
          "name": "Silver",
          "code": "silver"
        },
        {
          "id": "c2dcb40f-12dc-4bba-913b-f4ceb5e79523",
          "name": "Gold",
          "code": "gold"
        }
      ]
    },
    {
      "id": "b30f8b5a-e6f5-472a-b060-17127d6f75d5",
      "name": "Brands",
      "code": "brands",
      "options": [
        {
          "id": "8c9f249d-bc5d-4a6c-bf86-d08e2acc0312",
          "name": "Tommy Hilfiger",
          "code": "tommy-hilfiger"
        }
      ]
    }
  ],
  "labelValues": [
    {
      "id": "7bd8878e-4c45-48db-82b9-d465a5e14d66",
      "name": "Watches",
      "code": "watches"
    },
    {
      "id": "b4eee3b7-46ce-46bc-88c1-acf831a33bf8",
      "name": "Men",
      "code": "men"
    }
  ]
}
ProductsVariants

Was this page helpful?