Import Ecomm events

Using S2S API, you can send Ecomm events that occurred off-site. For example, a status change in the order management system, or a payment made through the CRM system.

You can also use S2S API to transfer data on orders made in iOS and Android application.

For details about website event transfer, refer to the Ecommerce section

Methods

To send Ecommerce events to the MyTracker server, use the following methods:

order to send one event;
orderBatch to send several events at once.

Uploaded events will be added to the project data and will appear in MyTracker reports within 4 hours.

order

Request format: https://tracker-s2s.my.com/v1/order/?idApp=XXX

Required parameters: event and product parameters, and also the user and/or device ID to which the event will be related:

For websites: customUserId and/or lvid
For mobile apps: customUserId and/or instanceId, gaid, appSetId, androidId, idfa, iosVendorId

orderBatch

Request format: https://tracker-s2s.my.com/v1/orderBatch/?idApp=XXX

Required parameters:

Name	Description	Type	Example
	One parameter without a name. It's an array, through which you can pass parameters from the `order` method. If validation rules are broken in at least one set of parameters, the server will return the error	Array. Maximum size 20	[ {"order_id": "000919", "status":"ADD", "items":[{"item_id": "00912", "item_name":"Apple", "quantity": "6"}]}, {"order_id": "000930", "status":"PAY", "items":[{"item_id": "00912", "item_name":"Apple", "quantity": "6"}]} ]

Parameters

All parameters are passed in the request body in JSON format.

Limit on the maximum size of imported data — 10Kb.

Event parameters

Name	Description	Type	Example
order_id*	Unique order number	String	"order_id":"000919"
status	Order action: ADD (product adding) PAY (payment for product, default value) CANCEL (canceling an unpaid product) REFUND (return of paid product) ADD and PAY correspond to the mt_order event in the dataLayer. CANCEL and REFUND correspond to the mt_refund event in the dataLayer.	String	"status":"PAY"
currency_code	Three-letter ISO 4217 currency code. Project currency by default.	String	"currency_code":"USD"
action_id	Unique action number within the order	String	"action_id":"119029"
action_ts	Event time on the client server (timestamp)	String	"action_ts":"1577191920"
coupon	The name or coupon code associated with the order	String	"coupon":"two-for-one"
items*	Array with the product description	Array	[ {"item_id": "00912", "item_name":"Apple", "quantity": "6"}, {"item_id": "00920", "item_name":"Apple", "quantity": "4"} ]

* — required parameters

Product parameters

Name	Description	Type	Example
item_id*	The ID of the product	String	"item_id":"00912"
item_name*	The name of the product. Might not be unique and change.	String	"item_name":"Apple"
affiliation	The supplying company or store to which the product belongs	String	"affiliation":"Gardens"
price	The monetary value of the product	Number	"price":"11.90"
discount	The monetary discount value associated with the product	Number	"discount":"2"
coupon	The name or coupon code associated with the product	String	"coupon":"two-for-one"
tax	Tax cost associated with the product. Value from 1 to 100, in percent.	Number	"tax":"20"
index	Product position in the list	Integer	"index":"1"
item_brand	The brand of the product	String	"item_brand":"Honey Crisp"
item_variant	A variation of the product	String	"item_variant":"Green"
item_list_id	The ID of the list in which the product was presented to the user	String	"item_list_id":"5"
item_list_name	The name of the list in which the product was presented to the user	String	"item_list_name":"Fruits"
item_category1	One of the categories to which the product belongs	String	"item_category1":"Foodstuffs"
item_category2	One of the categories to which the product belongs	String	"item_category2":"Fruits"
item_category3	One of the categories to which the product belongs	String	"item_category3":"Apples"
item_category4	One of the categories to which the product belongs	String	"item_category4":"Sweet"
location_id	The identifier or name of the product location, store, pick-up point, etc.	String	"location_id":"Oregon"
quantity	The number of product units	Integer	"quantity":"3"

* — required parameters

S2S API parameters

Name	Description	Type	Example
Common
eventTimestamp	Event time	Number, minimum value 946674000, maximum value 4294967295. By default, timestamp of receiving the event	"eventTimestamp":"1577191920"
customUserId	User identifier	String, maximum size 1024	"customUserId":"1234"
ipv4	ipv4 address	String, maximum size 15	"ipv4":"125.125.125.125"
ipv6	ipv6 address	String, maximum size 45	"ipv6":"2001:0db8:85a3:0000:0000:8a2e:0370:7334"
idGender	Gender	Number, possible values: 0 — unknown 1 — man 2 — woman	"idGender":"1"
age	Age	Number, maximum value 128	"age":"38"
connectionType	Connection type	Number, possible values: 0 — unknown 1 — mobile 2 — wi-fi By default, 0	"connectionType":"1"
bluetoothEnabled	Bluetooth	Number, possible values: 0 — unknown 1 — on 2 — off By default, 0	"bluetoothEnabled":"2"
For mobile apps
instanceId	S2S device identifier	String, number of symbols 36	"instanceId":"00000000-0000-0000-0000-000000000000"
adTrackingEnabled	Tracking permission	Number, possible values: 1 — on 0 — off By default, 1	"adTrackingEnabled":"0"
iOS
idfa	iOS advertising identifier	String, number of symbols 36	"idfa":"00000000-0000-0000-0000-000000000000"
iosVendorId	iOS vendor identifier	String, number of symbols 36	"iosVendorId":"00000000-0000-0000-0000-000000000000"
Android
gaid	Android advertising identifier (advertisingId)	String, number of symbols 36	"gaid":"00000000-0000-0000-0000-000000000000"
appSetId	Android identifier, unique within a Google Play developer account	String, number of symbols 36	"appSetId":"00000000-0000-0000-0000-000000000000"
androidId	Android identifier	String, number of symbols 16	"androidId":"000000000000000"
For websites
lvid	S2S device identifier	String, number of symbols 32	"lvid":"00000000000000000000000000000000"
adBlocker	Ad blocker	Number, possible values: 1 — on 0 — off By default, 0	"adBlocker":"0"
userAgent	User-Agent	String, maximum size 2048	"userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.87 Safari/537.36"

Example query

Examples of sending different events:

Event	Parameters
Order placement with payment	"status": "PAY" Send an event when the user has placed and fully paid for an order on the site.
Order placement without payment	"status": "ADD" Send an event when the user has placed a pending payment order. For example, the user will pay for the order at the pick-up point or with the courier.
Full or partial payment of the order	Payment of the order implies that the event in ADD status was sent before it. Possible chain of action: ADD→PAY. "status": "PAY" "order_id": "previously placed order number" "items": "description of paid products" Send an event when a user has paid for the product.
Adding a product to an order	Adding a product implies that the event with the same `order_id` was sent before it. Possible chains of action: ADD→ADD, ADD→PAY, PAY→ADD, PAY→PAY. "status": "PAY" if products are paid for "status": "ADD" if products are not paid for "order_id": "previously placed order number" "items": "description of added products" Send an event when a user has added a product.
Full or partial cancellation of an unpaid order	Canceling an order implies that the event with the same `order_id` was sent before it. Possible chains of action: ADD→CANCEL, PAY→CANCEL. "status": "CANCEL" "order_id": "previously placed order number" "items": "description of canceled products" Send an event when a user has canceled or partially canceled an order, or, for example, when an order reserve has expired.
Full or partial cancellation of a paid order	Canceling a paid order implies that the event with the same `order_id` was sent before it. Possible chains of action: PAY→REFUND, CANCEL→REFUND. "status": "REFUND" "order_id": "previously paid order number" "items": "description of returned products" Send the event when the user has completed the return.

Order placement without payment

curl --location 'https://tracker-s2s.my.com/v1/order/?idApp=001' \
--header 'Content-Type: application/json' \
--header 'Authorization: aaaaaAAAaaa01aaaaaaa1aaAAA11a' \
--data '{
    "lvid": "00000000000000000000000000000000",
    "order": {
        "order_id": "000919",
        "currency_code": "USD",
        "status": "ADD",
        "action_ts": "1709317326",
        "coupon": "two-for-one",
        "items": [
            {
                "item_id": "00912",
                "item_name": "Apple",
                "affilation": "Gardens",
                "item_list_id": "5",
                "item_list_name": "Fruits",
                "price": "11.90",
                "discount": "2",
                "coupon": " two-for-one",
                "tax": "20",
                "index": "1",
                "item_brand": "Honey Crisp",
                "item_variant": "Green",
                "item_category1": "Foodstuffs",
                "item_category2": "Fruits",
                "item_category3": "Apples",
                "item_category4": "Sweet",
                "location_id": "Oregon",
                "quantity": "5"
            }
        ]
    }
}'

Partial payment of the order

curl --location 'https://tracker-s2s.my.com/v1/order/?idApp=001' \
--header 'Content-Type: application/json' \
--header 'Authorization: aaaaaAAAaaa01aaaaaaa1aaAAA11a' \
--data '{
    "lvid": "00000000000000000000000000000000",
    "order": {
        "order_id": "000919",
        "currency_code": "USD",
        "status": "PAY",
        "action_ts": "1709478868",
        "coupon": "two-for-one",
        "items": [
            {
                "item_id": "00912",
                "item_name": "Apple",
                "affilation": "Gardens",
                "item_list_id": "5",
                "item_list_name": "Fruits",
                "price": "11.90",
                "discount": "2",
                "coupon": " two-for-one",
                "tax": "20",
                "index": "1",
                "item_brand": "Honey Crisp",
                "item_variant": "Green",
                "item_category1": "Foodstuffs",
                "item_category2": "Fruits",
                "item_category3": "Apples",
                "item_category4": "Sweet",
                "location_id": "Oregon",
                "quantity": "4"
            }
        ]
    }
}'

Partial cancellation of an unpaid order

curl --location 'https://tracker-s2s.my.com/v1/order/?idApp=001' \
--header 'Content-Type: application/json' \
--header 'Authorization: aaaaaAAAaaa01aaaaaaa1aaAAA11a' \
--data '{
    "lvid": "00000000000000000000000000000000",
    "order": {
        "order_id": "000919",
        "currency_code": "USD",
        "status": "CANCEL",
        "action_ts": "1709479828",
        "coupon": "two-for-one",
        "items": [
            {
                "item_id": "00912",
                "item_name": "Apple",
                "affilation": "Gardens",
                "item_list_id": "5",
                "item_list_name": "Fruits",
                "price": "11.90",
                "discount": "2",
                "coupon": " two-for-one",
                "tax": "20",
                "index": "1",
                "item_brand": "Honey Crisp",
                "item_variant": "Green",
                "item_category1": "Foodstuffs",
                "item_category2": "Fruits",
                "item_category3": "Apples",
                "item_category4": "Sweet",
                "location_id": "Oregon",
                "quantity": "1"
            }
        ]
    }
}'

Partial refund of a paid order

curl --location 'https://tracker-s2s.my.com/v1/order/?idApp=001' \
--header 'Content-Type: application/json' \
--header 'Authorization: aaaaaAAAaaa01aaaaaaa1aaAAA11a' \
--data '{
    "lvid": "00000000000000000000000000000000",
    "order": {
        "order_id": "000919",
        "currency_code": "USD",
        "status": "REFUND",
        "action_ts": "1709652628",
        "coupon": "two-for-one",
        "items": [
            {
                "item_id": "00912",
                "item_name": "Apple",
                "affilation": "Gardens",
                "item_list_id": "5",
                "item_list_name": "Fruits",
                "price": "11.90",
                "discount": "2",
                "coupon": " two-for-one",
                "tax": "20",
                "index": "1",
                "item_brand": "Honey Crisp",
                "item_variant": "Green",
                "item_category1": "Foodstuffs",
                "item_category2": "Fruits",
                "item_category3": "Apples",
                "item_category4": "Sweet",
                "location_id": "Oregon",
                "quantity": "1"
            }
        ]
    }
}'

Status codes

Code	Response	Description
200	{"message": "ОK"}	The request was successfully processed
400	{"error": "Bad Request"}	Request error, parameters not validated
403	{"error": "Forbidden"}	The token has not been validated or is not suitable for the application
400	{"error": "Empty post data"}	Empty request body
400	{"error": "Bad json"}	Passed an invalid JSON file in the request body
400	{"error": "Bad api version"}	Unsupported API version
404	{"error": "Method not found"}	API method not found
500	{"error": "Internal Server Error"}	Internal API error. Try to repeat the request later

Was this article helpful?