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.

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

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: [category, category, ...]
}

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: [location, location, ...]
}

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.

Example of Categories Request

{
    shop_id:      "eehj3eu84299kg5ghw5a6743r8",  
    shop_secret:  "pmd5362597thrgq8k256ep01t0",
    locations:    [
        {
            id:           1,
            name:         "New York",
            parent:       null
        },
        {
            id:           2,
            name:         "Los Angeles",
            parent:       null
        },
        {
            id:           3,
            name:         "Brighton Beach",
            parent:       1
        },
        {
            id:           4,
            name:         "Beverly Hills",
            parent:       2
        }
    ]
}

Requests for Import and Update

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	POST, PUT	application/json	40 requests/minute	32 MB/request

Operation	Request Type	Description
Overwrite	POST	Rewrite the database removing all previously imported records and adding new items
Add	PUT	Update the database adding new items (no rewriting)

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.

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.
available	boolean	required	Product Availability
name	string	required	Product Name. Max 255 symbols.
price	number	required	Product Price
url	string	required	Product Page URL
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
locations	array	optionally	Product Locations. See description below.
brand	string	optionally	Product Brand
barcode	string	optionally	Product Barcode
price_margin	number	optionally	Product Margin
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 description below.
cosmetic	object	optionally	Additional properties for a product from the cosmetic niche. See description below.
child	object	optionally	Additional properties for a product from the cosmetic niche. See description below.
book	object	optionally	Additional properties for a product from the niche of children's products. See description below.
params	array	optionally	Additional custom properties. See description below.
is_new	boolean	optionally	The product is from a new arrival.
customer_recommendations	array	optionally	Allows setting manually recommended products for a specific product. Need to set in the array the product IDs.

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.

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

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.

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

Example of Products Request

{
    shop_id: "eehj3eu84299kg5ghw5a6743r8",   
    shop_secret: "pmd5362597thrgq8k256ep01t0",   
    items:            [
        {
            id:             "6335",
            name:           "Hoverboard 100500",
            price:          1000,
            currency:       "USD",
            url:            "https://examplestore.com/products/6335.html",
            picture:        "https://examplestore.com/pictures/6335.jpg",
            available:      true, 
            categories:     [14, 3],
            barcode:        0123456789,
            price_margin:   10,
            locations: [
                {
                    location: "New York"
                },
                {
                    location: "Los Angeles",
                    price: 1250,
                    oldprice: 1500
                }
            ],
            brand:          "Dr. Emmett Brown",
            tags:           ["titanium", "steel", "sport"],
            is_child:       true
        },
        {
            id:             133
            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"
            }
        }
    ]
}

Synchronization Request

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.

{
    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.

Deletion Request

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.

Initialization (REST API)

Reasons to use HTTP API import

Import Categories

Request

API Response

Request Data Syntax

Category Object

Example of Categories Request

Import Locations

Request

API Response

Request Data Syntax

Location Object

Example of Categories Request

Requests for Import and Update

Requests

API Response

Request Data Syntax

Product Object

Fashion Object

Cosmetic Object

Child Object

Book Object

Locations Array

Example of Products Request

Synchronization Request

Requests

Request Data Syntax

API Response

Deletion Request

Requests

Request Data Syntax

API Response