The API reference isn't available right now
This instance couldn't load its API specification. The reference returns as soon as the specification is readable again.
Back to the API reference
No such operation
This instance documents no operation under that identifier. It may have been renamed, or it may belong to a feature this installation hasn't enabled.
Back to the API reference
This reference may be out of date
This instance couldn't reach its API specification on the last attempt, so this page shows the copy fetched before that. Anything added or changed since then is missing here, and the reference updates itself as soon as the specification is readable again. Last fetched 2026-10-22 22:09 UTC.
API reference
/
UserFavorites
Lists the operating user's favorites.
GET
/api/favorites/user
deprecated
Requires: Favorites.Manage, merchant scope.
Requires API key scope:
admin
(Administration)
Bucketed by whether they match the current operating context.
Results are split into two buckets: `inContext` (favorites whose stored scope matches the request's
operating context) is always populated; `outOfContext` is populated only when
`includeAllContexts` is `true`, otherwise it is empty.
This read also performs lazy upkeep: each favorite is re-validated against the owning entity's current
authorization and visibility, and any pin the user can no longer see (entity deleted, access revoked) is
quietly removed from their own list. Out-of-context favorites are not treated as orphans.
Signed in, you can send this request to your own sandbox merchant from the console
and read the answer.
Sign in to try it .
On this page
Example request
Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key.
The request body is a . See the Request body section below for its fields.
Code sample language >_
cURL PS
PowerShell TS
TypeScript C#
C# Py
Python
Copythe install command for cURL
Copied
Copy failed
cURL CopycURL
Copied
Copy failed
curl -X GET "{{BASE_URL}}/api/favorites/user" \
-H "api-key: {{API_KEY}}"
Copythe install command for PowerShell
Copied
Copy failed
PowerShell CopyPowerShell
Copied
Copy failed
$headers = @{
'api-key' = '{{API_KEY}}'
}
$response = Invoke-RestMethod -Method GET -Uri '{{BASE_URL}}/api/favorites/user' `
-Headers $headersnpm install @winkpg/winkpg-api
Copythe install command for TypeScript (SDK)
Copied
Copy failed
TypeScript (SDK) CopyTypeScript (SDK)
Copied
Copy failed
import { Configuration, UserFavoritesApi } from '@winkpg/winkpg-api';
const api = new UserFavoritesApi(new Configuration({
basePath: '{{BASE_URL}}',
apiKey: '{{API_KEY}}',
}));
const { data } = await api.userFavoritesGetMyFavorites();
Copythe install command for TypeScript (raw HTTP)
Copied
Copy failed
TypeScript (raw HTTP) CopyTypeScript (raw HTTP)
Copied
Copy failed
const response = await fetch('{{BASE_URL}}/api/favorites/user', {
method: 'GET',
headers: {
"api-key": "{{API_KEY}}",
},
});
const data = await response.json();dotnet add package WinkPg.Api.Client
Copythe install command for C# (SDK)
Copied
Copy failed
C# (SDK) CopyC# (SDK)
Copied
Copy failed
using WinkPg.Api.Client.Api;
using WinkPg.Api.Client.Client;
var config = new Configuration { BasePath = "{{BASE_URL}}" };
config.AddApiKey("api-key", "{{API_KEY}}");
var api = new UserFavoritesApi(config);
var result = await api.UserFavoritesGetMyFavoritesAsync();
Copythe install command for C# (raw HTTP)
Copied
Copy failed
C# (raw HTTP) CopyC# (raw HTTP)
Copied
Copy failed
using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };
var request = new HttpRequestMessage(new HttpMethod("GET"), "/api/favorites/user");
request.Headers.Add("api-key", "{{API_KEY}}");
var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();pip install winkpg-api
Copythe install command for Python (SDK)
Copied
Copy failed
Python (SDK) CopyPython (SDK)
Copied
Copy failed
import winkpg_api
configuration = winkpg_api.Configuration(host="{{BASE_URL}}")
configuration.api_key["ApiKey"] = "{{API_KEY}}"
with winkpg_api.ApiClient(configuration) as client:
api = winkpg_api.UserFavoritesApi(client)
result = api.user_favorites_get_my_favorites()pip install requests
Copythe install command for Python (raw HTTP)
Copied
Copy failed
Python (raw HTTP) CopyPython (raw HTTP)
Copied
Copy failed
import requests
headers = {
"api-key": "{{API_KEY}}",
}
response = requests.request(
"GET",
"{{BASE_URL}}/api/favorites/user",
headers=headers,
)
response.raise_for_status()
data = response.json()
Parameters
Name
In
Type
Description
IncludeAllContexts
required
query
boolean
When true, the response also populates `outOfContext`
with favorites stored under a different operating context.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
EntityType
required
query
string
Optional entity-type filter. When set, only favorites of this entity type are returned.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
suppressNulls
required
query
boolean
If true, omit properties with null values.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Request body
application/json
, required
This request body has no documented fields.
Responses 200
OK
Body:
UserFavoritePageDto
UserFavoritePageDto
Each item has these fields.
Field
Type
Description
inContext
required
array of UserFavoriteDto
array of UserFavoriteDto
Favorites whose stored context matches the request's operating context.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Fields of each UserFavoriteDto:
Field
Type
Description
id
required
string (uuid)
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
creationTime
required
string (date-time)
The date and time when this entity was created.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
creatorId
required
string (uuid)
The ID of the user who created this entity.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lastModificationTime
required
string (date-time)
The date and time when this entity was last modified.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lastModifierId
required
string (uuid)
The ID of the user who last modified this entity.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isDeleted
required
boolean
Indicates whether this entity has been deleted.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
deleterId
required
string (uuid)
The ID of the user who deleted this entity, if it is deleted.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
deletionTime
required
string (date-time)
The date and time when this entity was deleted, if it is deleted.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
userId
required
string (uuid)
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
tenantId
required
string (uuid)
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
resellerId
required
string (uuid)
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
merchantId
required
string (uuid)
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
entityType
required
string
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
entityId
required
string (uuid)
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
scope
required
FavoriteScope
FavoriteScope
Organizational scope for a pinned favorite.
Determines which operating-context fields the favorite is bound to.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
label
required
string
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
subtitle
required
string
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
route
required
string
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
pinnedAtUtc
required
string (date-time)
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
inContext
required
boolean
True if this favorite's stored context matches the request's operating context.
Computed server-side after lazy validation.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
This body has no documented fields.
outOfContext
required
array of UserFavoriteDto
array of UserFavoriteDto
Favorites stored under a different operating context. Empty unless
`includeAllContexts` is true.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Fields of each UserFavoriteDto:
Field
Type
Description
id
required
string (uuid)
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
creationTime
required
string (date-time)
The date and time when this entity was created.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
creatorId
required
string (uuid)
The ID of the user who created this entity.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lastModificationTime
required
string (date-time)
The date and time when this entity was last modified.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lastModifierId
required
string (uuid)
The ID of the user who last modified this entity.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isDeleted
required
boolean
Indicates whether this entity has been deleted.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
deleterId
required
string (uuid)
The ID of the user who deleted this entity, if it is deleted.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
deletionTime
required
string (date-time)
The date and time when this entity was deleted, if it is deleted.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
userId
required
string (uuid)
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
tenantId
required
string (uuid)
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
resellerId
required
string (uuid)
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
merchantId
required
string (uuid)
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
entityType
required
string
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
entityId
required
string (uuid)
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
scope
required
FavoriteScope
FavoriteScope
Organizational scope for a pinned favorite.
Determines which operating-context fields the favorite is bound to.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
label
required
string
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
subtitle
required
string
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
route
required
string
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
pinnedAtUtc
required
string (date-time)
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
inContext
required
boolean
True if this favorite's stored context matches the request's operating context.
Computed server-side after lazy validation.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
This body has no documented fields.
totalCount
required
integer (int32)
Total favorites across both buckets.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
This response has no documented body fields.
403
Forbidden
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
Field
Type
Description
error
required
RemoteServiceErrorInfo
RemoteServiceErrorInfo
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
This response has no documented body fields.
401
Unauthorized
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
Field
Type
Description
error
required
RemoteServiceErrorInfo
RemoteServiceErrorInfo
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
This response has no documented body fields.
400
Bad Request
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
Field
Type
Description
error
required
RemoteServiceErrorInfo
RemoteServiceErrorInfo
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
This response has no documented body fields.
404
Not Found
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
Field
Type
Description
error
required
RemoteServiceErrorInfo
RemoteServiceErrorInfo
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
This response has no documented body fields.
501
Not Implemented
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
Field
Type
Description
error
required
RemoteServiceErrorInfo
RemoteServiceErrorInfo
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
This response has no documented body fields.
500
Internal Server Error
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
Field
Type
Description
error
required
RemoteServiceErrorInfo
RemoteServiceErrorInfo
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
This response has no documented body fields.
default
The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The error reference lists the values `error.code` can take.
The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The error reference lists the values `error.code` can take.
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
Field
Type
Description
error
required
RemoteServiceErrorInfo
RemoteServiceErrorInfo
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
This response has no documented body fields.
429
The request was refused because a rate limit was exceeded, or because something a later retry can clear stopped it. A rate limit refusal carries an `application/problem+json` body: wait at least the interval `Retry-After` names before retrying, then back off. Limits are tuned per deployment, so read the allowance from the response headers rather than assuming a fixed ceiling. Any other refusal carries the standard error envelope as `application/json`, and its `error.code` names the cause.
Body:
RemoteServiceErrorResponse
RemoteServiceErrorResponse
Each item has these fields.
Field
Type
Description
error
required
RemoteServiceErrorInfo
RemoteServiceErrorInfo
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
This response has no documented body fields.
Errors
A failed request returns the platform error envelope. The
error reference lists every value
error.code can carry and shows the four response shapes.
Codes declared by
Next steps