Skip to content
ShopentlyLearn

Get a product variant

Get a product variant using Shopently API. Identifier: product_id, variant_id. Examples in cURL, PHP and Python.

GET/api/v1/products/{product_id}/variants/{variant_id}

Authentication
Bearer
Available from
STANDARD
Required permissions
catalog.product:read

Code examples

Request example

cURL

: "${SHOPENTLY_SHOP_URL:?}"

curl --disable --globoff --fail-with-body --silent --show-error \
  --proto '=https' --connect-timeout 5 --max-time 30 \
  --request GET \
  --header "Authorization: Bearer ${SHOPENTLY_ACCESS_TOKEN:?}" \
  --url "${SHOPENTLY_SHOP_URL%/}"/api/v1/products/example/variants/example

PHP

<?php
declare(strict_types=1);

$baseUrl = rtrim(getenv('SHOPENTLY_SHOP_URL') ?: '', '/');
$origin = parse_url($baseUrl);
if (!$origin || ($origin['scheme'] ?? '') !== 'https' || empty($origin['host']) ||
    isset($origin['user'], $origin['pass']) || isset($origin['user']) || isset($origin['path']) ||
    isset($origin['query']) || isset($origin['fragment'])) {
    throw new RuntimeException('SHOPENTLY_SHOP_URL must be an HTTPS origin');
}
$credential = getenv('SHOPENTLY_ACCESS_TOKEN') ?: '';
if ($credential === '' || strpbrk($credential, "\r\n") !== false) {
    throw new RuntimeException('Invalid credential');
}
$headers = [];
$headers[] = 'Authorization: Bearer ' . $credential;
$responseHeaders = [];
$handle = curl_init($baseUrl . '/api/v1/products/example/variants/example');
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HEADERFUNCTION => static function ($handle, string $line) use (&$responseHeaders): int {
        if (str_contains($line, ':')) {
            [$name, $value] = explode(':', $line, 2);
            $responseHeaders[strtolower(trim($name))] = trim($value);
        }
        return strlen($line);
    },
]);
$raw = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
$error = curl_error($handle);
curl_close($handle);
if ($raw === false) {
    throw new RuntimeException('Transport error: ' . $error);
}
if ($status < 200 || $status >= 300) {
    throw new RuntimeException('HTTP ' . $status . '; request_id=' .
        ($responseHeaders['x-request-id'] ?? '') . '; retry_after=' . ($responseHeaders['retry-after'] ?? ''));
}
$result = $raw === '' ? null : json_decode($raw, true, 512, JSON_THROW_ON_ERROR | JSON_BIGINT_AS_STRING);
echo json_encode($result, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), PHP_EOL;

Python

from contextlib import ExitStack
import json
import os
from urllib.parse import urlsplit

import requests  # python -m pip install requests

base_url = os.environ["SHOPENTLY_SHOP_URL"].rstrip("/")
origin = urlsplit(base_url)
if origin.scheme != "https" or not origin.hostname or origin.username or origin.password or origin.path or origin.query or origin.fragment:
    raise ValueError("SHOPENTLY_SHOP_URL must be an HTTPS origin")
credential = os.environ['SHOPENTLY_ACCESS_TOKEN']
if not credential or "\r" in credential or "\n" in credential:
    raise ValueError("Invalid credential")
headers = {}
headers["Authorization"] = 'Bearer' + " " + credential
body = None
if body is not None:
    headers["Content-Type"] = "application/json"

with ExitStack() as stack:
    session = stack.enter_context(requests.Session())
    files = None
    if False:
        image = stack.enter_context(open(os.environ["SHOPENTLY_IMAGE_FILE"], "rb"))
        if os.fstat(image.fileno()).st_size > 5242880:
            raise ValueError("Image exceeds 5 MiB")
        files = {"file": ("article.png", image, "image/png")}
    response = session.request(
        'GET', base_url + '/api/v1/products/example/variants/example', headers=headers,
        data=body.encode("utf-8") if body is not None else None, files=files,
        timeout=(5, 30), allow_redirects=False,
    )
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP {response.status_code}; request_id={response.headers.get('X-Request-ID', '')}; retry_after={response.headers.get('Retry-After', '')}")
    if False:
        if response.headers.get("Content-Type") != "image/webp" or len(response.content) > 5242880:
            raise ValueError("Unexpected image response")
        with open(os.environ["SHOPENTLY_OUTPUT_FILE"], "xb") as output:
            output.write(response.content)
    else:
        result = response.json() if response.content else None
        print(json.dumps(result, ensure_ascii=False, indent=2))

Response example 200

JSON
{
  "data": {
    "active": true,
    "created_at": "2026-01-01T12:00:00Z",
    "id": "example",
    "is_default": true,
    "media_ids": [
      "example"
    ],
    "position": 1,
    "pricing": {
      "base_adjustment": {
        "amount": "0.00",
        "currency": "PLN",
        "minor_units": 2
      },
      "market_price": null,
      "price": {
        "amount": "0.00",
        "currency": "PLN",
        "minor_units": 2,
        "tax_included": true
      },
      "product_version": 1,
      "version": 1
    },
    "primary_media_id": "example",
    "product_id": "example",
    "sku": "example",
    "updated_at": "2026-01-01T12:00:00Z",
    "values": [
      {
        "option_id": "example",
        "option_name": "example",
        "value": "example",
        "value_id": "example"
      }
    ],
    "version": 1
  },
  "meta": {
    "locale": "en",
    "market_code": "PL",
    "market_id": "example",
    "request_id": "example"
  }
}

How it works

  • A variant belongs to a product and uses values from the variant-option dictionaries.
  • The reference includes option and value CRUD as well as product-variant reads and writes.
  • Variant price changes use the explicit pricing kind, amount, currency and required versions.
  • Distinguish a base adjustment from a fixed market price.
  • Read current product and price state before submitting a dependent update.

Parameters

Path parameters

product_idStringRequired

Product identifier.

Constraints
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
Example: "example"
variant_idStringRequired

Product variant identifier.

Constraints
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
Example: "example"

Query parameters

localeString nullOptional

Language selected for this request.

String:minLength: 2maxLength: 20
market_idString nullOptional

Market identifier returned by the context endpoint.

Constraints · String 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
market_codeString nullOptional

Market code returned by the context endpoint.

String:minLength: 1maxLength: 16

This operation does not accept a JSON body.

Responses

Response 200

dataProductVariantData Required

Successful response payload.

Fields · data
activeBooleanRequired

Whether the resource is active.

created_atStringRequired

Creation time.

format: "date-time"
idStringRequired

Resource identifier; preserve it as returned.

is_defaultBooleanRequired

Whether this is the default choice.

media_idsArray <String> Required

Identifiers of already existing media assets.

positionIntegerRequired

Position in the ordered collection.

pricingVariantPricingData Required

Price configuration and its concurrency versions.

Fields · pricing
base_adjustmentMoneyData Required

Price adjustment relative to the base price.

market_priceMoneyData nullRequired

Price for the selected market.

pricePriceData nullRequired

Price information in the selected context.

product_versionIntegerRequired

Current product version for concurrency control.

versionIntegerRequired

Resource version used for concurrency control.

primary_media_idString nullRequired

Primary media asset identifier.

product_idStringRequired

Product identifier.

skuStringRequired

Stock keeping unit code.

updated_atStringRequired

Most recent update time.

format: "date-time"
valuesArray <VariantChoiceData > Required

Dictionary values.

Fields · values
versionIntegerRequired

Resource version used for concurrency control.

metaContextPageMeta ContextMeta PageMeta RequestMeta Required

Response metadata.

Fields · meta

ContextPageMeta

localeStringRequired

Language selected for this request.

market_codeStringRequired

Market code returned by the context endpoint.

market_idStringRequired

Market identifier returned by the context endpoint.

paginationPagination Required

Cursor pagination metadata.

request_idStringRequired

Request identifier; in response metadata this identifies the HTTP request.

minLength: 1maxLength: 100

ContextMeta

localeStringRequired

Language selected for this request.

market_codeStringRequired

Market code returned by the context endpoint.

market_idStringRequired

Market identifier returned by the context endpoint.

request_idStringRequired

Request identifier; in response metadata this identifies the HTTP request.

minLength: 1maxLength: 100

PageMeta

paginationPagination Required

Cursor pagination metadata.

request_idStringRequired

Request identifier; in response metadata this identifies the HTTP request.

minLength: 1maxLength: 100

RequestMeta

request_idStringRequired

Request identifier; in response metadata this identifies the HTTP request.

minLength: 1maxLength: 100
Response example

HTTP status

200
Successful response Schema
400
Invalid request
401
Authentication required
403
Permission denied
404
Resource not found
409
Version conflict
422
Validation failed
429
Rate limit exceeded
Other HTTP statuses (7)
405
Method not allowed
413
Request too large
415
Unsupported media type
500
Server error
502
API gateway error
503
Service unavailable
504
Gateway timeout

Error catalog: ErrorResponse

Headers

401

WWW-AuthenticateStringOptional

Authentication scheme required by the server.

405

AllowStringOptional

HTTP methods supported by this resource.

429, 503

Retry-AfterIntegerOptional

Minimum delay before retrying, in seconds.

minimum: 0