openapi: 3.1.0
info:
title: Clerk.io API
version: '2'
description: 'Clerk.io e-commerce personalisation REST API. Ingest and manage catalog data (products, categories, pages,
orders, order parcels, customers, accessories), run behaviour-ranked search and predictive search-as-you-type, request
recommendation logics (popular, trending, new, complementary, substituting, visitor- and customer-personalised, category-
and page-scoped), manage merchandising (custom search configurations, synonyms, redirects), drive audiences/campaigns/subscribers
for email, log visitor behaviour events, and service GDPR privacy requests.
All endpoints live under https://api.clerk.io/v2. Authentication uses a dual-key model: the public `key` identifies the
store and is safe in browser-side calls; `private_key` is additionally required for write and sensitive operations and
MUST only be sent over SSL.'
contact:
name: Clerk.io Documentation
url: https://docs.clerk.io/
x-provenance:
method: searched
harvested: '2026-08-13'
source: https://docs.clerk.io/reference/ (ReadMe API Designer OpenAPI 3.1.0 fragments per reference page)
original: openapi/_original/clerk-io-api-settings-openapi-original.yml
note: Provider-published operation content is verbatim. API Evangelist added the document title/description, tags[] declarations
and per-operation tag assignment; see overlays/clerk-io-api-overlay.yaml.
servers:
- url: https://api.clerk.io/v2
components:
securitySchemes:
sec0:
type: apiKey
name: key
in: query
x-default: your_api_key
security:
- sec0: []
paths:
/accessories:
get:
summary: /accessories
description: ''
operationId: accessories-get
parameters:
- name: key
in: query
description: Your stores public API key.
required: true
schema:
type: string
- name: private_key
in: query
description: Your stores private API key.
required: true
schema:
type: string
- name: accessories
in: query
description: List of product ID's to get the data for.
schema:
type: array
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{'status': 'ok',\n 'accessories':[\n \t{'product': 'AV-DHONO',\n \t 'accessories': ['JBL-GO'],\n\
\ \t 'directed_accessories': ['LDY84']}\n ]\n }"
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Accessories
post:
summary: /accessories
description: ''
operationId: accessories-post
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
properties:
key:
type: string
description: Your stores public API key.
private_key:
type: string
description: Your stores private API key.
accessories:
type: array
description: list of accessory objects
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{''status'': ''ok''}'
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Accessories
patch:
summary: /accessories
description: ''
operationId: accessories-patch
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
properties:
key:
type: string
description: Your stores public API key.
private_key:
type: string
description: Your stores private API key.
accessories:
type: array
description: list of accessory objects
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{''status'': ''ok''}'
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Accessories
delete:
summary: /accessories
description: ''
operationId: accessories-delete
parameters:
- name: key
in: query
description: Your stores public API key.
required: true
schema:
type: string
- name: private_key
in: query
description: Your stores private API key.
required: true
schema:
type: string
- name: accessories
in: query
description: List of product ID's to delete accessories for
schema:
type: array
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{''status'': ''ok'' }'
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Accessories
/audiences:
get:
summary: /audiences
description: ''
operationId: audiences-get
parameters:
- name: key
in: query
description: The public key of the store
required: true
schema:
type: string
- name: private_key
in: query
description: The private key of the store
required: true
schema:
type: string
- name: ids
in: query
description: The ids of the audiences to fetch
schema:
type: array
items:
type: integer
format: int32
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Audiences
post:
summary: /audiences
description: ''
operationId: audiences-post
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
properties:
key:
type: string
description: The public key of the store
private_key:
type: string
description: The private key of the store
audiences:
type: array
description: The list of audiences to create
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Audiences
patch:
summary: /audiences
description: ''
operationId: audiences-patch
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
properties:
key:
type: string
description: The public key of the store
private_key:
type: string
description: The private key of the store
audiences:
type: array
description: The list of audiences to update
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Audiences
delete:
summary: /audiences
description: ''
operationId: audiences-delete
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
properties:
key:
type: string
description: The public key of the store
private_key:
type: string
description: The private key of the store
ids:
type: array
description: The ids of the audiences to delete
items:
type: integer
format: int32
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Audiences
/audiences/emails:
get:
summary: /audiences/emails
description: ''
operationId: audiencesemails
parameters:
- name: key
in: query
description: The public key of the store
required: true
schema:
type: string
- name: private_key
in: query
description: The private key of the store
required: true
schema:
type: string
- name: id
in: query
description: The id for the audience to fetch all emails from.
required: true
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{''status'':''ok'',
''audiences'':[''a@a.a'',''b@b.gmail'']}'
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Audiences
/audiences/list:
get:
summary: /audiences/list
description: ''
operationId: audienceslist
parameters:
- name: key
in: query
description: The public key of the store
required: true
schema:
type: string
- name: private_key
in: query
description: The private key of the store
required: true
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{''status'':''ok''}'
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Audiences
/campaigns/click:
get:
summary: campaigns/click
description: Redirect the customer to the product corresponding to the previously rendered image from campaigns/embed.
operationId: campaigns-click
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: email
in: query
description: The email of the customer to load the recommendation for.
required: true
schema:
type: string
- name: embed
in: query
description: ID of the Hosted Template to be embedded.
required: true
schema:
type: string
- name: n
in: query
description: Loading the n-th product in the set of recommended products. n is 0-indexed.
required: true
schema:
type: integer
format: int32
- name: v
in: query
description: Unique version number of the email (ideally a random number per email or else a campaign id or date string).
required: true
schema:
type: string
- name: append
in: query
description: Append this string to the redirect link URL.
schema:
type: string
- name: prepend
in: query
description: Prepend this string to the redirect URL.
schema:
type: string
- name: filter
in: query
description: An attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "// Redirects to the product URL.\n\n{\n \"status\": \"ok\"\n}"
Error:
value: "{\n \"status\": \"error\",\n \"message\": \"A message explaining the error.\",\n \"moreInfo\"\
: \"http://help.clerk.io/error/{ERROR_ID}\",\n \"type\": \"ErrorType\",\n \"id\": \"{ERROR_ID}\"\n}"
schema:
oneOf:
- type: object
properties:
status:
type: string
example: ok
- title: Error
type: object
properties:
status:
type: string
example: error
message:
type: string
example: A message explaining the error.
moreInfo:
type: string
example: http://help.clerk.io/error/{ERROR_ID}
type:
type: string
example: ErrorType
id:
type: string
example: '{ERROR_ID}'
deprecated: false
x-readme:
code-samples:
- language: curl
code: curl http://api.clerk.io/v2/campaigns/click?key=store_api_key&email=john@doe.com&embed=reciept-email&n=0&v=1234567890&filter=price+>+10
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"email\": \"john@doe.com\",\n \"embed\": \"reciept-email\",\n \"n\": 0,\n \
\ \"v\": 1234567890,\n \"filter\": \"price > 10\"}' \\\n http://api.clerk.io/v2/campaigns/click"
name: POST
samples-languages:
- curl
tags:
- Campaigns
/campaigns/embed:
get:
summary: campaigns/embed
description: Render a recommendation onto a dynamic image for embedding dynamic content in a email.
operationId: campaigns-embed
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: email
in: query
description: The email of the customer to load the recommendation for.
required: true
schema:
type: string
- name: embed
in: query
description: ID of the Hosted Template to be embedded.
required: true
schema:
type: string
- name: n
in: query
description: Loading the n-th product in the set of recommended products. n is 0-indexed.
required: true
schema:
type: integer
format: int32
- name: v
in: query
description: Unique version number of the email (ideally a random number per email or else a campaign id or date string).
required: true
schema:
type: string
- name: append
in: query
description: Append this string to the redirect link URL.
schema:
type: string
- name: prepend
in: query
description: Prepend this string to the redirect URL.
schema:
type: string
- name: filter
in: query
description: An attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "// Redirects to the dynamically generated image on success.\n\n{\n \"status\": \"ok\"\n}"
Error:
value: "{\n \"status\": \"error\",\n \"message\": \"A message explaining the error.\",\n \"moreInfo\"\
: \"http://help.clerk.io/error/{ERROR_ID}\",\n \"type\": \"ErrorType\",\n \"id\": \"{ERROR_ID}\"\n}"
schema:
oneOf:
- type: object
properties:
status:
type: string
example: ok
- title: Error
type: object
properties:
status:
type: string
example: error
message:
type: string
example: A message explaining the error.
moreInfo:
type: string
example: http://help.clerk.io/error/{ERROR_ID}
type:
type: string
example: ErrorType
id:
type: string
example: '{ERROR_ID}'
deprecated: false
x-readme:
code-samples:
- language: curl
code: curl http://api.clerk.io/v2/campaigns/embed?key=store_api_key&email=john@doe.com&embed=reciept-email&n=0&v=1234567890&filter=price+>+10
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"email\": \"john@doe.com\",\n \"embed\": \"reciept-email\",\n \"n\": 0,\n \
\ \"v\": 1234567890,\n \"filter\": \"price > 10\"}' \\\n http://api.clerk.io/v2/campaigns/embed"
name: POST
samples-languages:
- curl
tags:
- Campaigns
/categories:
get:
summary: /categories
description: Get categories from Clerk.io
operationId: categories-get
parameters:
- name: key
in: query
description: Your stores public API key.
required: true
schema:
type: string
- name: private_key
in: query
description: Your stores private API key.
required: true
schema:
type: string
- name: categories
in: query
description: List of category ID's to get the data for.
required: true
schema:
type: array
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: ''
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Catalog
post:
summary: /categories
description: Add or update categories in Clerk.io
operationId: categories-post
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- categories
properties:
key:
type: string
description: Your stores public API key.
private_key:
type: string
description: Your stores private API key.
categories:
type: array
description: List of [categories](/reference/category-resource) to add or update.
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{"status":"ok"}'
schema:
type: object
properties:
status:
type: string
example: ok
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Catalog
patch:
summary: /categories
description: Patch existing categories in Clerk.io with new attributes or values.
operationId: categories-patch
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- categories
properties:
key:
type: string
description: You stores public API key.
private_key:
type: string
description: Your stores private API key.
categories:
type: array
description: List of partial category objects.
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{"status":"ok"}'
schema:
type: object
properties:
status:
type: string
example: ok
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Catalog
/customers:
get:
summary: /customers
description: Get customers from Clerk.io
operationId: customers-get
parameters:
- name: key
in: query
description: Your stores public API key.
required: true
schema:
type: string
- name: private_key
in: query
description: Your stores private API key.
required: true
schema:
type: string
- name: customers
in: query
description: List of customers emails to get the data for.
required: true
schema:
type: array
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: ''
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Catalog
post:
summary: /customers
description: Add or update customers in Clerk.io
operationId: customers-post
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- customers
properties:
key:
type: string
description: Your stores public API key.
private_key:
type: string
description: Your stores private API key.
customers:
type: array
description: List of [customers](/reference/customer-resource) to add or update.
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{"status":"ok"}'
schema:
type: object
properties:
status:
type: string
example: ok
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Catalog
patch:
summary: /customers
description: Patch existing customers in Clerk.io with new attributes or values.
operationId: customers-patch
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- customers
properties:
key:
type: string
description: You stores public API key.
private_key:
type: string
description: Your stores private API key.
customers:
type: array
description: List of partial [customer](/reference/customer-resource) objects.
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{"status":"ok"}'
schema:
type: object
properties:
status:
type: string
example: ok
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Catalog
delete:
summary: /customers
description: Delete customers from Clerk.io
operationId: customers-delete
parameters:
- name: key
in: query
description: Your stores public API key.
required: true
schema:
type: string
- name: private_key
in: query
description: Your stores private API key.
required: true
schema:
type: string
- name: customers
in: query
description: List of customer ID's to delete from Clerk.io
required: true
schema:
type: array
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{"status":"ok"}'
schema:
type: object
properties:
status:
type: string
example: ok
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Catalog
/customized_search:
get:
summary: /customized_search
description: ''
operationId: customized-searches-get
parameters:
- name: key
in: query
description: Your stores public API key.
required: true
schema:
type: string
- name: private_key
in: query
description: Your stores private API key.
schema:
type: string
- name: rules
in: query
description: the list of rule queries which you want to retrieve customized search rules for
required: true
schema:
type: array
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "[\n {\n 'query': 'abc',\n \t'products': {'pin': [1,2], 'hide': []},\n \t'categories': {'pin':\
\ [45], 'hide': []},\n \t'pages': {'pin': [], 'hide': []},\n \t'suggestions': {'pin': ['bcd'], 'hide':\
\ []}\n\t}\n]"
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
tags:
- Merchandising
post:
summary: /customized_search
description: ''
operationId: customized-searches-post
requestBody:
content:
application/json:
schema:
type: object
required:
- key
properties:
key:
type: string
description: Your stores public API key.
private_key:
type: string
description: Your stores private API key.
rules:
type: array
description: list of customized_search objects
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{"status":"ok"}'
schema:
type: object
properties:
# --- truncated at 32 KB (269 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clerk-io/refs/heads/main/openapi/clerk-io-openapi.yml