# Harvested 2026-08-13 by the API Evangelist enrichment pipeline.
# method: searched
# source: https://docs.clerk.io/reference/* (ReadMe API Designer OpenAPI 3.1.0 fragments
# embedded in each reference page's ssr-props payload, merged path-by-path).
# Ownership: servers[] is https://api.clerk.io/v2 and every path matches Clerk.io's own
# documented product surface; harvested from Clerk.io's own docs host docs.clerk.io.
# Provider content is preserved verbatim; only document assembly (path merge) is ours.
openapi: 3.1.0
info:
title: api-settings
version: '2'
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
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
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
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
/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
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
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
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
/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
/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
/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
/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
/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
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
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
/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
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
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
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
/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
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:
status:
type: string
example: ok
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
patch:
summary: /customized_search
description: ''
operationId: customized-searches-patch
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:
status:
type: string
example: ok
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
delete:
summary: /customized_search
description: ''
operationId: customized-searches-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.
schema:
type: string
- name: rules
in: query
description: the list of queries you want to delete customized search rules for
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
/log/cart/add:
get:
summary: log/cart/add
description: Add products to a customers cart. A product is defined as a basket_product object (see below)
operationId: logcartadd
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: products
in: query
description: A list of products in the form of **basket_products**
required: true
schema:
type: array
- name: visitor
in: query
description: Visitor id belonging to the basket
schema:
type: string
- name: email
in: query
description: Email belonging to the basket
schema:
type: string
- name: basket_id
in: query
description: Will be self assigned if one is not provided
schema:
type: string
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
x-readme:
code-samples:
- language: curl
code: curl https://api.clerk.io/v2/log/cart/add?key=store_api_key&products=[{"id":"abc","qty":3}]&visitor=bob
samples-languages:
- curl
/log/cart/remove:
get:
summary: log/cart/remove
description: remove products from a customers cart. A product is defined as a basket_product object (see below)
operationId: logcartremove
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: products
in: query
description: A list of products in the form of **basket_products**
required: true
schema:
type: array
- name: visitor
in: query
description: Visitor id belonging to the basket
schema:
type: string
- name: email
in: query
description: Email belonging tot he basket
schema:
type: string
- name: basket_id
in: query
description: Will be self assigned if one is not provided
schema:
type: string
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
x-readme:
code-samples:
- language: curl
code: curl https://api.clerk.io/v2/log/cart/remove?key=store_api_key&products=[{"id":"abc","qty":3}]&visitor=bob
samples-languages:
- curl
/log/cart/update:
get:
summary: log/cart/update
description: Sets the customers basket to the given products. A product is defined as a basket_product object (see below)
operationId: logcartupdate
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: products
in: query
description: A list of products in the form of **basket_products**
required: true
schema:
type: array
- name: visitor
in: query
description: Visitor id belonging to the basket
schema:
type: string
- name: email
in: query
description: Email belonging tot he basket
schema:
type: string
- name: basket_id
in: query
description: Will be self assigned if one is not provided
schema:
type: string
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
x-readme:
code-samples:
- language: curl
code: curl https://api.clerk.io/v2/log/cart/update?key=store_api_key&products=[{"id":"abc","qty":3}]&visitor=bob
samples-languages:
- curl
/log/category:
get:
summary: log/category
description: Log a category view from a customer
operationId: logcategory
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: category
in: query
description: ID of the product that the visitor viewed.
required: true
schema:
type: string
- name: visitor
in: query
description: Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API documentation on Visitor Tracking for details.
required: true
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\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 https://api.clerk.io/v2/log/category?key=store_api_key&category=123&visitor=unique_visitor_id
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"product\": 123,\n \"visitor\": \"unique_visitor_id\"}' \\\n https://api.clerk.io/v2/log/category"
name: POST
samples-languages:
- curl
/log/click:
get:
summary: log/click
description: Log a click on a product from Clerk.io.
operationId: log-click
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: product
in: query
description: ID pf the clicked product.
required: true
schema:
type: string
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
required: true
schema:
type: string
- name: api
in: query
description: The API endpoint used to generate the result for this click.
schema:
type: string
- name: n
in: query
description: The clicked products position in the result (0-indexed).
schema:
type: integer
format: int32
- name: external
in: query
description: Is this a external click from outside the website such as a email or an ad.
schema:
type: boolean
default: false
- name: labels
in: query
description: The label(s) of the API endpoint used to generate this click
schema:
type: array
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\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 https://api.clerk.io/v2/log/click?key=store_api_key&product=123&visitor=unique_visitor_id
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"product\": 123,\n \"visitor\": \"unique_visitor_id\"}' \\\n https://api.clerk.io/v2/log/click"
name: POST
samples-languages:
- curl
/log/email:
get:
summary: log/email
description: Associate an email with a visitor.
operationId: log-email
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: email
in: query
description: The visitors email.
required: true
schema:
type: string
- name: visitor
in: query
description: Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API documentation on Visitor Tracking for details.
required: true
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\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 https://api.clerk.io/v2/log/email?key=store_api_key&email=john@doe.com&visitor=unique_visitor_id
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"product\": 123,\n \"visitor\": \"unique_visitor_id\"}' \\\n https://api.clerk.io/v2/log/click"
name: POST
samples-languages:
- curl
/log/product:
get:
summary: log/product
description: Log a product view from a customer
operationId: logproduct
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: product
in: query
description: ID of the product that the visitor viewed.
required: true
schema:
type: string
- name: visitor
in: query
description: Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API documentation on Visitor Tracking for details.
required: true
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\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 https://api.clerk.io/v2/log/product?key=store_api_key&product=123&visitor=unique_visitor_id
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"product\": 123,\n \"visitor\": \"unique_visitor_id\"}' \\\n https://api.clerk.io/v2/log/product"
name: POST
samples-languages:
- curl
/log/returned:
get:
summary: log/returned
description: Log a product that was returned, on an order.
operationId: logreturned
parameters:
- name: key
in: query
description: Your store API key.
required: true
schema:
type: string
- name: private_key
in: query
description: Your store private API key.
required: true
schema:
type: string
- name: product
in: query
description: ID of the product.
required: true
schema:
type: string
- name: order
in: query
description: ID of the order / sale.
required: true
schema:
type: string
- name: quantity
in: query
description: The amount of returned products
required: true
schema:
type: integer
format: int32
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\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 https://api.clerk.io/v2/log/returned?key=store_api_key&private_key=store_private_api_key&product=123&order=456&quantity=2'
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"private_key\": \"store_private_api_key\",\n \"product\": 123,\n \"order\": 456,\n\
\ \"quantity\":1}' \\\n https://api.clerk.io/v2/log/returned"
name: POST
samples-languages:
- curl
/log/sale:
get:
summary: log/sale
description: Log a sale / order made by a user.
operationId: log-sale
parameters:
- name: key
in: query
description: You store API key
required: true
schema:
type: string
- name: sale
in: query
description: ID of the order / sale.
required: true
schema:
type: string
- name: products
in: query
description: List of products in the order. Can be a simple list of product IDs or a list of objects with ID, price
and quantity.
required: true
schema:
items:
properties:
id:
type: integer
description: The ID of the product that was bought.
format: int32
quantity:
type: integer
description: The number of identical products that were bought. Minimum 1.
format: int32
price:
type: number
description: The unit price of the product that was bought. This will be multiplied by the quantity in Clerk.
format: float
type: object
type: array
style: deepObject
explode: true
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: customer
in: query
description: ID of the customer who made the order / sale.
schema:
type: string
- name: email
in: query
description: The email of the customer who mae the order / sale.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\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 -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"sale\": 567,\n \"products\": [\n {\n \"id\": 1,\n \"price\"\
: 99.95,\n \"quantity\": 2\n }, \n {\n \"id\": 33,\n \
\ \"price\": 14.00,\n \"quantity\": 2\n }\n ],\n \"customer\": 1234,\n\
\ \"email\": \"theone@matrix.com\",\n \"visitor\": \"a1d0c6e83f027327d8461063f4ac58a6\"}' \\\
\n https://api.clerk.io/v2/log/sale"
name: POST
- language: text
code: curl https://api.clerk.io/v2/log/sale?key=store_api_key&sale=123456&email=john@doe.com&products=[123,456]
name: GET
samples-languages:
- curl
- text
post:
summary: log/sale
description: Log a sale / order made by a user.
operationId: logsale-copy
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- sale
- products
properties:
key:
type: string
description: You store API key
customer:
type: string
description: ID of the customer who made the order / sale.
email:
type: string
description: The email of the customer who mae the order / sale.
sale:
type: string
description: ID of the order / sale.
products:
type: array
description: List of products in the order. Can be a simple list of product IDs or a list of objects with
ID, price and quantity.
items:
properties:
id:
type: integer
description: The ID of the product that was bought.
format: int32
quantity:
type: integer
description: The number of identical products that were bought. Minimum 1.
format: int32
price:
type: number
description: The unit price of the product that was bought. This will be multiplied by the quantity
in Clerk.
format: float
type: object
visitor:
type: string
description: 'Required for tracking
Visitor ID for the given
visitor.
If `auto`, an anonymous ID is generated.
See API documentation on Visitor Tracking for details.'
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\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 -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"sale\": 567,\n \"products\": [\n {\n \"id\": 1,\n \"price\"\
: 99.95,\n \"quantity\": 2\n }, \n {\n \"id\": 33,\n \
\ \"price\": 14.00,\n \"quantity\": 2\n }\n ],\n \"customer\": 1234,\n\
\ \"email\": \"theone@matrix.com\",\n \"visitor\": \"a1d0c6e83f027327d8461063f4ac58a6\"}' \\\
\n https://api.clerk.io/v2/log/sale"
name: POST
- language: text
code: curl https://api.clerk.io/v2/log/sale?key=store_api_key&sale=123456&email=john@doe.com&products=[123,456]
name: GET
samples-languages:
- curl
- text
/merchandising:
get:
summary: /merchandising
description: ''
operationId: merchandising-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: campaigns
in: query
description: The ids for the merchandising campaign
required: true
schema:
type: array
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n 'status': 'ok',\n 'campaigns': [\n {'id': 'saa',\n \t\t'name': 'saa',\n \t\t'description':\
\ '',\n \t\t'active': True,\n \t\t'start_at': None,\n \t\t'end_at': None,\n \t\t'rules': [{'action': 'pin',\
\ 'products': ['MC-PRBO1100']}],\n \t\t'triggers': [{'type': 'searches_all'}],\n \t\t'triggers_match':\
\ 'any'}\n ]\n}"
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{request: bad}'
deprecated: false
post:
summary: /merchandising
description: ''
operationId: merchandising-post
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- campaigns
properties:
key:
type: string
description: The public key of the store
private_key:
type: string
description: The private key of the store
campaigns:
type: array
description: The campaigns which should be created. Consists of merchandising objects without ids.
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{ 'status': 'ok',\n\t'campaign_ids':['c1','c2']}"
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{request: bad}'
deprecated: false
patch:
summary: /merchandising
description: ''
operationId: merchandising-patch
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- campaigns
properties:
key:
type: string
description: The public key of the store
private_key:
type: string
description: The private key of the store
campaigns:
type: array
description: The merchandising campaigns which should be updated. Consists of merchandising objects.
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{ ''status'': ''ok'',}'
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{request: bad}'
deprecated: false
delete:
summary: /merchandising
description: ''
operationId: merchandising-delete
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: campaigns
in: query
description: The ids for the merchandising campaigns which should be deleted
required: true
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: '{request: bad}'
deprecated: false
/orders:
get:
summary: /orders
description: Get orders from Clerk.io
operationId: orders-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: orders
in: query
description: List of order 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
post:
summary: /orders
description: Add or update orders in Clerk.io
operationId: orders-post
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- orders
properties:
key:
type: string
description: Your stores public API key.
private_key:
type: string
description: Your stores private API key.
orders:
type: array
description: List of [orders](/reference/order-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
patch:
summary: /orders
description: Patch existing orders in Clerk.io with new attributes or values.
operationId: orders-patch
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- orders
properties:
key:
type: string
description: You stores public API key.
private_key:
type: string
description: Your stores private API key.
orders:
type: array
description: List of partial order 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
delete:
summary: /orders
description: Delete orders from Clerk.io
operationId: orders-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: orders
in: query
description: List of order 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
/orders/parcels:
get:
summary: /orders/parcels
description: Allows you to fetch all parcels associated with a given Order.
operationId: parcels-get
parameters:
- name: key
in: query
description: Public key
required: true
schema:
type: string
- name: private_key
in: query
description: Private key
required: true
schema:
type: string
- name: order_id
in: query
description: ID of the order to fetch tracking information for
required: true
schema:
type: string
- name: parcel_id
in: query
description: ID of the specific parcel you want to retrieve
schema:
type: string
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
post:
summary: /orders/parcels
description: Allows you to create parcels associated with a given Order.
operationId: parcels-post
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- order_id
properties:
key:
type: string
description: Your stores public API key.
private_key:
type: string
description: Your stores private API key.
order_id:
type: string
description: The ID of the order tied to the parcel.
tracking_code:
type: string
description: Tracking code associated with the parcel.
tracking_link:
type: string
description: Link from the carrier, including the tracking code in the query parameters.
status:
type: string
description: Semantic description of the parcel status.
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
patch:
summary: /orders/parcels
description: Allows you to edit parcels associated with a given Order.
operationId: parcels-patch
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- parcel_id
- order_id
properties:
key:
type: string
description: Your stores public API key.
private_key:
type: string
description: Your stores private API key.
parcel_id:
type: string
description: The ID of the parcel you are patching
order_id:
type: string
description: The ID of the order tied to the parcel
tracking_code:
type: string
description: Tracking code associated with the parcel
tracking_link:
type: string
description: Link from the carrier, including the tracking code in the query parameters.
status:
type: string
description: Semantic description of the parcel status.
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
delete:
summary: /orders/parcels
description: Allows you to delete parcels associated with a given Order.
operationId: parcels-delete
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- parcel_id
properties:
key:
type: string
description: Your stores public API key.
private_key:
type: string
description: Your stores private API key.
parcel_id:
type: string
description: The ID of the parcel you want to delete.
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
/pages:
get:
summary: /pages
description: Get pages from Clerk.io
operationId: pages-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: pages
in: query
description: List of page 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
post:
summary: /pages
description: Add or update pages in Clerk.io
operationId: pages-post
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- pages
properties:
key:
type: string
description: Your stores public API key.
private_key:
type: string
description: Your stores private API key.
pages:
type: array
description: List of [pages](/reference/page-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
patch:
summary: /pages
description: Patch existing pages in Clerk.io with new attributes or values.
operationId: pages-patch
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- pages
properties:
key:
type: string
description: You stores public API key.
private_key:
type: string
description: Your stores private API key.
pages:
type: array
description: List of partial page 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
delete:
summary: /pages
description: Delete pages from Clerk.io
operationId: pages-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: pages
in: query
description: List of page 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
/privacy/forget:
get:
summary: privacy/forget
description: Forget all available info Clerk.io has on a visitor or customer.
operationId: privacy-forget
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: private_key
in: query
description: Your store private API key.
required: true
schema:
type: string
- name: email
in: query
description: Email to forget info for.
schema:
type: string
- name: customer
in: query
description: Customer ID to forget info for.
schema:
type: string
- name: visitor
in: query
description: Visitor ID to forget info for.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\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 https://api.clerk.io/v2/privacy/forget?key=store_api_key&private_key=store_private_key&email=john.doe@example.com
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"private_key\": \"store_private_api_key\"\n \"email\": \"john.doe@example.com\"}' \\\n https://api.clerk.io/v2/privacy/forget"
name: POST
samples-languages:
- curl
/privacy/info:
get:
summary: privacy/info
description: Get all available info Clerk.io has on a visitor or customer.
operationId: privacy-info
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: private_key
in: query
description: Your store private API key.
required: true
schema:
type: string
- name: email
in: query
description: Email to retrieve info for.
schema:
type: string
- name: customer
in: query
description: Customer ID to retrieve info for.
schema:
type: string
- name: visitor
in: query
description: Visitor ID to retrieve info for.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"orders\": [123, 456, 789],\n \"activity\": [\n {\n \"visitor\"\
: \"123ABc\",\n \"type\": \"other\",\n \"description\": \"Some tracked activity\"\n \"\
time\": 1527206400\n }\n ]\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:
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 https://api.clerk.io/v2/privacy/info?key=store_api_key&private_key=store_private_key&email=john.doe@example.com
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"private_key\": \"store_private_api_key\"\n \"email\": \"john.doe@example.com\"}' \\\n https://api.clerk.io/v2/privacy/info"
name: POST
samples-languages:
- curl
/product/add:
get:
summary: product/add
description: Bulk add new / changed products to a store.
operationId: product-add
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: private_key
in: query
description: Your store private API key.
required: true
schema:
type: string
- name: products
in: query
description: List of the product objects to add. If the product already exists it will be overridden with the new
data.
required: true
schema:
type: array
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\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 -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"private_key\": \"store_private_api_key\"\n \"products\": [\n {\n \
\ \"id\": 123,\n \"name\": \"Green Lightsaber\",\n \"description\": \"\
Antiuque rebel lightsaber.\",\n \"price\": 99995.95,\n \"brand\": \"Je’daii\"\
,\n \"categories\": [987, 654],\n \"created_at\": 1199145600\n \
\ },\n {\n \"id\": 789,\n \"name\": \"Death Star Deluxe\"\
,\n \"description\": \"Death Star. Guaranteed idiot proof. \"\n \"price\": 99999999999999.95,\n\
\ \"brand\": \"Imperial Inc.\",\n \"categories\": [345678],\n \
\ \"created_at\": 11991864600\n }\n ]}' \\\n https://api.clerk.io/v2/product/add"
name: POST
samples-languages:
- curl
/product/attributes:
get:
summary: product/attributes
description: Loads the given attributes for the given products. See the API documentation for Product Metadata to embed
this with every avary call.
operationId: product-attributes
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: products
in: query
description: List of Product ID's to return attributes for.
required: true
schema:
type: array
items:
type: integer
format: int32
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
If none is provided all available attributes will be returned.
schema:
type: array
items:
type: string
- name: language
in: query
description: The language if the store is using multiple languages. If not provided the most used language in the
store will be used.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "[\n {\n \"id\": 123,\n \"name\": \"Wombat Wand\",\n \"price\": 14.95\n },\n {\n \
\ \"id\": 123,\n \"name\": \"Green Light Saber\",\n \"price\": 99995.95\n },\n {\n \"id\"\
: 789,\n \"name\": \"Death Star Deluxe\",\n \"price\": 99999999999999.95\n }\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: array
items:
type: object
properties:
id:
type: integer
example: 123
default: 0
name:
type: string
example: Wombat Wand
price:
type: number
example: 14.95
default: 0
- 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/product/attributes?key=store_api_key&products=[123,456,789]&attributes=id,name,price
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"products\": [123, 456, 789],\n \"attributes\": [\"id\", \"name\", \"price\"]}' \\\n http://api.clerk.io/v2/product/attributes"
name: POST
samples-languages:
- curl
/product/facets:
get:
summary: product/facets
description: Loads the facet groups available for the given products and attributes.
operationId: product-facets
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: products
in: query
description: List of product IDs. If not provided facets will be computed for all products.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
If none is provided all available attributes will be returned.
schema:
type: array
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"facets\": {\n \"categories\": [\n {\n \"count\": 2,\n\
\ \"type\": \"unit\",\n \"name\": \"Imperial Inc.\",\n \"value\": \"Imperial Inc.\"\
\n },\n {\n \"count\": 1,\n \"type\": \"unit\",\n \"name\": \"Je’daii\"\
,\n \"value\": \"Je’daii\"\n }\n ],\n \"price\": [\n {\n \"max\": 49.0,\n\
\ \"type\": \"range\",\n \"name\": \"0 - 49\",\n \"min\": 0.0\n },\n {\n\
\ \"max\": 99.0,\n \"type\": \"range\",\n \"name\": \"50 - 99\",\n \"min\"\
: 50.0\n },\n {\n \"max\": 750,\n \"type\": \"range\",\n \"name\": \">\
\ 100\",\n \"min\": 100\n }\n ]\n }\n}\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
facets:
type: object
properties:
categories:
type: array
items:
type: object
properties:
count:
type: integer
example: 2
default: 0
type:
type: string
example: unit
name:
type: string
example: Imperial Inc.
value:
type: string
example: Imperial Inc.
price:
type: array
items:
type: object
properties:
max:
type: integer
example: 49
default: 0
type:
type: string
example: range
name:
type: string
example: 0 - 49
min:
type: integer
example: 0
default: 0
- 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/product/facets?key=store_api_key&products=[123,456,789]&attributes=brand,price
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"products\": [123, 456, 789],\n \"attributes\": [\"id\", \"name\", \"price\"]}' \\\n http://api.clerk.io/v2/product/attributes"
name: POST
samples-languages:
- curl
/product/remove:
get:
summary: product/remove
description: Bulk remove products from a store.
operationId: product-remove
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: private_key
in: query
description: Your store private API key.
required: true
schema:
type: string
- name: products
in: query
description: List of product IDs to be removed.
required: true
schema:
type: array
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\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 https://api.clerk.io/v2/product/remove?key=store_api_key&private_key=store_private_key&products=[123,456,789]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"private_key\": \"store_private_api_key\"\n \"products\": [123, 456, 789]}' \\\n https://api.clerk.io/v2/product/remove"
name: POST
samples-languages:
- curl
/products:
post:
summary: /products
description: Add or update products in Clerk.io
operationId: products-post
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- products
properties:
key:
type: string
description: Your stores public API key.
private_key:
type: string
description: Your stores private API key.
products:
type: array
description: List of [products](/reference/product-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
patch:
summary: /products
description: Patch existing products in Clerk.io with new attributes or values.
operationId: products-patch
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- products
properties:
key:
type: string
description: You stores public API key.
private_key:
type: string
description: Your stores private API key.
products:
type: array
description: List of partial product 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
delete:
summary: Copy of Copy of /categories
description: Get categories from Clerk.io
operationId: categories-get-1-1
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: products
in: query
description: List of product ID's to delete.
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
get:
summary: /products
description: Get products from Clerk.io
operationId: categories-get-1
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 delete.
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: {}
/recommendations/bundle:
get:
summary: recommendations/bundle
description: This endpoint is deprecated and has been replaced by recommendations/complementary
operationId: recommendations-bundle
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: product
in: query
description: Product ID for the product you want bundled products for.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/bundle?key=store_api_key&product=123&limit=30&labels=["Bundled
products"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"product\": 123, \n \"limit\": 30,\n \"visitor\": \"unique_visitor_id\",\n \
\ \"exclude\": [42],\n \"filter\": \"price > 100\",\n \"labels\": [\"Bundle options\"],\n \
\ \"facets\": [\"categories\", \"brands\"]}' \\\n http://api.clerk.io/v2/recommendations/bundle"
name: POST
samples-languages:
- curl
/recommendations/category/new:
get:
summary: recommendations/category/new
description: The products in a given category (and subcategories) that were most recently added to the store.
operationId: recommendationscategorynew
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: category
in: query
description: Category ID for the category you want popular products for.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/category/new?key=store_api_key&category=123&limit=30&labels=["New
products in this category"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"category\": 123, \n \"limit\": 30,\n \"visitor\": \"unique_visitor_id\",\n \
\ \"exclude\": [42],\n \"filter\": \"price > 100\",\n \"labels\": [\"Category Popular\"]'\
\ \\\n http://api.clerk.io/v2/recommendations/category/new"
name: POST
samples-languages:
- curl
/recommendations/category/popular:
get:
summary: recommendations/category/popular
description: The products in a given category (and subcategories) that are most popular among customers right now.
operationId: recommendations-category-popular
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: category
in: query
description: Category ID for the category you want popular products for.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: offset
in: query
description: Offset into the result. See pagenation docs for a deeper specification on how to use pagenation.
schema:
type: integer
format: int32
default: 0
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: facets
in: query
description: List of facets to be returned for the products in the result. See API documentation on Facets for details.
schema:
type: array
items:
type: string
- name: orderby
in: query
description: Attribute to order the results by.
schema:
type: string
- name: order
in: query
description: Should the ordering from `orderby` be ascending (asc) or descending (desc).
schema:
type: string
default: asc
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/category/popular?key=store_api_key&category=123&limit=30&labels=["Category
Popular"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"category\": 123, \n \"limit\": 30,\n \"offset\": 60,\n \"visitor\": \"unique_visitor_id\"\
,\n \"exclude\": [42],\n \"filter\": \"price > 100\",\n \"labels\": [\"Category Popular\"\
],\n \"facets\": [\"categories\", \"brands\"]}' \\\n http://api.clerk.io/v2/recommendations/category/popular"
name: POST
samples-languages:
- curl
/recommendations/category/popular_subcategories:
get:
summary: recommendations/category/popular_subcategories
description: The subcategories in a given category that are most popular among customers right now.
operationId: recommendationscategorypopular_subcategories
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: category
in: query
description: Category ID for the category you want popular products for.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: offset
in: query
description: Offset into the result. See pagenation docs for a deeper specification on how to use pagenation.
schema:
type: integer
format: int32
default: 0
- name: order
in: query
description: Should the subcategories be in descending or ascending order. Default is descending so the most popular
is the first result.
schema:
type: string
default: desc
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [{'url':'https://www.yoursite.com/category1','name':'category1','id':123},{'url':'https://www.yoursite.com/category2','name':'category2','id':124},{'url':'https://www.yoursite.com/category3','name':'category3','id':325}\
\ ...]\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:
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/recommendations/category/popular_subcategories?key=store_api_key&category=123&limit=30
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"category\": 123, \n \"limit\": 30,\n \"offset\": 60,\n \"visitor\": \"unique_visitor_id\"\
,\n \"exclude\": [42],\n \"filter\": \"price > 100\",\n \"labels\": [\"Category Popular\"\
],\n \"facets\": [\"categories\", \"brands\"]}' \\\n http://api.clerk.io/v2/recommendations/category/popular"
name: POST
samples-languages:
- curl
/recommendations/category/trending:
get:
summary: recommendations/category/trending
description: The products in a given category (and subcategories) that are growing the most in popularity amongst customers
right now.
operationId: recommendationscategorytrending
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: category
in: query
description: Category ID for the category you want popular products for.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: offset
in: query
description: Offset into the result. See pagenation docs for a deeper specification on how to use pagenation.
schema:
type: integer
format: int32
default: 0
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: facets
in: query
description: List of facets to be returned for the products in the result. See API documentation on Facets for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/category/trending?key=store_api_key&category=123&limit=30&labels=["Trending
In This Category"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"category\": 123, \n \"limit\": 30,\n \"offset\": 60,\n \"visitor\": \"unique_visitor_id\"\
,\n \"exclude\": [42],\n \"filter\": \"price > 100\",\n \"labels\": [\"Trending In\
\ This Category\"],\n \"facets\": [\"categories\", \"brands\"]}' \\\n http://api.clerk.io/v2/recommendations/category/trending"
name: POST
samples-languages:
- curl
/recommendations/complementary:
get:
summary: recommendations/complementary
description: The products that customers are most likely to buy with a given product or multiple products.
operationId: recommendations-complementary
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: products
in: query
description: Product ID(s) for the products you want complementary products for.
required: true
schema:
type: array
items:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/complementary?key=store_api_key&products=[123,456,789]&limit=30&labels=["Best
Cross-Sell Products"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"products\": [123], \n \"limit\": 30,\n \"visitor\": \"unique_visitor_id\",\n \
\ \"exclude\": [42],\n \"filter\": \"price > 100\",\n \"labels\": [\"Best Cross-Sell Products\"\
],\n \"facets\": [\"categories\", \"brands\"]}' \\\n https://api.clerk.io/v2/recommendations/complementary"
name: POST
samples-languages:
- curl
/recommendations/currently_watched:
get:
summary: recommendations/currently_watched
description: The products other store visitors are currently looking at.
operationId: recommendationscurrently_watched
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
default: insert_api_key
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/currently_watched?key=store_api_key&limit=30&labels=["Customers
Are Looking At"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"limit\": 30,\n \"visitor\": \"unique_visitor_id\",\n \"exclude\": [42],\n \
\ \"labels\": [\"Customers Are Looking At\"],\n \"facets\": [\"categories\", \"brands\"]}' \\\n \
\ https://api.clerk.io/v2/recommendations/currently_watched"
name: POST
samples-languages:
- curl
/recommendations/customer/complementary:
get:
summary: recommendations/customer/complementary
description: The products that a specific customer is most likely to buy right now based on their order history.
operationId: recommendations-customer-complementary
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: email
in: query
description: The customers email address
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: customer
in: query
description: The customers ID.
schema:
type: string
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/customer/complementary?key=store_api_key&email=luke@skywalker.net&limit=30&labels=["Customer
Recommendations"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \t\t\t\"visitor\": \"visitor_id\",\n \"email\": \"luke@skywalker.com\",\n \"limit\": 30,\n\
\ \"exclude\": [42],\n \"filter\": \"price > 100\",\n \"labels\": [\"Customer Recommendations\"\
],\n \"facets\": [\"categories\", \"brands\"]}' \\\n http://api.clerk.io/v2/recommendations/customer/complementary"
name: POST
samples-languages:
- curl
/recommendations/customer/history:
get:
summary: recommendations/customer/history
description: The history of a customer's on-site activity.
operationId: recommendations-customer-history
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: email
in: query
description: The customers email address
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: customer
in: query
description: The customers ID.
schema:
type: string
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/customer/history?key=store_api_key&email=luke@skywalker.net&limit=30&labels=["Customer
History"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \t\t\t\"visitor\": \"visitor_id\",\n \"email\": \"luke@skywalker.com\",\n \"limit\": 30,\n\
\ \"exclude\": [42],\n \"filter\": \"price > 100\",\n \"labels\": [\"Customer History\"\
],\n \"facets\": [\"categories\", \"brands\"]}' \\\n http://api.clerk.io/v2/recommendations/customer/history"
name: POST
samples-languages:
- curl
/recommendations/customer/substituting:
get:
summary: recommendations/customer/substituting
description: The products that a specific customer is most likely to buy right now as replacements for their order history.
operationId: recommendations-customer-substituting
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: email
in: query
description: The customers email address
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: customer
in: query
description: The customers ID.
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
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/customer/substituting?key=store_api_key&email=luke@skywalker.net&limit=30&labels=["Customer
Alternatives"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"visitor\": \"visitor_id\",\n \"email\": \"luke@skywalker.com\",\n \"limit\": 30,\n\
\ \"exclude\": [42],\n \"filter\": \"price > 100\",\n \"labels\": [\"Customer Alternatives\"\
],\n \"facets\": [\"categories\", \"brands\"]}' \\\n http://api.clerk.io/v2/recommendations/customer/substituting"
name: POST
samples-languages:
- curl
/recommendations/keywords:
get:
summary: recommendations/keywords
description: Products based on content such as blogs, news or content pages.
operationId: recommendations-keywords
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: keywords
in: query
description: The keywords (ie. content title) to base the recommendations upon.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/keywords?key=store_api_key&limit=30&keywords=lightsaber&labels=["Keyword
Recommendations"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"limit\": 30,\n \"visitor\": \"unique_visitor_id\",\n \"exclude\": [42],\n \
\ \"filter\": \"price > 100\",\n \"labels\": [\"Keyword Recommendations\"],\n \"facets\": [\"\
categories\", \"brands\"]}' \\\n http://api.clerk.io/v2/recommendations/currently_watched"
name: POST
samples-languages:
- curl
/recommendations/most_sold_with:
get:
summary: recommendations/most_sold_with
description: The products that have been sold the most times with a given product or multiple products
operationId: recommendationsmost_sold_with
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: products
in: query
description: Product ID(s) for the products you the most sold with products for.
required: true
schema:
type: array
items:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/most_sold_with?key=store_api_key&products=[123,456,789]&limit=30&labels=["Best
Cross-Sell Products"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"products\": [123], \n \"limit\": 30,\n \"visitor\": \"unique_visitor_id\",\n \
\ \"exclude\": [42],\n \"filter\": \"price > 100\",\n \"labels\": [\"Best Cross-Sell Products\"\
],\n \"facets\": [\"categories\", \"brands\"]}' \\\n http://api.clerk.io/v2/recommendations/most_sold_with"
name: POST
samples-languages:
- curl
/recommendations/new:
get:
summary: recommendations/new
description: The products that were most recently added to the store.
operationId: recommendationsnew
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
default: insert_api_key
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/new?key=store_api_key&limit=30&labels=["Newly added products"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"limit\": 30,\n \"visitor\": \"unique_visitor_id\",\n \"exclude\": [42],\n \
\ \"labels\": [\"Newly added products\"],\n \"facets\": [\"categories\", \"brands\"]}' \\\n https://api.clerk.io/v2/recommendations/new"
name: POST
samples-languages:
- curl
/recommendations/page/category:
get:
summary: recommendations/page/category
description: Pages that are related to any given category
operationId: recommendationspagecategory
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: category
in: query
description: ID of the category you want related pages for.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Page attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: type
in: query
description: The type of pages to return
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, 112, 113],\n \"pages\": [{\"title\": \"\
How to build a Death Star\",\"url:\":\"https://galactic-empire.com/blogs/death-star\",\"text\":\"In order\
\ to build a Death Star, you must consider ventilation and...\",\"image\":\"https://galactic-empire.com/images/death-star.jpg\"\
,\"type\":\"blog\",\"id\": 123},{...}]\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:
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/recommendations/page/category?key=store_api_key&category=123&limit=5&type="CMS
Page"&labels=["Categories - Related Articles"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"category\": 123, \n \"type\": \"CMS Page\",\n \"limit\": 5,\n \"visitor\"\
: \"unique_visitor_id\",\n \"labels\": [\"Categories - Related Articles\"]}' \\\n http://api.clerk.io/v2/recommendations/page/category"
name: POST
samples-languages:
- curl
/recommendations/page/product:
get:
summary: recommendations/page/product
description: Pages that are related to any given product
operationId: recommendationspageproduct
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: product
in: query
description: ID of the product you want related pages for.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Page attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: type
in: query
description: The type of pages to return
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, 112, 113],\n \"pages\": [{\"title\": \"\
How to build a Death Star\",\"url:\":\"https://galactic-empire.com/blogs/death-star\",\"text\":\"In order\
\ to build a Death Star, you must consider ventilation and...\",\"image\":\"https://galactic-empire.com/images/death-star.jpg\"\
,\"type\":\"blog\",\"id\": 123},{...}]\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:
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/recommendations/page/product?key=store_api_key&product=123&limit=5&type="CMS Page"&labels=["Product
Page - Related Articles"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"product\": 123,\n \"type\": \"CMS Page\",\n \"limit\": 5,\n \"visitor\":\
\ \"unique_visitor_id\",\n \"labels\": [\"Product Page - Related Articles\"]}' \\\n http://api.clerk.io/v2/recommendations/page/product"
name: POST
samples-languages:
- curl
/recommendations/page/related_categories:
get:
summary: recommendations/page/related_categories
description: Products that are related to any given page
operationId: recommendationspagerelated_categories
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: page
in: query
description: ID of the page you want similar pages for.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Page attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n\t\"status\": \"ok\",\n\t\"count\": 1,\n\t\"result\": [456,111,455,786,433],\n\t\"categories\"\
: [{\"id\":456,\"name\": \"Lightsabers\",\"subcategories\":[789],\"parent\": 123,\"url\":\"https://www.rebels-of-a-just-cause.org/lightsabers\"\
},{...}]\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:
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/recommendations/page/related_categories?key=store_api_key&page=123&limit=5&labels=["Blog
Pages - Related Categories"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"page\": 123, \n \"limit\": 5,\n \"visitor\": \"unique_visitor_id\",\n \"\
labels\": [\"Blog Pages - Related Categories\"],}' \\\n http://api.clerk.io/v2/recommendations/page/related_categories"
name: POST
samples-languages:
- curl
/recommendations/page/related_products:
get:
summary: recommendations/page/related_products
description: Products that are related to any given page
operationId: recommendationspagerelated_products
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: page
in: query
description: ID of the page you want similar pages for.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Page attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/page/related_products?key=store_api_key&page=123&limit=5&labels=["Blog
Pages - Related Products"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"page\": 123, \n \"limit\": 5,\n \"visitor\": \"unique_visitor_id\",\n \"\
labels\": [\"Blog Pages - Related Products\"],}' \\\n http://api.clerk.io/v2/recommendations/page/related_products"
name: POST
samples-languages:
- curl
/recommendations/page/substituting:
get:
summary: recommendations/page/substituting
description: Pages that are similar to any given page
operationId: recommendationspagesubstituting
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: page
in: query
description: ID of the page you want similar pages for.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: type
in: query
description: The type of pages to return
schema:
type: string
- name: attributes
in: query
description: Page attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, 112, 113],\n \"pages\": [{\"title\": \"\
How to build a Death Star\",\"url:\":\"https://galactic-empire.com/blogs/death-star\",\"text\":\"In order\
\ to build a Death Star, you must consider ventilation and...\",\"image\":\"https://galactic-empire.com/images/death-star.jpg\"\
,\"type\":\"blog\",\"id\": 123},{...}]\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:
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/recommendations/page/substituting?key=store_api_key&page=123&limit=5&type="CMS
Page"&labels=["Blog Pages - Similar Articles"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"page\": 123, \n \"type\": \"CMS Page\",\n \"limit\": 5,\n \"visitor\": \"\
unique_visitor_id\",\n \"labels\": [\"Blog Pages - Similar Articles\"]}' \\\n http://api.clerk.io/v2/recommendations/page/substituting"
name: POST
samples-languages:
- curl
/recommendations/popular:
get:
summary: recommendations/popular
description: The most popular products among the store's customers right now.
operationId: recommendations-popular
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: offset
in: query
description: Offset into the result. See pagenation docs for a deeper specification on how to use pagenation.
schema:
type: integer
format: int32
default: 0
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: facets
in: query
description: List of facets to be returned for the products in the result. See API documentation on Facets for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/popular?key=store_api_key&limit=30&labels=["Bestsellers"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"limit\": 30,\n \"offset\": 60,\n \"visitor\": \"unique_visitor_id\",\n \"\
exclude\": [42],\n \"filter\": \"price > 100\",\n \"labels\": [\"Bestsellers\"],\n \
\ \"facets\": [\"categories\", \"brands\"]}' \\\n https://api.clerk.io/v2/recommendations/popular"
name: POST
samples-languages:
- curl
/recommendations/recently_bought:
get:
summary: recommendations/recently_bought
description: The products that were most recently purchased by customers.
operationId: recommendationsrecently_bought
parameters:
- name: key
in: query
description: Your store API key
required: true
schema:
type: string
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: limit
in: query
description: Number of results to be returned.
schema:
type: integer
format: int32
- name: filter
in: query
description: An attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\n}"
'400':
description: '400'
content:
application/json:
examples:
Result:
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:
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/recommendations/recently_bought?key=store_api_key&limit=30&labels=["Customers
Are Looking At"]
samples-languages:
- curl
/recommendations/substituting:
get:
summary: recommendations/substituting
description: The products that customers are most likely to buy instead of a given product or multiple products.
operationId: recommendations-substituting
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: products
in: query
description: Product ID(s) for the products you want substituting products for.
required: true
schema:
type: array
items:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/substituting?key=store_api_key&products=[123,456,789]&limit=30&labels=["Alternatives"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"products\": [123], \n \"limit\": 30,\n \"visitor\": \"unique_visitor_id\",\n \
\ \"exclude\": [42],\n \"filter\": \"price > 100\",\n \"labels\": [\"Alternatives\"],\n\
\ \"facets\": [\"categories\", \"brands\"]}' \\\n https://api.clerk.io/v2/recommendations/substituting"
name: POST
samples-languages:
- curl
/recommendations/trending:
get:
summary: recommendations/trending
description: The products with the fastest growth in popularity amongst customers right now.
operationId: recommendations-trending
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: offset
in: query
description: Offset into the result. See pagenation docs for a deeper specification on how to use pagenation.
schema:
type: integer
format: int32
default: 0
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: facets
in: query
description: List of facets to be returned for the products in the result. See API documentation on Facets for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/trending?key=store_api_key&limit=30&labels=["Hottest Products"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"limit\": 30,\n \"offset\": 60,\n \"visitor\": \"unique_visitor_id\",\n \"\
exclude\": [42],\n \"filter\": \"price > 100\",\n \"labels\": [\"Hottest Products\"],\n \
\ \"facets\": [\"categories\", \"brands\"]}' \\\n https://api.clerk.io/v2/recommendations/trending"
name: POST
samples-languages:
- curl
/recommendations/visitor/complementary:
get:
summary: recommendations/visitor/complementary
description: The products that a specific visitor is most likely to buy right now based on their on-site activity.
operationId: recommendations-visitor-complementary
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API documentation on Visitor Tracking for details.
required: true
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: email
in: query
description: A optional email to be mapped to a visitor ID. This will override the given visitor ID if any.
schema:
type: string
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/visitor/complementary?key=store_api_key&visitor=unique_visitor_id&limit=30&labels=["Visitor
Recommendations"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"visitor\": \"unique_visitor_id\",\n \"limit\": 30,\n \"exclude\": [42],\n \
\ \"filter\": \"price > 100\",\n \"labels\": [\"Visitor Recommendations\"],\n \"facets\": [\"\
categories\", \"brands\"]}' \\\n http://api.clerk.io/v2/recommendations/visitor/complementary"
name: POST
samples-languages:
- curl
/recommendations/visitor/history:
get:
summary: recommendations/visitor/history
description: The history of a visitor's on-site activity.
operationId: recommendations-visitor-history
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API documentation on Visitor Tracking for details.
required: true
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: email
in: query
description: A optional email to be mapped to a visitor ID. This will override the given visitor ID if any.
schema:
type: string
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/visitor/history?key=store_api_key&visitor=unique_visitor_id&limit=30&labels=["Visitor
History"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"visitor\": \"unique_visitor_id\",\n \"limit\": 30,\n \"exclude\": [42],\n \
\ \"filter\": \"price > 100\",\n \"labels\": [\"Visitor History\"],\n \"facets\": [\"categories\"\
, \"brands\"]}' \\\n http://api.clerk.io/v2/recommendations/visitor/history"
name: POST
samples-languages:
- curl
/recommendations/visitor/substituting:
get:
summary: recommendations/visitor/substituting
description: The products that a specific visitor is most likely to buy as alternatives to their on-site activity.
operationId: recommendations-visitor-substituting
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API documentation on Visitor Tracking for details.
required: true
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: email
in: query
description: A optional email to be mapped to a visitor ID. This will override the given visitor ID if any.
schema:
type: string
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789, ...]\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:
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/recommendations/visitor/substituting?key=store_api_key&visitor=unique_visitor_id&limit=30&labels=["Visitor
Alternatives"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"visitor\": \"unique_visitor_id\",\n \"limit\": 30,\n \"exclude\": [42],\n \
\ \"filter\": \"price > 100\",\n \"labels\": [\"Visitor Alternatives\"],\n \"facets\": [\"\
categories\", \"brands\"]}' \\\n http://api.clerk.io/v2/recommendations/visitor/substituting"
name: POST
samples-languages:
- curl
/redirects/:
get:
summary: /redirects
description: ''
operationId: redirects-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: redirects
in: query
description: The urls to fetch queries for
required: true
schema:
type: array
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{''status'': ''ok''
''redirects'':[{''url'':''clerk.io'',''queries'':[''clerk'',''redirects''],''exact_match'':True}]
}'
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
post:
summary: /redirects
description: ''
operationId: redirects-post
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- redirects
properties:
key:
type: string
description: The public key of the store
private_key:
type: string
description: The private key of the store
redirects:
type: array
description: A list of redirect 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
patch:
summary: /redirects
description: ''
operationId: redirects-patch
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- private_key
- redirects
properties:
key:
type: string
description: The public key of the store
private_key:
type: string
description: The private key of the store
redirects:
type: array
description: A list of redirect 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
delete:
summary: /redirects
description: ''
operationId: redirects-delete
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: redirects
in: query
description: The urls to delete redirects for
required: true
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
/search/categories:
get:
summary: search/categories
description: Category search API. Returns categories matching the search, sorted with the relevant and popular first.
operationId: search-categories
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: query
in: query
description: The search query. Can be empty to return all categories.
schema:
type: string
- name: limit
in: query
description: Number of results to be returned. Maximum 10.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: language
in: query
description: The language used for finding results. If not provided, the language configured on the Store in my.clerk.io
will be used.
schema:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [123, 456, 789],\n \"categories\": [\n {\n \"id\"\
: 123,\n \"name\": \"Wommens Runing Shoes\",\n \"url\": \"http://super-store.com/wommens-running-shoes/\"\
\n },\n {\n \"id\": 456,\n \"name\": \"Wommens Runing Shoes / Nike\",\n \"url\":\
\ \"http://super-store.com/wommens-running-shoes-nike/\"\n }\n ]\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
result:
type: array
items:
type: integer
example: 123
default: 0
categories:
type: array
items:
type: object
properties:
id:
type: integer
example: 123
default: 0
name:
type: string
example: Wommens Runing Shoes
url:
type: string
example: http://super-store.com/wommens-running-shoes/
- 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/search/categories?key=store_api_key&query=blue+running+sho&limit=6
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"query\": \"blue running sho\",\n \"language\": \"english\",\n \"limit\": 6,\n \
\ \"visitor\": \"unique_visitor_id\"}' \\\n http://api.clerk.io/v2/search/categories"
name: POST
samples-languages:
- curl
/search/pages:
get:
summary: search/pages
description: Pages search API.
operationId: search-pages
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: query
in: query
description: The search query.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned. Maximum 10.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: type
in: query
description: The type of the page if you only wish pages of a single type.
schema:
type: string
- name: language
in: query
description: The language used for finding results. If not provided, the language configured on the Store in my.clerk.io
will be used.
schema:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [ \n\t\t{\n \"id\": 123,\n \"type\": \"blog\"\
,\n \"name\": \"Wommens Runing Shoes\",\n \"url\": \"http://super-store.com/wommens-running-shoes/\"\
\n },\n {\n \"id\": 456,\n \"type\": \"campaign\",\n \"name\": \"Wommens Runing Shoes\
\ / Nike\",\n \"url\": \"http://super-store.com/wommens-running-shoes-nike/\"\n }\n\t],\n \"\
pages\": [\n {\n \"id\": 123,\n \"type\": \"blog\",\n \"name\": \"Wommens Runing Shoes\"\
,\n \"url\": \"http://super-store.com/wommens-running-shoes/\"\n },\n {\n \"id\": 456,\n\
\ \"type\": \"campaign\",\n \"name\": \"Wommens Runing Shoes / Nike\",\n \"url\": \"http://super-store.com/wommens-running-shoes-nike/\"\
\n }\n ]\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
result:
type: array
items:
type: integer
example: 123
default: 0
pages:
type: array
items:
type: object
properties:
id:
type: integer
example: 123
default: 0
type:
type: string
example: blog
name:
type: string
example: Wommens Runing Shoes
url:
type: string
example: http://super-store.com/wommens-running-shoes/
- 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/search/pages?key=store_api_key&query=blue+running+sho&limit=6
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"query\": \"blue running sho\",\n \"language\": \"english\",\n \"limit\": 6,\n \
\ \"visitor\": \"unique_visitor_id\"}' \\\n http://api.clerk.io/v2/search/pages"
name: POST
samples-languages:
- curl
/search/popular:
get:
summary: search/popular
description: Searches that have been made the most in the past 2 days.
operationId: search-popular
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned. Maximum 10.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: language
in: query
description: The language used for finding results. If not provided, the language configured on the Store in my.clerk.io
will be used.
schema:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [\n \"shoes\",\n \"t-shirts\",\n \"kids t-shirts\"\
\n ]\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
result:
type: array
items:
type: string
example: shoes
- 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/search/popular?key=store_api_key&limit=3
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"query\": \"blue running sho\",\n \"language\": \"english\",\n \"limit\": 6,\n \
\ \"visitor\": \"unique_visitor_id\"}' \\\n http://api.clerk.io/v2/search/suggestions"
name: POST
samples-languages:
- curl
/search/predictive:
get:
summary: search/predictive
description: '"Search As You Type" API that predicts the given unfinished query and returns products matching it.'
operationId: search-predictive
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: query
in: query
description: The search query.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned. Maximum 10.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: facets
in: query
description: List of facets to be returned for the products in the result. See API documentation on Facets for details
schema:
type: array
items:
type: string
- name: language
in: query
description: The language used for finding results. If not provided, the language configured on the Store in my.clerk.io
will be used.
schema:
type: string
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"query\":\"shoes\",\n \"hits\":3,\n \"result\": [123, 456, 789],\n\
\ \"no_exact_match\": true // returned for SKU searches or semantic fallbacks\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
query:
type: string
example: shoes
hits:
type: integer
example: 3
default: 0
result:
type: array
items:
type: integer
example: 123
default: 0
no_exact_match:
type: boolean
example: true
default: true
- 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/search/predictive?key=store_api_key&query=blue+running+sho&limit=6&labels=["Instant
Search"]&facets=["price","categories"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"query\": \"blue running sho\",\n \"language\": \"english\",\n \"limit\": 6,\n \
\ \"visitor\": \"unique_visitor_id\",\n \"exclude\": [42],\n \"filter\": \"price > 100\"\
,\n \"facets\": [\"price\",\"categories\"],\n \"labels\": [\"Instant Search\"]}' \\\n http://api.clerk.io/v2/search/predictive"
name: POST
samples-languages:
- curl
/search/search:
get:
summary: search/search
description: Search for products in the store with a ranking based on sales and behavioural data as well as keyword
matching.
operationId: search-search
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: query
in: query
description: The search query.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: labels
in: query
description: 'Required for tracking
A list of one or more text labels,
used to track the labels performance in Analytics.'
schema:
type: array
items:
type: string
- name: facets
in: query
description: List of facets to be returned for the products in the result. See API documentation on Facets for details.
schema:
type: array
items:
type: string
- name: longtail
in: query
description: Should all products matching any word in the query be in the result.
schema:
type: boolean
default: false
- name: offset
in: query
description: Offset into the result. See pagenation docs for a deeper specification on how to use pagenation.
schema:
type: integer
format: int32
default: 0
- name: filter
in: query
description: A attribute filter to filter the result. See API documentation on Filters for details.
schema:
type: string
- name: exclude
in: query
description: Array of product IDs to be excluded from the result. See API documentation on Filters for details.
schema:
type: array
items:
type: string
- name: orderby
in: query
description: Attribute to order the results by.
schema:
type: string
- name: order
in: query
description: Should the ordering from `orderby` be ascending (asc) or descending (desc).
schema:
type: string
default: asc
- name: language
in: query
description: The language used for finding results. If not provided, the language configured on the Store in my.clerk.io
will be used.
schema:
type: string
- name: attributes
in: query
description: Product attributes to be provided in the response. See API documentation on Product Metadata for details.
schema:
type: array
items:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"count\":15,\n \"hits\":15, \n \"result\": [123, 456, 789,..],\n\
\ \"facets\": {\"categories\":[..],\"brands\":[..]},\n \"no_exact_match\": true // false if a direct\
\ text match is found\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:
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/search/search?key=store_api_key&query=blue+running+shoes+for+women&limit=30&facets=["categories","brand"]&labels=["Search"]
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"query\": \"men\",\n \"language\": \"english\",\n \"limit\": 30,\n \"offset\"\
: 60,\n \"visitor\": \"unique_visitor_id\",\n \"exclude\": [42],\n \"filter\": \"price\
\ > 100\",\n \"labels\": [\"Search\"]\n \"facets\": [\"categories\", \"brands\"]}' \\\n \
\ http://api.clerk.io/v2/search/search"
name: POST
samples-languages:
- curl
/search/suggestions:
get:
summary: search/suggestions
description: Auto-complete the customer's search query as they type.
operationId: search-suggestions
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: query
in: query
description: The search query.
required: true
schema:
type: string
- name: limit
in: query
description: Number of results to be returned. Maximum 10.
required: true
schema:
type: integer
format: int32
- name: visitor
in: query
description: 'Required for tracking
Visitor ID for the given visitor.
If `auto`, an anonymous ID is generated.
See API
documentation on Visitor Tracking for details.'
schema:
type: string
- name: language
in: query
description: The language used for finding results. If not provided, the language configured on the Store in my.clerk.io
will be used.
schema:
type: string
- name: callback
in: query
description: JSONP - Wraps the response as a function call with the name of the string.
schema:
type: string
- name: debug
in: query
description: When `true`, the response will include a JSON dictionary of the various customisations made to the results
shown by Synonyms, Customized Search, Merchandising etc.
schema:
type: boolean
default: false
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"status\": \"ok\",\n \"result\": [\n \"blue running shoes\",\n \"blue running shoes\
\ men\",\n \"blue running shoes women\",\n \"blue running shoes kids\"\n ]\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
result:
type: array
items:
type: string
example: blue running shoes
- 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/search/suggestions?key=store_api_key&query=blue+running+sho&limit=6
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"query\": \"blue running sho\",\n \"language\": \"english\",\n \"limit\": 6,\n \
\ \"visitor\": \"unique_visitor_id\"}' \\\n http://api.clerk.io/v2/search/suggestions"
name: POST
samples-languages:
- curl
/subscriber/subscribe:
get:
summary: subscriber/subscribe
description: Subscribe an email address globally or to a specific list
operationId: subscriberssubscribe
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: email
in: query
description: The email address to subscribe for email marketing.
required: true
schema:
type: string
- name: list_id
in: query
description: An optional ID of a list for the email address to be subscribed to. Email address will also be subscribed
globally if it was not already.
List IDs are found in my.clerk.io under *Email > Lists*.
schema:
type: string
- name: redirect
in: query
description: If true, redirects the user to my.clerk.io to confirm subscription. Can be combined with `redirect_url`
to send user to a specific URL.
schema:
type: boolean
default: false
- name: redirect_url
in: query
description: An optional URL to redirect to after the user is successfully subscribed.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
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
- 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/subscriber/subscribe?key=store_api_key&email=luke@skywalker.org&list_id=RFPGVQFA
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"email\": \"luke@skywalker.org\",\n \"list_id\": \"RFPGVQFA\"}' \\\n http://api.clerk.io/v2/subscriber/subscribe"
name: POST
samples-languages:
- curl
/subscriber/unsubscribe:
get:
summary: subscriber/unsubscribe
description: Unsubscribe an email address globally or from a specific list
operationId: subscribersunsubscribe
parameters:
- name: key
in: query
description: You store API key.
required: true
schema:
type: string
- name: email
in: query
description: The email address to unsubscribe for email marketing.
required: true
schema:
type: string
- name: list_id
in: query
description: An optional ID of a list for the email address to be unsubscribed from. If not provided, recipient will
be unsubscribed globally.
List IDs are found in my.clerk.io under *Email > Lists*.
schema:
type: string
- name: redirect
in: query
description: If true, redirects the user to my.clerk.io to confirm that they are unsubscribed. Can be combined with
`redirect_url` to send user to a specific URL.
schema:
type: boolean
default: false
- name: redirect_url
in: query
description: An optional URL to redirect to after the user is successfully unsubscribed.
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
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
- 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/subscriber/unsubscribe?key=store_api_key&email=luke@skywalker.org&list_id=RFPGVQFA
name: GET
- language: curl
code: "curl -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"key\": \"store_api_key\",\n \
\ \"email\": \"luke@skywalker.org\",\n \"list_id\": \"RFPGVQFA\"}' \\\n http://api.clerk.io/v2/subscriber/unsubscribe"
name: POST
samples-languages:
- curl
/synonyms:
get:
summary: /synonyms
description: ''
operationId: synonyms-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
schema:
type: string
- name: synonyms
in: query
description: The queries which to fetch synonyms for
schema:
type: array
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n 'status' : 'ok',\n 'synonyms' :\n \t[\n {'query':'hello', 'directed_synonyms':['hi'],'synonyms':['hello\
\ there','greetings']},\n {'query':'shirt', 'directed_synonyms':['sweater'],'synonyms':['cardigan']}\n\
\ ]\n}"
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
post:
summary: /synonyms
description: ''
operationId: synonyms-post
requestBody:
content:
application/json:
schema:
type: object
required:
- key
properties:
key:
type: string
description: The public key of the store
private_key:
type: string
description: The private key of the store
synonyms:
type: array
description: List of synonym objects
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n 'status' : 'ok',\n}"
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
patch:
summary: /synonyms
description: ''
operationId: synonyms-patch
requestBody:
content:
application/json:
schema:
type: object
required:
- key
properties:
key:
type: string
description: The public key of the store
private_key:
type: string
description: The private key of the store
synonyms:
type: array
description: List of synonym objects
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n 'status' : 'ok',\n}"
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
delete:
summary: /synonyms
description: ''
operationId: synonyms-delete
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
schema:
type: string
- name: synonyms
in: query
description: The queries which to delete synonyms for
schema:
type: array
items:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n 'status' : 'ok',\n}"
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
/token/verify:
get:
summary: Verify
description: This provides an overview of the verify endpoint. It's general use is to see if the token you have in the
cookie header is valid or not.
operationId: token-verification
parameters:
- name: token
in: query
description: The token we want to verify, note this will be overwritten if you have a jwt token in your cookie
required: true
schema:
type: string
- name: key
in: query
description: public_key of the store the verification token is made for. Only required for importers
schema:
type: string
- name: jwt
in: header
description: signed jwt token we want to verify as an http only, secure cookie.
schema:
type: string
default: 'Cookie: jwt=TOKEN'
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '{"status":"ok", "token_payload":PAYLOAD}'
deprecated: false