Countera
Auth Public site
Developer Docs / API / Products

External product price delta API

Use this GraphQL API to sync product variant price changes into external systems such as electronic shelf labels. The API supports delta sync by variant update timestamp and direct lookup by variant id.

Access and endpoint

GraphQL queryDelta syncVariant prices

All requests go through the Countera GraphQL endpoint:

POST https://{your-countera-domain}/graphql
Content-Type: application/json
Authorization: Bearer {token}

Authenticate first using the login mutation documented in Authentication and bearer tokens.

GraphQL query

The external product price delta API is exposed through the public GraphQL field externalProductPrices.

query ExternalProductPrices(
  $variantId: ID
  $locationId: ID
  $variantUpdatedSince: DateTime
  $page: Int
  $size: Int
) {
  externalProductPrices(
    variantId: $variantId
    locationId: $locationId
    variantUpdatedSince: $variantUpdatedSince
    page: $page
    size: $size
  ) {
    page
    totalRecords
    variants {
      variantId
      name
      upc
      ean
      sku
      sellUomCode
      locationId
      basePrice
      salePrice
      currency
    }
  }
}

Provide either variantId for a direct lookup or variantUpdatedSince for a delta sync. If neither is supplied, the API returns an error.

Delta sync request

Use this mode to retrieve variants changed after the last successful sync cursor. The cursor should be an ISO-8601 instant in UTC.

curl -X POST "https://api.example.countera.ai/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COUNTERA_TOKEN" \
  -d '{
    "query": "query ExternalProductPrices($locationId: ID, $variantUpdatedSince: DateTime, $page: Int, $size: Int) { externalProductPrices(locationId: $locationId, variantUpdatedSince: $variantUpdatedSince, page: $page, size: $size) { page totalRecords variants { variantId name upc ean sku sellUomCode locationId basePrice salePrice currency } } }",
    "variables": {
      "locationId": "0c59b311-9af6-41d9-8b79-8b855a963efa",
      "variantUpdatedSince": "2026-09-27T00:00:00Z",
      "page": 0,
      "size": 200
    }
  }'

Variables

{
  "locationId": "0c59b311-9af6-41d9-8b79-8b855a963efa",
  "variantUpdatedSince": "2026-09-27T00:00:00Z",
  "page": 0,
  "size": 200
}

Response

{
  "data": {
    "externalProductPrices": {
      "page": 0,
      "totalRecords": 1284,
      "variants": [
        {
          "variantId": "b044f02c-c945-4330-bed6-c7152c42dace",
          "name": "Banana Plantain per lb",
          "upc": "100000078150",
          "ean": null,
          "sku": "FP1060",
          "sellUomCode": "LB",
          "locationId": "0c59b311-9af6-41d9-8b79-8b855a963efa",
          "basePrice": 0.99,
          "salePrice": null,
          "currency": "USD"
        }
      ]
    }
  }
}

Single variant request

Use this mode when your system already knows the Countera variant id and needs the current price row for that variant. You may include locationId to return only that store's price.

curl -X POST "https://api.example.countera.ai/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COUNTERA_TOKEN" \
  -d '{
    "query": "query ExternalProductPrices($variantId: ID!, $locationId: ID) { externalProductPrices(variantId: $variantId, locationId: $locationId) { page totalRecords variants { variantId name upc ean sku sellUomCode locationId basePrice salePrice currency } } }",
    "variables": {
      "variantId": "b044f02c-c945-4330-bed6-c7152c42dace",
      "locationId": "0c59b311-9af6-41d9-8b79-8b855a963efa"
    }
  }'

Response

{
  "data": {
    "externalProductPrices": {
      "page": 0,
      "totalRecords": 1,
      "variants": [
        {
          "variantId": "b044f02c-c945-4330-bed6-c7152c42dace",
          "name": "Banana Plantain per lb",
          "upc": "100000078150",
          "ean": null,
          "sku": "FP1060",
          "sellUomCode": "LB",
          "locationId": "0c59b311-9af6-41d9-8b79-8b855a963efa",
          "basePrice": 0.99,
          "salePrice": null,
          "currency": "USD"
        }
      ]
    }
  }
}

Request fields

ArgumentTypeRequiredDescription
variantIdIDConditionalCountera product variant UUID. If supplied, the API returns prices for this variant.
locationIdIDNoStore/location UUID. When supplied, returns only the matching store price. When omitted, returns all available store price rows or the global variant price.
variantUpdatedSinceDateTimeConditionalUTC ISO-8601 timestamp used for delta sync. Required when variantId is omitted.
pageIntNoZero-based page number for delta sync. Defaults to 0.
sizeIntNoPage size for delta sync. Defaults to 200. Maximum accepted size is 500.
Required filter rule: send either variantId or variantUpdatedSince. Sending neither is invalid.

Response fields

FieldTypeDescription
pageIntZero-based page number returned by the API.
totalRecordsLongTotal matching product records for the request. For direct variant lookup, this is the number of returned variant price rows.
variantsExternalProductPrice[]List of variant price rows for the requested page or variant lookup.
variants[].variantIdIDCountera product variant UUID.
variants[].nameStringVariant display name or variant name.
variants[].upcStringVariant UPC, when available.
variants[].eanStringVariant EAN, when available.
variants[].skuStringCountera SKU.
variants[].sellUomCodeStringSelling unit of measure code, such as EA or LB.
variants[].locationIdIDStore/location UUID for store-scoped price rows. May be null for global variant price rows.
variants[].basePriceFloatPrimary selling price. ESL integrations should use this as the shelf price.
variants[].salePriceFloatOptional promotional sale price from the price row, when populated.
variants[].currencyStringCurrency code, normally USD.

Errors

ConditionExpected resultResolution
No tokenRequest rejected as unauthenticated.Call login and pass the bearer token.
No variantId and no variantUpdatedSinceGraphQL error from pricing service.Provide one of the two required filters.
Unknown variantIdvariants is empty and totalRecords is 0.Confirm the variant id exists and is active in Countera.

Sync guidance

  • Use UTC timestamps for variantUpdatedSince, for example 2026-09-27T00:00:00Z.
  • Advance your cursor only after processing the full page successfully.
  • Use page and size for backfills or large change windows.
  • For store-specific ESL systems, always send locationId so you receive the price for that store only.
  • Use basePrice as the canonical shelf price unless Countera explicitly instructs your integration to use salePrice.