Import/Sync Orders (REST API)

Owned by Andrey Veprikov
Last updated: Mar 05, 2024
9 min read

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

EndpointRequest TypeContent-TypeRate LimitMax Data Size
https://api.personaclick.com/sync/ordersPOSTapplication/json40 requests/minute32 MB/request

Parameters

NameTypeRequirementDescription
shop_idstringrequiredUnique Store Key in PersonaClick. Located there: Account > Settings > Store Settings
shop_secretstringrequiredStore Secret Key in PersonaClick. Located there: Account > Settings > Store Settings
ordersArrayrequiredObject array with orders. See the description below.

Order Object

NameTypeRequirementDescription
idstringrequired

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.

statusstringrequiredOrder Status. The status matching must be set there in advance: Account > Settings > Order Statuses
channelstringrequired for a new orderThe name of the sales channel. Any string value, such as "website", "offline", "mobile_ios", "mobile_android", "infokiosk", "pos", "callcenter", etc.
datenumberrequired for a new order

Order date in UNIX timestamp format (in seconds).

Milliseconds and microseconds aren't supported.

valueObjectrequired for a new orderDescribes the parts from which the final cost of the order is calculated. See the description below.
itemsArrayrequired for a new order or an order where the status has been updated for at least one product

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.

offlinebooleanoptionallySets whether the order was created offline or not. Default: false.
emailstringoptionally, but recommended for use when importing a new order to create a new user profile or to link an order to an existing profileUser's email.
phonestringoptionally, but recommended for use when importing a new order to create a new user profile or to link an order to an existing profile

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_idstringoptionally, but recommended for use when importing a new order to create a new user profile or to link an order to an existing profileUser's Loyalty ID.
location_idstringoptionallyUser's Location. Should match the value from the previously given list of locations (HTTP API, XML feed).
promocodestringoptionallyThe promo code that the user applied at checkout.
delivery_typestringoptionallyDelivery Type, e.g. "courier", "self_pickup", "delivery", "pickup_point", etc.
delivery_addressstringoptionallyShipping address.
delivery_datestringoptionallyDate of delivery, planned or completed. Format: YYYY-MM-DD.
delivery_timestringoptionallyTime of delivery, planned or completed. Format: hh:mm.
payment_typestringoptionallyThe method of payment, such as "cash", "card", "wire", etc.
tax_freebooleanoptionallyIt sets whether the order was placed with Tax-Free or not.
bank_issuerstringoptionallyIssuing bank.
bank_pos_processorstringoptionallyBank POS processor.
bank_loyalty_programstringoptionallyBank loyalty program.
bank_total_installmentnumberoptionallyTotal bank installment.
payment_card_providerstringoptionallyPayment Card Provider.
gift_packagebooleanoptionallyGift package included or not.
payment_structureobjectoptionallyCustom 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.
commentstringoptionallyCustom text comment about an order. The maximum string length is 500 symbols.

Value Object

NameTypeRequirementDescription
totalnumberrequired

Order's total value. 

deliverynumberoptionally

Describes the cost of delivery of the order. 

cashnumberoptionally

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

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

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

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

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

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

Items Array

NameTypeRequirementDescription
idstringrequiredProduct ID.
pricenumberrequiredCost per unit of product.
quantitynumberrequiredThe product quantity in the order.
statusstringoptionally

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_pricenumberoptionallyThe base price of the product.
discount_productnumberoptionallyDescribes the amount of discount (in money) applied to the product.
discount_couponnumberoptionallyDescribes the amount of discount (in money) applied to the product by using the discount coupon.
discount_bonusesnumberoptionallyDescribes how much of the product's value was paid by bonuses.
delivery_companystringoptionallyProduct-specific delivery company.
line_idstringoptionallyThe 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.
barcodestringoptionallyProduct barcode. If set, this property has priority over the "id" property when searching for a product of order in the order history.
cancel_reasonstringoptionallyAny description of the reason for returning the product.

API Response Code

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 RequestUnsuccessful authorization.

Request Example

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

Page Navigation



Related Pages

Copyright 2018-2024 PersonaClick