Method Objective

The method allows importing order history or updating of orders previously imported or created by tracking, as well as changing order statuses.

Don't use this method to create new orders. The creation of new orders should be done by tracking user activity in a way that is appropriate for your platform. See REST API, JS SDK or Mobile SDKs.

Request

Endpoint	Request Type	Content-Type	Max Data Size

Endpoint	Request Type	Content-Type	Max Data Size
https://api.personaclick.com/sync/orders	POST	application/json	32 MB/request

Parameters

Name	Type	Requirement	Description

Name	Type	Requirement	Description
shop_id	string	required	Unique Store Key in PersonaClick. Located there: Account > Settings > Store Settings
shop_secret	string	required	Store Secret Key in PersonaClick. Located there: Account > Settings > Store Settings
orders	Array	required	Object array with orders. See the description below.

Order Object

Name	Type	Requirement	Updatable on re-import (sync)	Description

Name	Type	Requirement	Updatable on re-import (sync)	Description
id	string	required	no	Order ID. If the Order ID and Order Number aren't the same, it's recommended to use the Order Number value. This will allow for easy comparison of orders on both sides. Also, note that the source of this property must be the same as the one used in the User Activity Tracking (Purchase Event). Please note that order IDs in UUID format aren't displayed in the dashboard. Instead of UUDI, "---" will be displayed. To avoid this, add any prefix to this.
status	string	required	yes	Order Status. The status matching must be set there in advance: Account > Settings > Order Statuses
channel	string	required for a new order	yes	The name of the sales channel. Any string value, such as "website", "offline", "mobile_ios", "mobile_android", "infokiosk", "pos", "callcenter", etc.
date	number	required for a new order	no	Order date in UNIX timestamp format (in seconds). Milliseconds and microseconds aren't supported.
value	Object	required for a new order	yes	Describes the parts from which the final cost of the order is calculated. See the description below.
items	Array	required for a new order or an order where the status has been updated for at least one product	yes	Describes the products of the order. See the description below. This property should be missing if the synchronization of the status of an existing order is performed.
custom	Object	optional	yes	Custom properties of the order. The properties should be pre-created: Account > Settings > Order properties The following data types are supported: - string - integer - float - array - array of string (preset string values) - json - date (YYYY-MM-DD hh:mm:ss) See example below.
offline	boolean	optionally	yes	Sets whether the order was created offline or not. Default: false.
email	string	At least one is required so that an order can be bound to a profile	no	User's email.
phone	string		no	User's phone in full international format. A phone number in full international format may begin with a plus sign (+) followed by the country code, city (area) code, and phone number.
loyalty_id	string		no	User's Loyalty ID.
external_id	string		no	User's store ID.
telegram_id	string		no	User's telegram ID.
location_id	string	optional	yes	User's Location. Should match the value from the previously given list of locations (HTTP API, XML feed).
promocode	string	optional	yes	The promo code that the user applied at checkout.
delivery_type	string	optional	yes	Delivery Type, e.g. "courier", "self_pickup", "delivery", "pickup_point", etc.
delivery_address	string	optional	yes	Shipping address.
delivery_date	string	optional	yes	Date of delivery, planned or completed. Format: YYYY-MM-DD.
delivery_time	string	optional	yes	Time of delivery, planned or completed. Format: hh:mm.
payment_type	string	optional	yes	The method of payment, such as "cash", "card", "wire", etc.
tax_free	boolean	optional	yes	It sets whether the order was placed with Tax-Free or not.
bank_issuer	string	optional	yes	Issuing bank.
bank_pos_processor	string	optional	yes	Bank POS processor.
bank_loyalty_program	string	optional	yes	Bank loyalty program.
bank_total_installment	number	optional	yes	Total bank installment.
payment_card_provider	string	optional	yes	Payment Card Provider.
gift_package	boolean	optional	yes	Gift package included or not.
payment_structure	object	optional	yes	Custom values of the payment methods of the order. Can have any parameter name with a positive or negative numeric value (in money), the sum of which must be equal to the "value.total" value. See the example below. Some properties are automatically recognized by the system for certain purposes: bonuses cash delivery discount
comment	string	optional	yes	Custom text comment about an order. The maximum string length is 500 symbols.
stream	string	optional	yes	Data stream code. Alphanumeric string (letters, numbers only). Max length: 16. The empty default value will mean "web". Can be "ios", "android" or any other string. Used to distinguish between mobile apps, websites, and other events sources.

Value Object

Name	Type	Requirement	Updatable on re-import (sync)	Description

Name	Type	Requirement	Updatable on re-import (sync)	Description
total	number	required	yes	Order's total value.
delivery	number	optional	yes	Describes the cost of delivery of the order.

Items Array

Name	Type	Requirement	Updatable on re-import (sync)	Description

Name	Type	Requirement	Updatable on re-import (sync)	Description
id	string	required	yes	Product ID.
price	number	required	yes	Cost per unit of product.
quantity	number	required	yes	The product quantity in the order.
status	string	optional	yes	Item (product) status. Can only have the following values: created, invoiced, shipped, delivered, cancelled, refunded. If the status of at least one product in an order is updated, all products should be included in the request.
original_price	number	optional	yes	The base price of the product.
discount_product	number	optional	yes	Describes the amount of discount (in money) applied to the product.
discount_coupon	number	optional	yes	Describes the amount of discount (in money) applied to the product by using the discount coupon.
discount_bonuses	number	optional	yes	Describes how much of the product's value was paid by bonuses.
delivery_company	string	optional	yes	Product-specific delivery company.
line_id	string	optional	yes	The unique ID of the product position in the order on the store side. If set, this property has priority over the "id", "barcode" properties when searching for a product of order in the order history.
barcode	string	optional	no, if it's already set	Product barcode. If set, this property has priority over the "id" property when searching for a product of order in the order history.
cancel_reason	string	optional	yes	Any description of the reason for returning the product.

API Response Code

HTTP status code	Description

HTTP status code	Description
200 OK	Authorization was successful. The import process is asynchronous and executes in the background. The system checks only if the value types are correct, but not if the values themselves are correct. First, make sure by importing one order that the data is correct, then import all necessary orders.
400 Bad Request	Unsuccessful authorization.

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.

Import/Sync Orders (REST API)