List products with pagination

Lists the store products, 20 per page by default, with their variants and pricing. Filters combine. Prices are the stored prices unless regionId is given.

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → API keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Query Parameters

page?integer

1-based page number.

Default1

Range1 <= value

limit?integer

Items per page. Default 20. Maximum 100. Larger values are capped to 100.

Default20

Range1 <= value <= 100

search?string

Case-insensitive text search over name, SKU and description. With several words, products matching every word are returned; when none does, products matching any word are returned.

status?string

Filter by publish state. Any other value is rejected with 400.

Value in"active" | "draft"

type?string

Filter by product type. Any other value is rejected with 400.

Value in"SIMPLE" | "VARIABLE" | "KIT"

sortBy?string

Field to sort by. price sorts on the stored base price (basePrice). An unknown value falls back to createdAt.

Default"menuOrder"

sortOrder?string

Sort direction. Default asc.

Default"asc"

Value in"asc" | "desc"

regionId?string

Region ID. When set, prices are shown in that region currency, using the region manual price overrides where they exist. Ignored when the region is not found or already uses the store currency.

curl -X GET "https://api.brainerce.com/api/v1/products?page=1&limit=20&search=string&status=active&type=SIMPLE&sortBy=name&sortOrder=asc&regionId=string"

curl -X GET "https://api.brainerce.com/api/v1/products?page=1&limit=20&search=string&status=active&type=SIMPLE&sortBy=name&sortOrder=asc&regionId=string"

{
  "data": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "name": "Classic T-Shirt",
      "slug": "classic-t-shirt",
      "localeSlugs": {},
      "description": "A soft cotton t-shirt.",
      "descriptionFormat": "text",
      "basePrice": "49.90",
      "salePrice": "24.90",
      "costPrice": "12.00",
      "priceMin": "24.90",
      "priceMax": "34.90",
      "priceVaries": true,
      "displayPrice": "29.90",
      "displaySalePrice": "24.90",
      "displayPriceMin": "24.90",
      "displayPriceMax": "34.90",
      "displayCurrency": "USD",
      "gtin": "0123456789012",
      "mpn": "TS-BLK-M",
      "salePriceStartsAt": "2019-08-24T14:15:22Z",
      "salePriceEndsAt": "2019-08-24T14:15:22Z",
      "shippingWeightValue": 0.3,
      "shippingWeightUnit": "kg",
      "shippingLengthValue": 30,
      "shippingWidthValue": 20,
      "shippingHeightValue": 5,
      "shippingDimensionUnit": "cm",
      "metaDescription": "Soft cotton t-shirt in five colors",
      "status": "active",
      "sku": "TSHIRT-BLK-M",
      "type": "SIMPLE",
      "kitPricingMode": "FIXED",
      "kitDiscountValue": 10,
      "isDownloadable": true,
      "downloadData": {
        "files": [
          {
            "id": "clx1a2b3c4d5e6f7g8h9",
            "name": "photos.zip",
            "url": "https://cdn.example.com/downloads/photos.zip",
            "storageKey": "downloads/photos.zip",
            "size": 5242880,
            "mimeType": "application/zip"
          }
        ],
        "downloadLimit": 3,
        "downloadExpiry": 30
      },
      "needsSync": true,
      "lastSyncedAt": "2019-08-24T14:15:22Z",
      "menuOrder": 0,
      "taxBehavior": "taxable",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z",
      "inventory": {
        "trackingMode": "TRACKED",
        "total": 42,
        "reserved": 3,
        "available": 39,
        "inStock": true,
        "canPurchase": true,
        "lastInventorySyncAt": "2019-08-24T14:15:22Z"
      },
      "variants": [
        {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "productId": "clx1a2b3c4d5e6f7g8h9",
          "sku": "TSHIRT-BLK-M",
          "name": "Black / M",
          "attributes": {
            "size": "S",
            "color": "Red"
          },
          "price": "19.90",
          "salePrice": "24.90",
          "costPrice": "12.00",
          "salePriceStartsAt": "2019-08-24T14:15:22Z",
          "salePriceEndsAt": "2019-08-24T14:15:22Z",
          "displayPrice": "29.90",
          "displaySalePrice": "24.90",
          "displayCurrency": "USD",
          "image": "string",
          "position": 0,
          "status": "active",
          "inventory": {
            "trackingMode": "TRACKED",
            "total": 42,
            "reserved": 3,
            "available": 39,
            "inStock": true,
            "canPurchase": true,
            "lastInventorySyncAt": "2019-08-24T14:15:22Z"
          },
          "isDownloadable": true,
          "downloadData": {
            "files": [
              {
                "id": "clx1a2b3c4d5e6f7g8h9",
                "name": "photos.zip",
                "url": "https://cdn.example.com/downloads/photos.zip",
                "storageKey": "downloads/photos.zip",
                "size": 5242880,
                "mimeType": "application/zip"
              }
            ],
            "downloadLimit": 3,
            "downloadExpiry": 30
          },
          "shippingClassId": "clx1a2b3c4d5e6f7g8h9",
          "createdAt": "2019-08-24T14:15:22Z",
          "updatedAt": "2019-08-24T14:15:22Z"
        }
      ],
      "images": [
        {
          "url": "https://cdn.example.com/products/tshirt.jpg",
          "position": 0,
          "isMain": true,
          "alt": "Black t-shirt on a hanger",
          "id": "clx1a2b3c4d5e6f7g8h9",
          "key": "products/tshirt.jpg",
          "thumbnailUrl": "https://cdn.example.com/products/tshirt-thumb.jpg",
          "width": 1200,
          "height": 800,
          "size": 245123,
          "mimeType": "image/jpeg",
          "createdAt": "2019-08-24T14:15:22Z",
          "source": "local",
          "importStatus": "completed",
          "importError": "HTTP 404 from the source server",
          "src": "https://cdn.example.com/products/tshirt.jpg",
          "altSource": "asset",
          "altTranslations": {},
          "originalFilename": "tshirt.jpg",
          "sourceUrl": "https://source.example.com/img/tshirt.jpg",
          "sourcePlatform": "SHOPIFY",
          "importedAt": "2026-01-15T10:30:00.000Z",
          "platformImageIds": {}
        }
      ],
      "channels": {},
      "translations": {},
      "categories": [
        {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "name": "Shoes",
          "taxBehavior": "taxable"
        }
      ],
      "brands": [
        {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "name": "Summer Collection"
        }
      ],
      "attributes": [
        "string"
      ],
      "productAttributeOptions": [
        {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "attributeId": "clx1a2b3c4d5e6f7g8h9",
          "attributeOptionId": "clx1a2b3c4d5e6f7g8h9",
          "platform": "GLOBAL",
          "attribute": {
            "id": "clx1a2b3c4d5e6f7g8h9",
            "name": "Color",
            "displayType": "COLOR_SWATCH"
          },
          "attributeOption": {
            "id": "clx1a2b3c4d5e6f7g8h9",
            "name": "Black",
            "value": "black",
            "swatchColor": "#000000",
            "swatchColor2": "#FFFFFF",
            "swatchImageUrl": "https://cdn.example.com/swatches/black.png"
          }
        }
      ],
      "tags": [
        "string"
      ],
      "metafields": [
        {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "definitionId": "clx1a2b3c4d5e6f7g8h9",
          "definitionKey": "material",
          "definitionName": "Material",
          "type": "TEXT",
          "value": "Cotton",
          "variantId": "clx1a2b3c4d5e6f7g8h9"
        }
      ],
      "customizationFields": [
        {
          "definitionId": "clx1a2b3c4d5e6f7g8h9",
          "name": "Engraving text",
          "key": "engraving",
          "description": "Up to 20 characters",
          "type": "TEXT",
          "required": true,
          "minLength": 1,
          "maxLength": 20,
          "minValue": 0,
          "maxValue": 100,
          "enumValues": [
            "string"
          ],
          "defaultValue": "Happy birthday",
          "position": 0
        }
      ],
      "channelPublishes": [
        {
          "salesChannel": {
            "id": "clx1a2b3c4d5e6f7g8h9",
            "name": "My storefront",
            "connectionId": "vc_9f3a2b1c8d7e6f5a"
          },
          "connection": {
            "id": "clx1a2b3c4d5e6f7g8h9",
            "name": "My storefront",
            "connectionId": "vc_9f3a2b1c8d7e6f5a"
          }
        }
      ],
      "vibeCodedPublishes": [
        {
          "salesChannel": {
            "id": "clx1a2b3c4d5e6f7g8h9",
            "name": "My storefront",
            "connectionId": "vc_9f3a2b1c8d7e6f5a"
          },
          "connection": {
            "id": "clx1a2b3c4d5e6f7g8h9",
            "name": "My storefront",
            "connectionId": "vc_9f3a2b1c8d7e6f5a"
          }
        }
      ],
      "channelSync": {},
      "shippingClassId": "clx1a2b3c4d5e6f7g8h9",
      "shippingClass": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "Heavy items"
      },
      "crossSells": [
        {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "name": "Summer Collection"
        }
      ],
      "upsells": [
        {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "name": "Summer Collection"
        }
      ],
      "related": [
        {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "name": "Summer Collection"
        }
      ],
      "bundleOfferCount": 1,
      "orderBumpCount": 1,
      "avgRating": 4.6,
      "reviewCount": 18,
      "seoScore": {
        "score": 82,
        "band": "excellent",
        "hasUnresolvedError": true
      },
      "modifierGroups": [
        {
          "attachmentId": "clx1a2b3c4d5e6f7g8h9",
          "groupId": "clx1a2b3c4d5e6f7g8h9",
          "variantId": "clx1a2b3c4d5e6f7g8h9",
          "position": 0,
          "minOverride": 0,
          "maxOverride": 3,
          "freeQuantityOverride": 1,
          "requiredOverride": true,
          "freeAllocationPolicyOverride": "EXPENSIVE_FREE",
          "defaultModifierIds": [
            "string"
          ],
          "name": "Toppings",
          "internalName": "toppings-pizza",
          "description": "Choose up to 3",
          "translations": {},
          "selectionType": "SINGLE",
          "minSelections": 0,
          "maxSelections": 3,
          "freeQuantity": 1,
          "required": true,
          "freeAllocationPolicy": "EXPENSIVE_FREE",
          "status": "active",
          "modifiers": [
            {
              "id": "clx1a2b3c4d5e6f7g8h9",
              "name": "Extra cheese",
              "description": "Double portion",
              "translations": {},
              "priceDelta": "2.50",
              "sku": "TSHIRT-BLK-M",
              "image": "http://example.com",
              "position": 0,
              "isDefault": true,
              "available": true,
              "referencedProductId": "clx1a2b3c4d5e6f7g8h9",
              "status": "active"
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 137,
    "totalPages": 7
  }
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products"
}

List products with pagination

Authorization

Query Parameters

Example default

Example default

Example default

Example default