EAN & Product Search

PixeePIM exposes two complementary APIs for product identification. The EAN Lookup API (/api/v1/ean/) resolves known EAN-13 or EAN-8 barcodes against external databases such as Icecat and GS1. The Product Search API (/api/v1/ean-lookup/) performs multi-criteria searches by product name, reference, or brand when an EAN is not yet known.

EANs that could not be resolved during an import are listed at GET /api/v1/imports/ean-pending. See the Imports page for details.

EAN Lookup

Routes under /api/v1/ean/ resolve barcodes you already have. Results are cached to minimise external API costs.

POST/api/v1/ean/lookup

Look up a single EAN

Resolves a single EAN-13 or EAN-8 barcode against the configured provider databases.

Body parameters

Name
ean
Type
string
Description
The EAN to look up (8 or 13 digits).
Name
use_cache
Type
boolean
Description
Return a cached result when available. Defaults to true.
Name
providers
Type
array
Description
Explicit list of providers to query: icecat, gs1. When omitted all active providers are queried.

Request

POST

/api/v1/ean/lookup

curl -X POST https://api.pixeepim.com/api/v1/ean/lookup \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "ean": "3760000000001",
    "use_cache": true,
    "providers": ["icecat", "gs1"]
  }'

Response

{
  "ean": "3760000000001",
  "found": true,
  "provider": "icecat",
  "data": {
    "name": "Example Product",
    "brand": "My Brand",
    "category": "Electronics",
    "description": "Detailed product description.",
    "specs": {
      "weight": "500g",
      "color": "Black"
    },
    "images": [
      "https://cdn.icecat.biz/img/example.jpg"
    ]
  },
  "lookup_date": "2026-06-19T10:30:00Z"
}

POST/api/v1/ean/batch-lookup

Batch EAN lookup

Resolves multiple EANs in a single request.

Body parameters

Name
eans
Type
array
Description
Array of EAN strings to resolve.
Name
use_cache
Type
boolean
Description
Return cached results where available. Defaults to true.
Name
parallel
Type
boolean
Description
Query providers in parallel for faster resolution. Defaults to true.

Request

POST

/api/v1/ean/batch-lookup

curl -X POST https://api.pixeepim.com/api/v1/ean/batch-lookup \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "eans": [
      "3760000000001",
      "3760000000002",
      "9999999999999"
    ],
    "use_cache": true,
    "parallel": true
  }'

Response

{
  "results": [
    {
      "ean": "3760000000001",
      "found": true,
      "provider": "icecat",
      "data": { "name": "Product A", "brand": "Brand A" }
    },
    {
      "ean": "3760000000002",
      "found": true,
      "provider": "gs1",
      "data": { "name": "Product B", "brand": "Brand B" }
    },
    {
      "ean": "9999999999999",
      "found": false,
      "provider": null,
      "data": null
    }
  ],
  "total": 3,
  "found": 2,
  "processing_time_ms": 234
}

GET/api/v1/ean/cache

Cache stats

Returns statistics about the EAN lookup result cache (hit rate, size, TTL).

Request

GET

/api/v1/ean/cache

curl https://api.pixeepim.com/api/v1/ean/cache \
  -H "Authorization: Bearer {api_key}"

Response

{
  "total_entries": 7200,
  "hit_rate": 0.578,
  "cache_hits": 7200,
  "cache_misses": 5250,
  "total_lookups": 12450
}

DELETE/api/v1/ean/cache

Clear cache

Flushes all cached EAN lookup results. Use with care — subsequent lookups will hit external providers and incur API costs.

Request

DELETE

/api/v1/ean/cache

curl -X DELETE https://api.pixeepim.com/api/v1/ean/cache \
  -H "Authorization: Bearer {api_key}"

Response

{
  "cleared": true,
  "entries_removed": 7200
}

GET/api/v1/ean/history

Lookup history

Returns the history of recent EAN lookups.

Query parameters

Name
skip
Type
integer
Description
Offset for pagination. Defaults to 0.
Name
limit
Type
integer
Description
Number of items to return, max 100. Defaults to 50.

Request

GET

/api/v1/ean/history

curl "https://api.pixeepim.com/api/v1/ean/history?limit=10" \
  -H "Authorization: Bearer {api_key}"

Response

{
  "items": [
    {
      "ean": "3760000000001",
      "found": true,
      "provider": "icecat",
      "looked_up_at": "2026-06-19T10:30:00Z",
      "from_cache": false
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

GET/api/v1/ean/stats

EAN statistics

Returns aggregate statistics: total lookups, success rate, provider breakdown, and monthly cost.

Request

GET

/api/v1/ean/stats

curl https://api.pixeepim.com/api/v1/ean/stats \
  -H "Authorization: Bearer {api_key}"

Response

{
  "total_lookups": 12450,
  "successful_lookups": 10980,
  "failed_lookups": 1470,
  "success_rate": 0.882,
  "by_provider": {
    "icecat": { "lookups": 8200, "found": 7500 },
    "gs1": { "lookups": 4250, "found": 3480 }
  },
  "estimated_cost_usd": 12.40
}

POST/api/v1/ean/upload

Upload EAN file

Uploads a file (CSV or plain text, one EAN per line) for bulk resolution. The job is processed asynchronously in the background.

Body parameters (multipart/form-data)

Name
file
Type
file
Description
CSV or plain-text file containing one EAN per line.

Request

POST

/api/v1/ean/upload

curl -X POST https://api.pixeepim.com/api/v1/ean/upload \
  -H "Authorization: Bearer {api_key}" \
  -F "file=@eans.csv"

Response

{
  "job_id": "ean-upload-7f3a9c",
  "status": "queued",
  "ean_count": 350,
  "created_at": "2026-06-19T10:35:00Z"
}

GET/api/v1/ean/providers

List providers

Lists all configured EAN lookup providers and their current status.

Request

GET

/api/v1/ean/providers

curl https://api.pixeepim.com/api/v1/ean/providers \
  -H "Authorization: Bearer {api_key}"

Response

{
  "providers": [
    {
      "id": "icecat",
      "name": "Icecat",
      "status": "active",
      "confidence": 0.95,
      "description": "International product database"
    },
    {
      "id": "gs1",
      "name": "GS1",
      "status": "active",
      "confidence": 0.88,
      "description": "GS1 global product registry"
    }
  ]
}

POST/api/v1/ean/providers/:provider_id/test

Test a provider

Sends a test lookup to the specified provider and returns connectivity and credential status.

Path parameters

Name
provider_id
Type
string
Description
Provider identifier, e.g. icecat or gs1.

Request

POST

/api/v1/ean/providers/:provider_id/test

curl -X POST https://api.pixeepim.com/api/v1/ean/providers/icecat/test \
  -H "Authorization: Bearer {api_key}"

Response

{
  "provider_id": "icecat",
  "ok": true,
  "latency_ms": 143,
  "message": "Connection successful"
}

GET/api/v1/ean/cost-limits

Cost limits

Returns the configured monthly cost limits per provider and the current spending against those limits.

Request

GET

/api/v1/ean/cost-limits

curl https://api.pixeepim.com/api/v1/ean/cost-limits \
  -H "Authorization: Bearer {api_key}"

Response

{
  "limits": [
    {
      "provider_id": "icecat",
      "monthly_limit_usd": 50.00,
      "current_spend_usd": 12.40,
      "remaining_usd": 37.60
    },
    {
      "provider_id": "gs1",
      "monthly_limit_usd": 20.00,
      "current_spend_usd": 4.10,
      "remaining_usd": 15.90
    }
  ]
}

Product Search

Routes under /api/v1/ean-lookup/ perform multi-criteria searches when a barcode is not yet known. Search by product name, internal reference, brand, or supplier to find a match and optionally retrieve an EAN.

Unresolved EANs from imports (products that arrived without a barcode) are listed at GET /api/v1/imports/ean-pending. See the Imports page for details.

POST/api/v1/ean-lookup/search

Search products

Searches for a product by name, reference, brand, or supplier. At least one of product_name or reference is required.

Body parameters

Name
product_name
Type
string
Description
Product name or keywords. Required if reference is omitted.
Name
reference
Type
string
Description
Internal or supplier reference. Required if product_name is omitted.
Name
brand
Type
string
Description
Brand name to narrow results.
Name
supplier
Type
string
Description
Supplier name or code to restrict the search scope.

Request

POST

/api/v1/ean-lookup/search

curl -X POST https://api.pixeepim.com/api/v1/ean-lookup/search \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "USB-C Hub 7-port",
    "brand": "Anker"
  }'

Response

{
  "results": [
    {
      "product_id": "c3f2a1b0-...",
      "title": "Anker USB-C Hub 7-in-1",
      "brand": "Anker",
      "ean": "0194644078965",
      "reference": "A8346",
      "score": 0.97,
      "source": "internal"
    }
  ],
  "total": 1
}

POST/api/v1/ean-lookup/batch

Batch product lookup

Looks up multiple products by their internal product_id values. Maximum 50 IDs per request.

Body parameters

Name
product_ids
Type
array
Description
Array of product UUID strings to look up (max 50).

Request

POST

/api/v1/ean-lookup/batch

curl -X POST https://api.pixeepim.com/api/v1/ean-lookup/batch \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": [
      "c3f2a1b0-0000-0000-0000-000000000001",
      "c3f2a1b0-0000-0000-0000-000000000002"
    ]
  }'

Response

{
  "results": [
    {
      "product_id": "c3f2a1b0-0000-0000-0000-000000000001",
      "title": "Product Alpha",
      "ean": "3760000000001",
      "found": true
    },
    {
      "product_id": "c3f2a1b0-0000-0000-0000-000000000002",
      "title": "Product Beta",
      "ean": null,
      "found": false
    }
  ],
  "total": 2,
  "found": 1
}

POST/api/v1/ean-lookup/resolve/:resolution_id

Resolve pending EAN

Manually resolves a pending EAN resolution record by supplying the correct EAN and its source.

Path parameters

Name
resolution_id
Type
string
Description
ID of the pending resolution record to resolve.

Body parameters

Name
ean
Type
string
Description
The resolved EAN to assign to the record.
Name
source
Type
string
Description
How the EAN was obtained, e.g. manual, icecat, gs1.

Request

POST

/api/v1/ean-lookup/resolve/:resolution_id

curl -X POST https://api.pixeepim.com/api/v1/ean-lookup/resolve/res_7f3a9c \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "ean": "3760000000001",
    "source": "manual"
  }'

Response

{
  "resolution_id": "res_7f3a9c",
  "ean": "3760000000001",
  "source": "manual",
  "resolved_at": "2026-06-19T11:00:00Z",
  "status": "resolved"
}

GET/api/v1/ean-lookup/providers

Search providers

Lists the providers available for multi-criteria product search (distinct from the EAN barcode providers above).

Request

GET

/api/v1/ean-lookup/providers

curl https://api.pixeepim.com/api/v1/ean-lookup/providers \
  -H "Authorization: Bearer {api_key}"

Response

{
  "providers": [
    {
      "id": "icecat",
      "name": "Icecat",
      "status": "active"
    },
    {
      "id": "gs1",
      "name": "GS1",
      "status": "active"
    }
  ]
}

GET/api/v1/ean-lookup/quotas

Search quotas

Returns the monthly query quota for each product search provider and the number of queries used so far this month.

Request

GET

/api/v1/ean-lookup/quotas

curl https://api.pixeepim.com/api/v1/ean-lookup/quotas \
  -H "Authorization: Bearer {api_key}"

Response

{
  "quotas": [
    {
      "provider_id": "icecat",
      "monthly_limit": 10000,
      "used": 3420,
      "remaining": 6580,
      "reset_at": "2026-07-01T00:00:00Z"
    },
    {
      "provider_id": "gs1",
      "monthly_limit": 5000,
      "used": 870,
      "remaining": 4130,
      "reset_at": "2026-07-01T00:00:00Z"
    }
  ]
}

PUT/api/v1/ean-lookup/quotas/:provider_id

Update quota

Updates the monthly query quota for a specific product search provider.

Path parameters

Name
provider_id
Type
string
Description
Provider identifier, e.g. icecat or gs1.

Body parameters

Name
monthly_limit
Type
integer
Description
New monthly query limit for the provider.

Request

PUT

/api/v1/ean-lookup/quotas/:provider_id

curl -X PUT https://api.pixeepim.com/api/v1/ean-lookup/quotas/icecat \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "monthly_limit": 15000
  }'

Response

{
  "provider_id": "icecat",
  "monthly_limit": 15000,
  "updated_at": "2026-06-19T11:05:00Z"
}