Skip to main content
If your store runs on a platform not natively supported by Cartally, you can integrate using the Custom API method. You build an API endpoint on your server that returns your product catalog — Cartally fetches it periodically and indexes it for search.

​
Overview

​
Setup

  1. Log in to app.cartally.co.
  2. Go to Integration and select API as the method.
  3. Enter the full URL of your product endpoint (e.g. https://myshop.com/api/cartally/products).
  4. (Optional) Enter an API key if your endpoint requires authentication.
  5. Click Save & Connect.
Cartally will call your endpoint with a GET request. If authentication is configured, the request includes an Authorization: Basic {api_key} header.

​
Product endpoint specification

Your endpoint must return a JSON array of product objects. Cartally fetches products in pages using query parameters.

​
Request

GET https://myshop.com/api/cartally/products?page=1&per_page=100&lang=en
ParameterTypeDescription
pageintegerPage number (starts at 1)
per_pageintegerNumber of products per page (default: 100)
langstringLanguage code (e.g. en, pl). Return product data in this language

​
Response

Return a JSON array of product objects. When the last page is reached, return an empty array []. 
[
  {
    "id": 12345,
    "name": "Mountain Bike Helmet Pro",
    "description": "Lightweight polycarbonate helmet with adjustable ventilation and MIPS protection system. Certified for mountain biking and trail riding.",
    "reference": "HEL-PRO-001",
    "url": "https://myshop.com/product/mountain-bike-helmet-pro",
    "price": 49.99,
    "categories": ["Helmets", "Safety Equipment"],
    "images": [
      "https://myshop.com/img/helmet-black-1.jpg",
      "https://myshop.com/img/helmet-black-2.jpg"
    ],
    "variants": [
      {
        "id": "12345-black",
        "attributes": {
          "color": "black",
          "size": "M"
        },
        "price": 49.99,
        "images": [
          "https://myshop.com/img/helmet-black-1.jpg"
        ]
      },
      {
        "id": "12345-white",
        "attributes": {
          "color": "white",
          "size": "M"
        },
        "price": 49.99,
        "images": [
          "https://myshop.com/img/helmet-white-1.jpg"
        ]
      }
    ],
    "currencies": {
      "EUR": 49.99,
      "PLN": 219.00,
      "USD": 54.99
    }
  }
]

​
Product fields reference

​
Required fields

FieldTypeDescription
idstring or integerUnique product identifier
namestringProduct title. Should be descriptive — this is the primary search field
descriptionstringProduct description in plain text or HTML (HTML tags will be stripped). The more detailed, the better the AI search quality
categoriesstring[]List of category names the product belongs to. Used for faceted filtering
imagesstring[]List of publicly accessible image URLs. The first image is used as the main thumbnail
pricenumberProduct price in the store’s default currency (decimal, e.g. 49.99)
FieldTypeDescription
urlstringDirect URL to the product page in your store. Customers click this to visit the product
referencestringSKU or internal reference code
variantsobject[]Product variants (see below). If omitted, the product is indexed as a single item
currenciesobjectPrices in additional currencies. Keys are ISO 4217 currency codes, values are decimal prices

​
Variant fields

If your products have color variants, provide them in the variants array. Cartally splits color variants into separate search results so each variant shows the correct image.
FieldTypeDescription
idstringUnique variant identifier (e.g. 12345-black)
attributesobjectKey-value pairs of variant attributes (e.g. {"color": "black", "size": "M"})
pricenumberVariant-specific price (if different from the parent product)
imagesstring[]Variant-specific images. If omitted, parent product images are used
The color attribute has special handling — variants with different colors become separate search results with their own images. Other attributes (like size) are indexed as filterable facets but don’t split the product.

​
Multi-currency pricing

To support multiple currencies, include a currencies object with ISO 4217 codes as keys: 
{
  "currencies": {
    "PLN": 219.00,
    "EUR": 49.99,
    "USD": 54.99,
    "GBP": 42.99
  }
}
If currencies is omitted, only the base price field is indexed using your store’s default currency.

​
Multilingual products

If your store supports multiple languages, Cartally will call your endpoint with different lang parameter values. Your endpoint should return product names, descriptions, and categories in the requested language. 
GET /api/cartally/products?page=1&per_page=100&lang=pl
If a product is not translated, return it in the default language — Cartally handles the fallback gracefully.

​
Declaring available languages

Cartally detects available languages from the <html lang> attribute and <link rel="alternate" hreflang="..."> tags on your store’s homepage. Make sure these are present: 
<html lang="pl">
<head>
  <link rel="alternate" hreflang="pl" href="https://myshop.com" />
  <link rel="alternate" hreflang="en" href="https://myshop.com/en/" />
  <link rel="alternate" hreflang="de" href="https://myshop.com/de/" />
</head>

​
Pagination

Your endpoint must support pagination. Cartally fetches products in batches of 100 (configurable). Rules:
  • Return up to per_page products per request.
  • When there are no more products, return an empty array [].
  • Products should be returned in a consistent order (e.g. by ID) so pagination is stable.
Example pagination flow:
RequestResponse
?page=1&per_page=100100 products
?page=2&per_page=100100 products
?page=3&per_page=10047 products
?page=4&per_page=100[] (empty — sync complete)

​
Authentication

If your endpoint requires authentication, enter an API key in the Cartally panel. Cartally sends it as: 
Authorization: Basic {api_key}
Always use HTTPS for your product endpoint. API keys sent over HTTP are vulnerable to interception.

​
Sync schedule

  • The first sync runs immediately after saving the integration.
  • Subsequent syncs run automatically every 24 hours (configurable).
  • You can trigger a manual re-sync from the Integration page in the Cartally panel.

​
Minimal example

Here’s the simplest possible product endpoint (Python/Flask): 
from flask import Flask, request, jsonify

app = Flask(__name__)

PRODUCTS = [
    {
        "id": 1,
        "name": "Classic T-Shirt",
        "description": "100% cotton t-shirt, available in multiple colors.",
        "categories": ["Clothing", "T-Shirts"],
        "images": ["https://myshop.com/img/tshirt.jpg"],
        "price": 29.99,
        "url": "https://myshop.com/product/classic-tshirt",
        "variants": [
            {
                "id": "1-black",
                "attributes": {"color": "black", "size": "M"},
                "images": ["https://myshop.com/img/tshirt-black.jpg"]
            },
            {
                "id": "1-white",
                "attributes": {"color": "white", "size": "M"},
                "images": ["https://myshop.com/img/tshirt-white.jpg"]
            }
        ]
    },
    {
        "id": 2,
        "name": "Running Shoes",
        "description": "Lightweight running shoes with responsive cushioning.",
        "categories": ["Footwear", "Running"],
        "images": ["https://myshop.com/img/shoes.jpg"],
        "price": 89.99,
        "url": "https://myshop.com/product/running-shoes"
    }
]

@app.route("/api/cartally/products")
def products():
    page = int(request.args.get("page", 1))
    per_page = int(request.args.get("per_page", 100))
    # lang = request.args.get("lang", "en")  # Use for translations

    start = (page - 1) * per_page
    end = start + per_page
    return jsonify(PRODUCTS[start:end])

​
Best practices

The AI assistant uses product descriptions to answer customer questions. The more detailed your descriptions, the better the AI can recommend and compare products.
Categories become filter facets in the widget. Use consistent naming (e.g. always “T-Shirts”, not sometimes “Tshirts” or “tee shirts”).
The first image in the array is used as the search result thumbnail. Use square or landscape images for best results.
If a product comes in multiple colors, provide color-specific images in each variant. This way customers see the correct color in search results.
Cartally fetches up to 100 products per request. Your endpoint should respond within 30 seconds. Use database pagination — don’t load all products into memory.

​
Troubleshooting

​
Connection test fails

  • Verify the endpoint URL is correct and publicly accessible.
  • Check that HTTPS is working (Cartally requires a valid SSL certificate).
  • If using an API key, verify it’s entered correctly in the panel.
  • Check that your endpoint returns valid JSON.
  • Verify that name, description, categories, images, and price are present for every product.
  • Check that pagination returns an empty array [] on the last page (not an error).
  • Wait a few minutes after the sync — indexing may still be in progress.

​
Wrong prices or languages

  • Ensure your endpoint responds to the lang parameter with correctly translated data.
  • Verify that currencies values are decimal numbers (not strings, not minor units).