Skip to main content
GET
/
v1
/
entitlements
List Entitlements
curl --request GET \
  --url https://api.paygentic.io/v1/entitlements \
  --header 'Authorization: Bearer <token>'
import requests

url = "https://api.paygentic.io/v1/entitlements"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.paygentic.io/v1/entitlements', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.paygentic.io/v1/entitlements",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.paygentic.io/v1/entitlements"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.paygentic.io/v1/entitlements")
  .header("Authorization", "Bearer <token>")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.paygentic.io/v1/entitlements")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
{
  "object": "list",
  "data": [
    {
      "entitlementId": "ent_a7b8c9d0e1f2g3h4",
      "customerId": "cus_q3r4s5t6u7v8w9x0",
      "featureId": "feat_max_users",
      "featureKey": "max_users",
      "featureType": "static",
      "productId": "prod_m5n6o7p8q9r0s1t2",
      "subscriptionId": "sub_pro_plan",
      "status": "active",
      "activeFrom": "2024-01-01T00:00:00Z",
      "activeTo": "2025-01-01T00:00:00Z",
      "hasAccess": true,
      "metadata": {},
      "config": {
        "limit": 25
      }
    },
    {
      "entitlementId": "ent_b8c9d0e1f2g3h4i5",
      "customerId": "cus_q3r4s5t6u7v8w9x0",
      "featureId": "feat_sso_enabled",
      "featureKey": "sso_enabled",
      "featureType": "boolean",
      "productId": "prod_m5n6o7p8q9r0s1t2",
      "subscriptionId": "sub_pro_plan",
      "status": "active",
      "activeFrom": "2024-01-01T00:00:00Z",
      "activeTo": null,
      "hasAccess": true,
      "metadata": {},
      "config": null
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 2
  }
}

Authorizations

​
Authorization
string
header
required

API key authentication

Query Parameters

​
customerId
string

The Paygentic customer id to retrieve entitlements for. Supply exactly one of customerId or externalCustomerId. When combined with merchantId, the customer must belong to that merchant or the request resolves to not found. Unique identifier for a customer

Pattern: ^cus_[a-zA-Z0-9]+$
​
externalCustomerId
string

The merchant's own external customer reference (Customer.externalId, exact match), used to retrieve entitlements without first resolving it to a cus_ id. Matches the externalId filter on GET /v1/customers (plain string, exact match — no pattern constraint, so any stored externalId is addressable). Supply exactly one of customerId or externalCustomerId. externalId is unique only within a merchant, so an effective merchant scope is required: either pass merchantId, or authenticate with a single-merchant API key. With no resolvable merchant scope the request is rejected.

Required string length: 1 - 255
​
merchantId
string

Optional merchant scope. With externalCustomerId it selects the merchant the external id is resolved within (required for the platform key, which has no single merchant). With customerId it acts as a tenant guard — the resolved customer must belong to this merchant, otherwise the request resolves to not found. A passed merchantId is only a filter and never grants access the caller does not already hold; authorization is always evaluated against the resolved customer's merchant. Unique identifier for an organization

Pattern: ^org_[a-zA-Z0-9]+$
​
featureKey
string

Filter results to a specific feature by its key. When specified, productId is also required. Use this to check access to a single feature.

​
productId
string

Filter results to entitlements for a specific product. Required when featureKey is specified since feature keys are scoped to products. Unique identifier for a product

Pattern: ^prod_[a-zA-Z0-9]+$
​
subscriptionId
string

Filter results to entitlements for a specific subscription. Unique identifier for a subscription

Pattern: ^sub_[a-zA-Z0-9]+$
​
limit
integer
default:10

Maximum number of entitlements to return per page. Use with offset for pagination.

Required range: 1 <= x <= 100
​
offset
integer
default:0

Number of entitlements to skip. Use with limit for pagination through large result sets.

Required range: x >= 0
​
at
string<date-time>

Evaluate balance and access at this point in time (RFC 3339 datetime with any UTC offset, e.g. 2024-01-15T10:30:00Z or 2024-01-15T15:30:00+05:30). Defaults to current time.

Response

Successfully retrieved the list of entitlements for the customer.

​
object
enum<string>
default:list
required
Available options:
list
​
data
object[]
required

Array of entitlement list items. The shape of each item varies by featureType.

An entitlement as returned by the list endpoint. The shape varies by featureType. Uses entitlementId (not id) for backwards compatibility with the original list contract.

​
pagination
object
required

Offset-based pagination response.