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 Categories

This part describes how to import product categories into PersonaClick using HTTP API import.

Request

Endpoint	Request Type	Content Type	Rate Limit	Max Data Size
https://api.personaclick.com/import/categories	POST	application/json	40 requests/minute	32 MB/request

Each request overwrites previously imported categories.

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.

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.

{
    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"
        }
	]
}

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	32 MB/request

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.

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.

{
    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 and 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	32 MB/request

Operation	Request Type	Description
Add	PUT	Adds a new or updates existing products

In the situation lacking a technical feasibility to send PUT request, use POST requests and add to the JSON-body a variable method with the corresponding value in the upper case: PUT.

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.

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.

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
name	string	required	Product Name. Max 255 symbols.
price	number	required	Product Price
url	string	required	Product Page URL
deeplink_android	string	optionally	Deep link to a product for an Android app.
deeplink_ios	string	optionally	Deep link to a product for an iOS app.
picture	string	required	Product Picture URL
categories	array	required	Product Categories. See description below.
currency	string	required	Currency code: USD, EUR, TRY, etc.
oldprice	number	optionally	Product Old Price
discount_percent	number	optionally	User-defined discount value. Usually, the "price" and "old_price" values are used to calculate the discount value. The "discount_percent" property allows to set the discount value in advance.
installment	number	optionally	The payment cost if purchasing the product in installments.
promocode	string	optionally	The promo code is for a specific product.
price_with_promocode	number	optionally	The product price when using the promo code specified for the product.
locations	array	optionally	Product Locations. See description below. If the property isn't used, the product is considered available in all known locations.
type_prefix	string	optionally	Type/category of product (for example: "mobile phone", "washing machine", "corner sofa")
model	string	optionally	Model and product name
brand	string	optionally	Product Brand
barcode	string	optionally	Product Barcode
vendor_code	string	optionally	Manufacturer product code
price_margin	number	optionally	Product Margin It only can be a value from 0 to 100 (in percent). Using values greater than 100 leads to unpredictable results of calculation formulas.
tags	array	optionally	Product-Related Tags
is_child	boolean	optionally	The product is for children or not
is_fashion	boolean	optionally	The product is clothing or not
fashion	object	optionally	Additional properties for a product from the clothing and accessories niche. See the description below.
cosmetic	object	optionally	Additional properties for a product from the cosmetic niche. See the description below.
child	object	optionally	Additional properties for a product from the niche of children's products. See the description below.
book	object	optionally	Additional properties for a product from the book niche. See the description below.
jewelry	object	optionally	Additional properties for a product from the jewelry niche. See the description below.
is_new	boolean	optionally	The product is from a new arrival.
seasonality	array	optionally	Product seasonality. The sequence number of the month (from 1 to 12) is used as the value.
accessories	array	optionally	Allows setting manually recommended products for a specific product. Need to set in the array the product IDs.
customer_recommendations	array	optionally	This has a similar meaning to the "accessories" property. Support for this property will be discontinued on 2024-01-01.
stock_quantity	number	optionally	The available quantity of products. Integer value from 1 and more.
leftovers	string	optionally	Rough number of the products left in stock. Available values are: one - one product few - 2-10 products lot - over 10 products
rating	number	optionally	Product rating. Integer value from 1 to 5.
gift	boolean	optionally	Specifies whether the product is a gift.
description	string	optionally	Product description Please contact your account manager to activate this property.
date	string	optionally	Any date in YYYY-MM-DD format This is typically used to specify the creation date for sorting products by newness.
params	Object array	optionally	Additional parameters. See the description below.

Fashion Object

Name	Type	Requirement	Description
gender	string	optionally	Product relating to a specific gender. See the available values in the "Apparel & Accessories" section of the XML product feed.
type	string	optionally	Product relating to a specific type. See the available values in the "Apparel & Accessories" section of the XML product feed.
sizes	array	required if the "type" property is set	An array of available sizes. See the size value format in the "Apparel & Accessories" section of the XML product feed.
colors	array	optionally	Object array with available product colors and product image URLs to the corresponding color. See example below.
feature	string	optionally	The product has some features. Available values: adult (default), child, pregnant.

{
    gender: "m",
	sizes:  ["XS", "S", "L"], // "M" and "XL" sizes aren't available
    type:   "shoe",
	colors: [
        {
            color: "blue",
            picture: "https://examplestore.com/product/100500/images/blue.jpg"
        }, 
        {
            color: "yellow",
            picture: "https://examplestore.com/product/100500/images/yellow.jpg"
        }
    ],
    feature: "child"
}

Cosmetic Object

Name	Type	Requirement	Description
gender	string	optionally	Product relating to a specific gender. See the available values in the "Cosmetics & Perfumes" section of the XML product feed.
hypoallergenic	boolean	optionally	The product is hypoallergenic or not. Default value: false.
skin	object	optionally	Allows marking a product that relates to a specific skin type. Values for available properties: type, condition, part are available in the "Cosmetics & Perfumes" section of the XML product feed.
hair	object	optionally	Allows marking a product that relates to a specific hair type. Values for available properties: type, condition are available in the "Cosmetics & Perfumes" section of the XML product feed.
nail	object	optionally	Allows marking a product that relates to a specific nail type. Values for available properties: type, polish_color are available in the "Cosmetics & Perfumes" section of the XML product feed.
perfume	object	optionally	Allows filling the product with the properties of the perfume niche. Values for available properties: family, aroma are available in the "Cosmetics & Perfumes" section of the XML product feed.
periodic	boolean	optionally	The product is professional or not. Default value: false.
professional	boolean	optionally	The product is professional or not. Default value: false.

Child Object

Name	Type	Requirement	Description
gender	string	optionally	Product relating to a specific gender. See the available values in the "Baby & Children" section of the XML product feed.
type	string	optionally	Product relating to a specific type. See the available values in the "Baby & Children" section of the XML product feed.
age	object	optionally	Product relating to a specific age. See the available values in the "Baby & Children" section of the XML product feed.

Book Object

Name	Type	Requirement	Description
author	string	optionally	Allows specifying the author of a work, book, etc.
publisher	string	optionally	Allows specifying the publisher of a work, book, etc.
series	string	optionally	Allows specifying a series of works.
year	number	optionally	Allows specifying the year of publishing.
isbn	array	optionally	Allows listing the ISBNs. The values in the array must be of string type.

Jewelry Object

Name	Type	Requirement	Description
gender	string	optionally	Product relating to a specific gender. See the available values in the "Jewelry" section of the XML product feed.
ring_sizes	array	optionally	The product has specific ring sizes. See the example below.
bracelet_sizes	array	optionally	The product has specific bracelet sizes. See the example below.
chain_sizes	array	optionally	The product has specific chain sizes. See the example below.
color	string	optionally	The product has a specific color. See the available values in the "Jewelry" section of the XML product feed.
metal	string	optionally	The product made of a specific metal. See the available values in the "Jewelry" section of the XML product feed.
gem	string	optionally	The product with a specific gemstone. See the available values in the "Jewelry" section of the XML product feed.

Locations Array

The "locations" array specifies the product availability status for various cities/towns as well as any alterations in price in these cities/towns. Your default price is used if the price alterations have not been stated in this object.

Name	Type	Requirement	Description
location	string	required	Location ID
price	number	optionally	Price for location
oldprice	number	optionally	Old price for location

Params Object

Name	Type	Requirement	Description
name	string	required	Parameter name
value	String array	required	An array of parameter string values. The maximum size of the string is 1000 symbols.
unit	string	required for numeric values	The measurement unit

params: [
    {
        name: "interface",
        value: ["bluetooth", "wi-fi"]
    },
    {
        name: "connection",
        value: [10, 100, 1000],
        unit: "MB"
    }
]

Example of Products Request

{
    shop_id: "eehj3eu84299kg5ghw5a6743r8",   
    shop_secret: "pmd5362597thrgq8k256ep01t0",   
    items: [
        {
            id: "6335",
            group_id: "3955",
            name: "Hoverboard 100500",
            price: 1000,
            old_price: 1200,
            discount_percent: 16,
            installment: 85,
            promocode: "BACKTOTHEFUTURE",
            price_with_promocode: 950,
            currency: "USD",
            url: "https://examplestore.com/products/6335.html",
            deeplink_android: "app_android://395532",
            deeplink_ios: "app_ios://395532",
            picture: "https://examplestore.com/pictures/6335.jpg",
            available: true, 
            categories: [
                14,
                3
            ],
            barcode: "0123456789",
            vendor_code: "HB100500",
            price_margin: 10,
            stock_quantity: 3,
            locations: [
                {
                    location: "New York"
                },
                {
                    location: "Los Angeles",
                    price: 1250,
                    oldprice: 1500
                }
            ],
            brand: "Dr. Emmett Brown",
            tags: [
                "titanium",
                "steel",
                "sport"
            ],
            is_child: true,
            accessories: [146, 100500],
            seasonality: [1, 2, 12],
            rating: 4,
            leftovers: "few",
            date: "2023-04-13"
        },
        {
            id: "133",
            group_id: "3955",
            name: "red jacket",
            price: 200,  
            currency: "USD",
            url: "https://examplestore.com/products/133.html",
            picture: "https://examplestore.com/pictures/133.jpg",
            available: true, 
            categories: [
                33
            ],
            locations: [
                {
                    "location": "New York"
                }
            ],
            brand: "McFly",
            tags: [
                "winter",
                "sport"
            ],
            is_fashion: true,
            fashion: {
                gender: "m",
                sizes: [
                    "M",
                    "L",
                    "XXL"
                ],
                type: "jacket"
            },
            params: [
                {
                    name: "drying",
                    value: [
                        30,
                        40,
                        60
                    ],
                    unit: "°C"
                }
            ]
        },
        {
            id: 146,
            name: "Diamond Ring",
            price: 1999.99,  
            currency: "USD",
            url: "https://examplestore.com/products/146.html",
            picture: "https://examplestore.com/pictures/146.jpg",
            available: true, 
            gift: true,
            categories: [
                55
            ],
            jewelry: {
                gender: "f",
                ring_sizes: [16, 16.5, 17],
                color: "yellow",
                metal: "gold",
                gem: "diamond"
            }
        }
    ]
}

Synchronization of Products Availability

Allows synchronizing the availability status of products. All products sent in the request will be marked as in stock, the rest as out of stock.

Requests

Endpoint	Request Type	Content Type	Rate Limit	Max Data Size
https://api.personaclick.com/import/products	PATCH	application/json	40 requests/minute	32 MB/request

Operation	Request Type	Description
Sync	PATCH	Sync product availability status

In the situation lacking a technical feasibility to send PATCH request, use POST requests and add to the JSON-body a variable method with the corresponding value in the upper case: PATCH.

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 IDs that should be marked as in stock. Can be an empty array to disable all products. If you are going to use a combination of "empty PATCH request + PUT requests" to periodically re-import the entire product database, please contact your account manager to activate this feature.

{
    shop_id:        "eehj3eu84299kg5ghw5a6743r8",	
    shop_secret:    "pmd5362597thrgq8k256ep01t0",	
    items:          [635, 3373, 75778]
}

# to disable all products
{
    shop_id:        "eehj3eu84299kg5ghw5a6743r8",	
    shop_secret:    "pmd5362597thrgq8k256ep01t0",	
    items:          []
}

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.

Deleting Products

Allows marking products in the request as out of stock. The statuses of the other products will remain unchanged.

Requests

Endpoint	Request Type	Content Type	Rate Limit	Max Data Size
https://api.personaclick.com/import/products	DELETE	application/json	40 requests/minute	32 MB/request

Operation	Request Type	Description
Remove	DELETE	Remove selected items from the database (mark the selected items as "out of stock")

In the situation lacking a technical feasibility to send DELETE request, use POST requests and add to the JSON-body a variable method with the corresponding value in the upper case: DELETE.

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 IDs that should be marked as out of stock.

{
    shop_id:        "eehj3eu84299kg5ghw5a6743r8",	
    shop_secret:    "pmd5362597thrgq8k256ep01t0",	
    items:          [635, 3373, 75778]
}

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.

Product Catalog Synchronization

The best practice of periodically synchronizing the product catalog.

Action	Period	Requests
The first import of the product catalog	Once	Importing categories (POST request) Importing locations (POST request) Importing products (PUT request)
Synchronization of the product catalog	Once a day	Importing categories (POST request) Importing locations (POST request) Synchronize product availability (PATCH request) Importing products (PUT request)
Synchronize products availability	Every an hour	Synchronize product availability (PATCH request)
Updating modified products, adding new ones, and deleting not-existed ones	Every 15 minutes	Importing products (PUT request) Deleting products (DELETE request)
Re-import the entire product base Please contact your account manager to activate this feature.	When it's necessary, for example, once a month	Disabling all products (empty PATCH request) Importing products (PUT request)

Multiple Requests

The system makes multiple simultaneous requests to download product images. Check the IP list and make sure they are all whitelisted on your side.

Page Navigation

Related Pages

Page:

Additional Part (XML)
Page:

HTTP API (Product Catalog)
Page:

Import Audience (REST API)
Page:

Import Suppressed Email (REST API)
Page:

Import/Sync Orders (REST API)
Page:

Required Part (XML)
Page:

Webhooks