Skip to content
ShopentlyLearn

Promotions · Get

Promotions · Get. Every code must allow combinations. Discounts apply in order.

GET/api/v1/discounts/promotions/{identity}

Authentication
Bearer
Available from
STANDARD
Required permissions
discounts.promotions: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/discounts/promotions/example-campaign

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/discounts/promotions/example-campaign');
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/discounts/promotions/example-campaign', 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": {
    "created_at": "2026-10-07T10:00:00Z",
    "created_by": {
      "kind": "admin",
      "label": "Editorial integration",
      "reference": "learn-api-key"
    },
    "enabled": false,
    "id": "example-campaign",
    "kind": "coupon",
    "markets": [
      {
        "currency": "PLN",
        "market_id": "poland",
        "minor_units": 0
      }
    ],
    "name": "Autumn guide offer",
    "updated_at": "2026-10-07T10:00:00Z",
    "used_count": 0,
    "version": 1
  },
  "meta": {
    "locale": "example",
    "market_code": "example",
    "market_id": "poland",
    "pagination": {
      "has_more": false,
      "limit": 1,
      "next_cursor": null
    },
    "request_id": "learn-example-request"
  }
}

Overview

Selected products and categories are combined. Categories include directly assigned products.

Parameters

Path parameters

identityStringRequired

Identifier used in this resource path.

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

This operation does not accept a JSON body.

Responses

Response 200

dataCampaignData Required

Successful response payload.

Fields · data
audienceStringOptional

Customers

Constraints
enum
["all", "guest", "customer", "selected"]

Default: "all"

benefit_typeStringOptional

Variant of the data structure described by its allowed values.

Constraints
enum
["percentage", "fixed", "none"]

Default: "percentage"

category_idsArray <String> Optional

Identifiers of related categories.

maxItems: 1000
Constraints · Array 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
codeString nullOptional

Stable machine-readable code.

Constraints · String 1
pattern
"^[A-Za-z0-9]{6,16}$"
combine_couponsBooleanOptional

Combine with other codes

Default: false

combine_promotionsBooleanOptional

Allow this code on products with automatic promotions

Default: false

created_atStringRequired

Creation time.

format: "date-time"
created_byCreatorData Required

Created by

Fields · created_by
kindStringRequired

Variant of the data structure described by its allowed values.

Constraints
enum
["admin", "api"]
labelStringRequired

Resource name in the relevant context.

referenceStringRequired

Identifier of the referenced entity.

customer_idsArray <String> Optional

Customer information recorded for this resource.

maxItems: 1000
Constraints · Array 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
enabledBooleanRequired

Whether this setting is enabled.

ends_atString nullOptional

Active until

String:format: "date-time"
free_shippingBooleanOptional

Free shipping

Default: false

idStringRequired

Resource identifier; preserve it as returned.

kindStringRequired

Variant of the data structure described by its allowed values.

Constraints
enum
["coupon", "promotion"]
minimum_quantityIntegerOptional

Minimum number of items in cart

minimum: 1maximum: 2147483647

Default: 1

nameStringRequired

Resource name in the relevant context.

minLength: 1maxLength: 160
per_customer_limitIntegerOptional

Usage limit per customer

minimum: -1maximum: 2147483647

Default: -1

percentageStringOptional

Percentage

maxLength: 19
Constraints
pattern
"^(0|[1-9][0-9]{0,13})(\\.[0-9]{1,4})?$"

Default: "10"

product_idsArray <String> Optional

Identifiers of related products.

maxItems: 1000
Constraints · Array 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
product_scopeStringOptional

Products

Constraints
enum
["all", "selected"]

Default: "all"

show_accountBooleanOptional

In the customer account

Default: false

show_cartBooleanOptional

In the cart

Default: false

show_productBooleanOptional

On product pages

Default: false

starts_atString nullOptional

Active from

String:format: "date-time"
updated_atStringRequired

Most recent update time.

format: "date-time"
usage_limitIntegerOptional

Usage limit

minimum: -1maximum: 2147483647

Default: -1

used_countIntegerRequired

Times used

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