HTTP API (Product Catalog)
Reasons to use HTTP API import
Too many products in the database (over 200,000).
New arrivals often come in small quantities, making it unreasonable to create a new XML with hundreds of thousands of products for the sake of a few new ones.
Product changes must be applied more quickly than the time it takes to generate the XML and have it processed by the system.
Case Sensitivity
All parameter names are case-sensitive and should follow the spelling used in this documentation.
Import/Update Categories
This part describes how to import product categories into PersonaClick using HTTP API import.
Request
Endpoint | Request Type | Action | Content Type | Rate Limit | Max Data Size |
|---|---|---|---|---|---|
https://api.personaclick.com/import/categories | POST | Overwrite | application/json | 40 requests/minute 1 request/1.5 seconds | 32 MB/request |
PUT | Update |
Exceeding the limit will result in a 429 "Too Many Requests" HTTP error. The request can be repeated after the rate limit period.
API Response
HTTP status code | Description |
|---|---|
204 No content | Authentication was successful. The data was accepted and queued for processing in the background. If the data processing fails, the account owner and employees authorized to receive technical notifications will be sent an email describing the error. |
400 Bad request | Authorization failed. |
While working with the API, you may encounter typical situations with HTTP status codes from the following groups: 4xx “Client Error” and 5xx “Server Error”.
If you receive an HTTP status code from the 4xx “Client Error” group, you should check the request data for correctness or resend the request if the error is related to exceeding limits.
If you receive an HTTP status code from the 5xx “Server Error” group, you should postpone the execution of requests for 10-15 minutes. If the period is longer, please contact Personaclick support.
Request Data Syntax
Name | Type | Requirement | Description |
|---|---|---|---|
shop_id | string | required | Unique Store Key in PersonaClick. Located there: Account > Settings > Store Settings |
shop_secret | string | required | The store's Secret Key in PersonaClick. Located there: Account > Settings > Store Settings |
categories | array | required | Array with category property objects. See description below. |
webhook | string | optionally | The webhook URL to which a request will be sent upon successful or failed import. This is a POST request with "Content-Type: application/json" and with a body in case of success: {
"status":"success"
}or in case of failure: {
"status":"error",
"message":"ERROR MESSAGE"
} |
{
shop_id: "...",
shop_secret: "...",
categories: [object, object, ...]
} Category Object
Name | Type | Requirement | Description |
|---|---|---|---|
id | string | required | Category ID |
name | string | required | Category Name |
parent | string | required for subcategories | Parent category ID. This property must have NULL value for categories that have no parent category. |
url | string | optionally | Category URL |
alias | string | optionally | Category Page URL |
Example of Categories Request
{
"shop_id": "eehj3eu84299kg5ghw5a6743r8",
"shop_secret": "pmd5362597thrgq8k256ep01t0",
"categories": [
{
"id": 1,
"name": "Main category",
"parent": null,
"url": "https://mysite.com/catalog",
"alias": "main"
},
{
"id": 2,
"name": "Apparel",
"parent": 1,
"url": "https://mysite.com/catalog/apparel",
"alias": "apparel"
},
{
"id": 3,
"name": "Hoverboards",
"parent": 1,
"url": "https://mysite.com/catalog/hoverboards",
"alias": "hoverboards"
},
{
"id": 14,
"name": "Child Hoverboards",
"parent": 3,
"url": "https://mysite.com/categories/hoverboards/child",
"alias": "hoverboards/child"
}
]
}
Deleting Categories
This part describes how to delete product categories using HTTP API import.
Request
Endpoint | Request Type | Content Type | Rate Limit | Max Data Size |
|---|---|---|---|---|
https://api.personaclick.com/import/categories | DELETE | application/json | 40 requests/minute 1 request/1.5 seconds | 32 MB/request |
Exceeding the limit will result in a 429 "Too Many Requests" HTTP error. The request can be repeated after the rate limit period.
API Response
HTTP status code | Description |
|---|---|
204 No content | Authentication was successful. The data was accepted and queued for processing in the background. If the data processing fails, the account owner and employees authorized to receive technical notifications will be sent an email describing the error. |
400 Bad request | Authorization failed. |
While working with the API, you may encounter typical situations with HTTP status codes from the following groups: 4xx “Client Error” and 5xx “Server Error”.
If you receive an HTTP status code from the 4xx “Client Error” group, you should check the request data for correctness or resend the request if the error is related to exceeding limits.
If you receive an HTTP status code from the 5xx “Server Error” group, you should postpone the execution of requests for 10-15 minutes. If the period is longer, please contact Personaclick support.
Request Data Syntax
Name | Type | Requirement | Description |
|---|---|---|---|
shop_id | string | required | Unique Store Key in PersonaClick. Located there: Account > Settings > Store Settings |
shop_secret | string | required | The store's Secret Key in PersonaClick. Located there: Account > Settings > Store Settings |
categories | array | required | Array with category IDs. See description below. |
webhook | string | optionally | The webhook URL to which a request will be sent upon successful or failed import. This is a POST request with "Content-Type: application/json" and with a body in case of success: {
"status":"success"
}or in case of failure: {
"status":"error",
"message":"ERROR MESSAGE"
} |
{
shop_id: "...",
shop_secret: "...",
categories: ["categoryID1", "categoryID2", ...]
} Example of Categories Request
{
"shop_id": "eehj3eu84299kg5ghw5a6743r8",
"shop_secret": "pmd5362597thrgq8k256ep01t0",
"categories": ["1", "2", "3", "14", "100500", "146-ABC"]
} Import Locations
This part describes how to import store locations into PersonaClick using HTTP API import.
Request
Endpoint | Request Type | Content Type | Rate Limit | Max Data Size |
|---|---|---|---|---|
https://api.personaclick.com/import/locations | POST | application/json | 40 requests/minute 1 request/1.5 seconds | 32 MB/request |
Exceeding the limit will result in a 429 "Too Many Requests" HTTP error. The request can be repeated after the rate limit period.
API Response
HTTP status code | Description |
|---|---|
204 No content | Authentication was successful. The data was accepted and queued for processing in the background. If the data processing fails, the account owner and employees authorized to receive technical notifications will be sent an email describing the error. |
400 Bad request | Authorization failed. |
While working with the API, you may encounter typical situations with HTTP status codes from the following groups: 4xx “Client Error” and 5xx “Server Error”.
If you receive an HTTP status code from the 4xx “Client Error” group, you should check the request data for correctness or resend the request if the error is related to exceeding limits.
If you receive an HTTP status code from the 5xx “Server Error” group, you should postpone the execution of requests for 10-15 minutes. If the period is longer, please contact Personaclick support.
Request Data Syntax
Name | Type | Requirement | Description |
|---|---|---|---|
shop_id | string | required | Unique Store Key in PersonaClick. Located there: Account > Settings > Store Settings |
shop_secret | string | required | The store's Secret Key in PersonaClick. Located there: Account > Settings > Store Settings |
locations | array | required | Array with location objects. See description below. |
webhook | string | optionally | The webhook URL to which a request will be sent upon successful or failed import. This is a POST request with "Content-Type: application/json" and with a body in case of success: {
"status":"success"
}or in case of failure: {
"status":"error",
"message":"ERROR MESSAGE"
} |
{
shop_id: "...",
shop_secret: "...",
locations: [object, object, ...]
} Location Object
Name | Type | Requirement | Description |
|---|---|---|---|
id | string | required | Location ID |
name | string | required | Location Name |
parent | string | required for sublocations | Parent location ID. This property must have NULL value for categories that have no parent category. |
group | string | optionally | Grouping of locations by any custom property. For example: "cash only", "wholesale", etc. |
Example of Locations Request
{
shop_id: "eehj3eu84299kg5ghw5a6743r8",
shop_secret: "pmd5362597thrgq8k256ep01t0",
locations: [
{
id: 1,
name: "New York",
parent: null,
group: "city"
},
{
id: 2,
name: "Los Angeles",
parent: null,
group: "city"
},
{
id: 3,
name: "Brighton Beach",
parent: 1
},
{
id: 4,
name: "Beverly Hills",
parent: 2
}
]
}
Import/Update Products
This part describes how to import products into PersonaClick using HTTP API import.
Requests
Endpoint | Request Types | Content Type | Rate Limit | Max Data Size |
|---|---|---|---|---|
https://api.personaclick.com/import/products | PUT | application/json | 40 requests/minute 1 request/1.5 seconds | 32 MB/request |
Exceeding the limit will result in a 429 "Too Many Requests" HTTP error. The request can be repeated after the rate limit period.
Operation | Request Type | Description |
|---|---|---|
Add | PUT | Adds a new or updates existing products |
API Response
HTTP status code | Description |
|---|---|
204 No content | Authentication was successful. The data was accepted and queued for processing in the background. If the data processing fails, the account owner and employees authorized to receive technical notifications will be sent an email describing the error. |
400 Bad request | Authorization failed. |
423 Locked | This response code is possible if one of the previous requests was a PATCH request (see its description), which hasn't finished its work yet. Should keep this in mind in development and repeat sending the current request until it succeeds. |
While working with the API, you may encounter typical situations with HTTP status codes from the following groups: 4xx “Client Error” and 5xx “Server Error”.
If you receive an HTTP status code from the 4xx “Client Error” group, you should check the request data for correctness or resend the request if the error is related to exceeding limits.
If you receive an HTTP status code from the 5xx “Server Error” group, you should postpone the execution of requests for 10-15 minutes. If the period is longer, please contact Personaclick support.
Request Data Syntax
Name | Type | Requirement | Description |
|---|---|---|---|
shop_id | string | required | Unique Store Key in PersonaClick. Located there: Account > Settings > Store Settings |
shop_secret | string | required | The store's Secret Key in PersonaClick. Located there: Account > Settings > Store Settings |
items | array | required | Array with product property objects. See description below. |
webhook | string | optionally | The webhook URL to which a request will be sent upon successful or failed import. This is a POST request with "Content-Type: application/json" and with a body in case of success: {
"status":"success"
}or in case of failure: {
"status":"error",
"message":"ERROR MESSAGE"
} |
Product Object
Name | Type | Requirement | Description |
|---|---|---|---|
id | string | required | Product ID. Max 64 symbols. |
group_id | string | optionally | Used to combine several variants of the same product into a group. The system will automatically use the most relevant product variant in the tools. If the product variants don't have this property, the system will consider each product variant as a separate product. |
available | boolean | required | Product Availability |