Method Objective

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

Warning
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	Rate Limit	Max Data Size
https://api.personaclick.com/sync/orders	POST	application/json	40 requests/minute	32 MB/request

Parameters

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

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

Note
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

yes

Order date in UNIX timestamp format (in seconds).

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

Warning
This property should be missing if the synchronization of the status of an existing order is performed.

custom

Object

optionally

yes

Custom properties of the order. The properties should be pre-created: Account > Settings > Order properties

The following data types are supported:
- string
- integer
- date (YYYY-MM-DD)

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.

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

location_id

string

optionally

yes

User's Location. Should match the value from the previously given list of locations (HTTP API, XML feed).

promocode

string

optionally

yes

The promo code that the user applied at checkout.

delivery_type

string

optionally

yes

Delivery Type, e.g. "courier", "self_pickup", "delivery", "pickup_point", etc.

delivery_address

string

optionally

yes

Shipping address.

delivery_date

string

optionally

yes

Date of delivery, planned or completed. Format: YYYY-MM-DD.

delivery_time

string

optionally

yes

Time of delivery, planned or completed. Format: hh:mm.

payment_type

string

optionally

yes

The method of payment, such as "cash", "card", "wire", etc.

tax_free

boolean

optionally

yes

It sets whether the order was placed with Tax-Free or not.

bank_issuer

string

optionally

yes

Issuing bank.

bank_pos_processor

string

optionally

yes

Bank POS processor.

bank_loyalty_program

string

optionally

yes

Bank loyalty program.

bank_total_installment

number

optionally

yes

Total bank installment.

payment_card_provider

string

optionally

yes

Payment Card Provider.

gift_package

boolean

optionally

yes

Gift package included or not.

payment_structure

object

optionally

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.

comment

string

optionally

yes

Custom text comment about an order. The maximum string length is 500 symbols.

Value Object

Name	Type	Requirement	Updatable on re-import (sync)	Description
total	number	required	yes	Order's total value.
delivery	number

optionally

Describes the cost of delivery of the order.

~~cashnumberoptionally~~

~~Describes how much of the order's value was paid by cash.~~

Warning
Moved to the "payment_structure" property. See the description above.

~~bonusesnumberoptionally~~

~~Describes how much of the order's value was paid by bonuses.~~

Warning
Moved to the "payment_structure" property. See the description above.

~~discountnumberoptionally~~

~~Describes the amount of discount (in money) applied to the order.~~

WarningMoved to the "payment_structure" property. See the description above.

optionally

yes

Describes the cost of delivery of the order.

Items Array

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

optionally

yes

Item (product) status. Can only have the following values: created, invoiced, shipped, delivered, cancelled, refunded.

Note
If the status of at least one product in an order is updated, all products should be included in the request.

original_price

number

optionally

yes

The base price of the product.

discount_product

number

optionally

yes

Describes the amount of discount (in money) applied to the product.

discount_coupon

number

optionally

yes

Describes the amount of discount (in money) applied to the product by using the discount coupon.

discount_bonuses

number

optionally

yes

Describes how much of the product's value was paid by bonuses.

delivery_company

string

optionally

yes

Product-specific delivery company.

line_id

string

optionally

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

optionally

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

optionally

yes

Any description of the reason for returning the product.

API Response Code

HTTP status code

Description

200 OK

Authorization was successful.

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

Request Example

Code Block

language	js
theme	FadeToGrey

curl 'https://api.personaclick.com/sync/orders' \
  -X 'POST' \
  -H 'content-type: application/json' \
  --data-binary '@data.json'

# data.json
{
    "shop_id": "0d42fd8b713d0752776ca589cc0056",
    "shop_secret": "0123456789abcdef0123456789abcdef",
    "orders": [
        {
            "id": "ORDER_ID_1",
            "status": "Delivered",
            "channel": "website",
            "date": 1626344304,
            "offline": false,
            "email": "john.doe@examplemail.com",
            "phone": "+4400114527199",
            "loyalty_id": "000001234567",
            "location_id": "NY",
            "promocode": "vxawxSi9Uy",
            "delivery_type": "courier",
            "delivery_address": "146, Somewhere Ave, NY",
            "delivery_date": "2021-08-21",
            "delivery_time": "00:01",
            "payment_type": "card",
            "tax_free": false,
            "bank_issuer": "Garanti BBVA",
            "bank_pos_processor": "Apex",
            "bank_loyalty_program": "miles&smiles",
            "bank_total_installment": 4,
            "payment_card_provider": "mastercard",
            "gift_package": true,
            "value": {
                "total": 112.13,
                "delivery": 20
            },
            "payment_structure": {
                "cash": 67.13,
                "bonuses": -20,
                "credit_card": 30,
                "masterpass": 20,
                "credit_check": 15,
                "gift_card": -10,
                "bank_transfer": 15,
                "discount_coupon": -10,
                "bla-bla-wallet": 5
            },
            "custom": {
                "order_comment": "Delivery after 15:00, 2nd floor, apt. 222",
                "boxes": 2,
                "refund_date": "2021-09-21"
            },
            "items": [
                {
                    "id": "ITEM-ID-1",
                    "price": 205,
                    "quantity": 1,
                    "status": "cancelled",
                    "original_price": 270,
                    "discount_product": 30,
                    "discount_coupon": 10,
                    "discount_bonuses": 25,
                    "delivery_company": "ups",
                    "barcode": "195204003541",
                    "line_id": "195204003541-22323443-123434",
                    "cancel_reason": "over size"
                },
                {
                    "id": "ITEM-ID-2",
                    "price": 3,
                    "quantity": 4
                }
            ]
        },
        {
            "id": "ORDER_ID_2",
            "status": "Delivered",
            "channel": "website",
            "date": 1626344414,
            "offline": false,
            "email": "peter.parker@examplemail.com",
            "phone": "+4400145291711",
            "loyalty_id": "000000001",
            "location_id": "NY",
            "promocode": "vxawxSi9Uy",
            "delivery_type": "courier",
            "delivery_address": "Forest Hills, Queens",
            "delivery_date": "2021-07-20",
            "delivery_time": "10:01",
            "value": {
                "total": 211.13,
                "cash": 190,
                "bonuses": 27,
                "delivery": 20,
                "discount": 24.87
            },
            "items": [
                {
                    "id": "ITEM-ID-3",
                    "price": 204,
                    "quantity": 1
                },
                {
                    "id": "ITEM-ID-4",
                    "price": 3,
                    "quantity": 4
                }
            ]
        }
    ]
}

Column

Page Navigation

Table of Contents

maxLevel	1
indent	0px
style	none

Related Pages

Filter by label (Content by label)

showLabels	false
showSpace	false
sort	title
cql	label in ( "imports" , "orders" )

Versions Compared

Old Version 31

New Version Current

Key

Method Objective

Request

Parameters

Order Object

Value Object

Items Array

API Response Code

Request Example

Page Comparison

Versions Compared

Old Version 31

New Version Current

Key

Method Objective

Request

Parameters

Order Object

Value Object

Items Array

API Response Code

Request Example