Conversions and Product catalog v2.0
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
It is highly recommended that you send multiple objects in one HTTP request. This API allows streaming using newline separated JSON format or ndjson (http://ndjson.org/)
- You may send up to 30 requests per second
- You may have up to 30 concurrent connections
- If you send many conversions/products/etc. in bulk, the upload speed will be limited to 30 conversions/products/etc. per second
- If you send 1 conversion per request you will be limited to 30 requests per second
- If you send 90 conversions in one request your upload will be completed in about 3 seconds
- If you send 40 requests, each with one conversion in the same second, 30 of them will be processed and 10 of them will be rejected
- If you send 3 requests, each with 100 conversions they will be completed in 10 seconds
- You can send up to 150 conversion items
Use the long format with timezone for passing ISO-8601 dates. The following formats are accepted:
- "2019-04-29T13:47:47.315Z"
- "2019-04-29T13:47:47Z"
- "2019-04-29T13:47:47.315+02:00"
- "2019-04-29T13:47:47+02:00"
Errors are always returned as an array of objects in the top-level "errors" property.
For bulk operations you may have "errors" and "data" properties at the same time since some objects may have errors while others may not. Bulk errors are aggregated which means there won't be an error for each instance of an error but one error for each type of error with the number of occurrences and some examples of line numbers or ids.
{
"errors": [
{
"code": "YOU_CAN_CHECK_THIS_IN_CODE",
"detail": "This explains the error",
"meta": {
"context_property_example": "value_example",
"error_count": 3,
"line_numbers": [34, 45],
"ids": [
"c9017b85-8016-4f13-88b4-18d57c67b866",
"12e0c3cb-7e8d-462f-9232-f7c61a900738"
]
}
}
]
"data": {
"accepted_object_count": 4,
"rejected_object_count": 3
}
}
Error objects have the following properties
Property | Type | Required | Description |
code | string | true | Always present and contains error code that can be checked programmatically |
detail | string | true | Human readable message that explains the problem. You should not check the value of this property programmatically because it may change |
meta | object | false | Error specific object that contains details about what generated the error |
Base URLs:
- HTTP Authentication, scheme: bearer Token will be provided by our support/consulting team
Code samples
POST https://api.commander1.com/v2/{siteId}/conversions/bulk HTTP/1.1
Host: api.commander1.com
Content-Type: application/x-ndjson
Accept: application/json
Authorization: Bearer NJtcKaoCYu...mGZDxRgMBMUw==
POST /conversions/bulkThis endpoint creates and updates conversions. Your request will be processed asynchronously. It can take up to 24 hours until the request is processed and updates are made in the database.
Body parameter
{"id":"db050bb1-810d-4420-a6fb-c1ce472a4ca9","user":{"user_email":"[email protected]"},"type":"offline","status":"in_progress","created":"2018-01-01T20:00:00.000+01:00","updated":"2018-01-01T20:00:00.000+01:00","acknowledged":true,"currency":"EUR","comment":"Package needs to be smaller than 30cm by 30cm","billing_address":{"country":"France","iso_country_code":"FR","country_code":"FRA","region":"Ile-de-France","locality":"Paris","postal_code":"75009","recipient":"Commanders Act","street_address":"3-5 Rue Saint-Georges","full_address":null,"label":"home","coordinates":{"latitude":48.857764,"longitude":2.33935}},"contact_address":{"country":"France","iso_country_code":"FR","country_code":"FRA","region":"Ile-de-France","locality":"Paris","postal_code":"75009","recipient":"Commanders Act","street_address":"3-5 Rue Saint-Georges","full_address":null,"label":"home","coordinates":{"latitude":48.857764,"longitude":2.33935}},"shipping_address":{"country":"France","iso_country_code":"FR","country_code":"FRA","region":"Ile-de-France","locality":"Paris","postal_code":"75009","recipient":"Commanders Act","street_address":"3-5 Rue Saint-Georges","full_address":null,"label":"home","coordinates":{"latitude":48.857764,"longitude":2.33935}},"shipping_provider":"UPS","shipping_tracking_code":"702c7a16-2c3d-4946-bb35-69ba540773f6","payment_method":"card","original_quantity":3,"cancelled_quantity":1,"returned_quantity":1,"exchanged_quantity":0,"final_quantity":1,"original_amount":30,"cancelled_amount":10,"returned_amount":10,"exchanged_amount":0,"shipping_amount":0,"discount_amount":0,"tax_amount":5,"final_amount":10,"custom":{"internal_reference":"fa34dc2","referer":"[email protected]","website_version":"2.4"},"conversion_items":[{"id":"68cd1310-4b7a-454c-99fb-2510f0e156ec","original_quantity":3,"cancelled_quantity":1,"returned_quantity":1,"exchanged_quantity":0,"final_quantity":1,"original_amount":30,"cancelled_amount":10,"returned_amount":10,"exchanged_amount":0,"final_amount":10,"price":10,"original_item":true,"custom":{"remarketing_campaign":"christmas_2018","time_to_checkout":"25 minutes","ab_testing_group":"3245fcda"},"product":{"id":"db050bb1-810d-4420-a6fb-c1ce472a4ca9","name":"Mug Commanders Act","description":"White stoneware mug with C-Handle is the perfect cup for any beverage","category_1":"Home","category_2":"Kitchen","category_3":"Accessories","category_4":"Containers","category_5":"Mugs","tags":["mugs","handle","white","brand"],"condition":"new","availability":"in_stock","availability_date":"2019-02-06T17:41:31.427+01:00","expiration_date":"2019-02-06T17:41:31.427+01:00","price":10,"sale_price":8,"currency":"EUR","image_link":"https://commandersact.com/images/shopping/mug_hi_res.jpg","link":"https://commandersact.com/shopping/mug","brand":"Commanders Act","width":6.4,"length":7.3,"height":9.5,"weight":80.7,"size":"medium","colors":["white","red"],"gtin":"134588842456789000","mpn":"134588842","custom":{"internal_category_id":721,"warehouse":"building B","box_barcode":1830135586179}}},{"id":"68cd1310-4b7a-454c-99fb-2510f0e156ec","original_quantity":3,"cancelled_quantity":1,"returned_quantity":1,"exchanged_quantity":0,"final_quantity":1,"original_amount":30,"cancelled_amount":10,"returned_amount":10,"exchanged_amount":0,"final_amount":10,"price":10,"original_item":true,"custom":{"remarketing_campaign":"christmas_2018","time_to_checkout":"25 minutes","ab_testing_group":"3245fcda"},"product":{"id":"db050bb1-810d-4420-a6fb-c1ce472a4ca9","name":"Mug Commanders Act","description":"White stoneware mug with C-Handle is the perfect cup for any beverage","category_1":"Home","category_2":"Kitchen","category_3":"Accessories","category_4":"Containers","category_5":"Mugs","tags":["mugs","handle","white","brand"],"condition":"new","availability":"in_stock","availability_date":"2019-02-06T17:41:31.427+01:00","expiration_date":"2019-02-06T17:41:31.427+01:00","price":10,"sale_price":8,"currency":"EUR","image_link":"https://commandersact.com/images/shopping/mug_hi_res.jpg","link":"https://commandersact.com/shopping/mug","brand":"Commanders Act","width":6.4,"length":7.3,"height":9.5,"weight":80.7,"size":"medium","colors":["white","red"],"gtin":"134588842456789000","mpn":"134588842","custom":{"internal_category_id":721,"warehouse":"building B","box_barcode":1830135586179}}}]}
{"id":"db050bb1-810d-4420-a6fb-c1ce472a4ca9","user":{"user_email":"[email protected]"},"type":"offline","status":"in_progress","created":"2018-01-01T20:00:00.000+01:00","updated":"2018-01-01T20:00:00.000+01:00","acknowledged":true,"currency":"EUR","comment":"Package needs to be smaller than 30cm by 30cm","billing_address":{"country":"France","iso_country_code":"FR","country_code":"FRA","region":"Ile-de-France","locality":"Paris","postal_code":"75009","recipient":"Commanders Act","street_address":"3-5 Rue Saint-Georges","full_address":null,"label":"home","coordinates":{"latitude":48.857764,"longitude":2.33935}},"contact_address":{"country":"France","iso_country_code":"FR","country_code":"FRA","region":"Ile-de-France","locality":"Paris","postal_code":"75009","recipient":"Commanders Act","street_address":"3-5 Rue Saint-Georges","full_address":null,"label":"home","coordinates":{"latitude":48.857764,"longitude":2.33935}},"shipping_address":{"country":"France","iso_country_code":"FR","country_code":"FRA","region":"Ile-de-France","locality":"Paris","postal_code":"75009","recipient":"Commanders Act","street_address":"3-5 Rue Saint-Georges","full_address":null,"label":"home","coordinates":{"latitude":48.857764,"longitude":2.33935}},"shipping_provider":"UPS","shipping_tracking_code":"702c7a16-2c3d-4946-bb35-69ba540773f6","payment_method":"card","original_quantity":3,"cancelled_quantity":1,"returned_quantity":1,"exchanged_quantity":0,"final_quantity":1,"original_amount":30,"cancelled_amount":10,"returned_amount":10,"exchanged_amount":0,"shipping_amount":0,"discount_amount":0,"tax_amount":5,"final_amount":10,"custom":{"internal_reference":"fa34dc2","referer":"[email protected]","website_version":"2.4"},"conversion_items":[{"id":"68cd1310-4b7a-454c-99fb-2510f0e156ec","original_quantity":3,"cancelled_quantity":1,"returned_quantity":1,"exchanged_quantity":0,"final_quantity":1,"original_amount":30,"cancelled_amount":10,"returned_amount":10,"exchanged_amount":0,"final_amount":10,"price":10,"original_item":true,"custom":{"remarketing_campaign":"christmas_2018","time_to_checkout":"25 minutes","ab_testing_group":"3245fcda"},"product":{"id":"db050bb1-810d-4420-a6fb-c1ce472a4ca9","name":"Mug Commanders Act","description":"White stoneware mug with C-Handle is the perfect cup for any beverage","category_1":"Home","category_2":"Kitchen","category_3":"Accessories","category_4":"Containers","category_5":"Mugs","tags":["mugs","handle","white","brand"],"condition":"new","availability":"in_stock","availability_date":"2019-02-06T17:41:31.427+01:00","expiration_date":"2019-02-06T17:41:31.427+01:00","price":10,"sale_price":8,"currency":"EUR","image_link":"https://commandersact.com/images/shopping/mug_hi_res.jpg","link":"https://commandersact.com/shopping/mug","brand":"Commanders Act","width":6.4,"length":7.3,"height":9.5,"weight":80.7,"size":"medium","colors":["white","red"],"gtin":"134588842456789000","mpn":"134588842","custom":{"internal_category_id":721,"warehouse":"building B","box_barcode":1830135586179}}},{"id":"68cd1310-4b7a-454c-99fb-2510f0e156ec","original_quantity":3,"cancelled_quantity":1,"returned_quantity":1,"exchanged_quantity":0,"final_quantity":1,"original_amount":30,"cancelled_amount":10,"returned_amount":10,"exchanged_amount":0,"final_amount":10,"price":10,"original_item":true,"custom":{"remarketing_campaign":"christmas_2018","time_to_checkout":"25 minutes","ab_testing_group":"3245fcda"},"product":{"id":"db050bb1-810d-4420-a6fb-c1ce472a4ca9","name":"Mug Commanders Act","description":"White stoneware mug with C-Handle is the perfect cup for any beverage","category_1":"Home","category_2":"Kitchen","category_3":"Accessories","category_4":"Containers","category_5":"Mugs","tags":["mugs","handle","white","brand"],"condition":"new","availability":"in_stock","availability_date":"2019-02-06T17:41:31.427+01:00","expiration_date":"2019-02-06T17:41:31.427+01:00","price":10,"sale_price":8,"currency":"EUR","image_link":"https://commandersact.com/images/shopping/mug_hi_res.jpg","link":"https://commandersact.com/shopping/mug","brand":"Commanders Act","width":6.4,"length":7.3,"height":9.5,"weight":80.7,"size":"medium","colors":["white","red"],"gtin":"134588842456789000","mpn":"134588842","custom":{"internal_category_id":721,"warehouse":"building B","box_barcode":1830135586179}}}]}
{"id":"db050bb1-810d-4420-a6fb-c1ce472a4ca9","user":{"user_email":"[email protected]"},"type":"offline","status":"in_progress","created":"2018-01-01T20:00:00.000+01:00","updated":"2018-01-01T20:00:00.000+01:00","acknowledged":true,"currency":"EUR","comment":"Package needs to be smaller than 30cm by 30cm","billing_address":{"country":"France","iso_country_code":"FR","country_code":"FRA","region":"Ile-de-France","locality":"Paris","postal_code":"75009","recipient":"Commanders Act","street_address":"3-5 Rue Saint-Georges","full_address":null,"label":"home","coordinates":{"latitude":48.857764,"longitude":2.33935}},"contact_address":{"country":"France","iso_country_code":"FR","country_code":"FRA","region":"Ile-de-France","locality":"Paris","postal_code":"75009","recipient":"Commanders Act","street_address":"3-5 Rue Saint-Georges","full_address":null,"label":"home","coordinates":{"latitude":48.857764,"longitude":2.33935}},"shipping_address":{"country":"France","iso_country_code":"FR","country_code":"FRA","region":"Ile-de-France","locality":"Paris","postal_code":"75009","recipient":"Commanders Act","street_address":"3-5 Rue Saint-Georges","full_address":null,"label":"home","coordinates":{"latitude":48.857764,"longitude":2.33935}},"shipping_provider":"UPS","shipping_tracking_code":"702c7a16-2c3d-4946-bb35-69ba540773f6","payment_method":"card","original_quantity":3,"cancelled_quantity":1,"returned_quantity":1,"exchanged_quantity":0,"final_quantity":1,"original_amount":30,"cancelled_amount":10,"returned_amount":10,"exchanged_amount":0,"shipping_amount":0,"discount_amount":0,"tax_amount":5,"final_amount":10,"custom":{"internal_reference":"fa34dc2","referer":"[email protected]","website_version":"2.4"},"conversion_items":[{"id":"68cd1310-4b7a-454c-99fb-2510f0e156ec","original_quantity":3,"cancelled_quantity":1,"returned_quantity":1,"exchanged_quantity":0,"final_quantity":1,"original_amount":30,"cancelled_amount":10,"returned_amount":10,"exchanged_amount":0,"final_amount":10,"price":10,"original_item":true,"custom":{"remarketing_campaign":"christmas_2018","time_to_checkout":"25 minutes","ab_testing_group":"3245fcda"},"product":{"id":"db050bb1-810d-4420-a6fb-c1ce472a4ca9","name":"Mug Commanders Act","description":"White stoneware mug with C-Handle is the perfect cup for any beverage","category_1":"Home","category_2":"Kitchen","category_3":"Accessories","category_4":"Containers","category_5":"Mugs","tags":["mugs","handle","white","brand"],"condition":"new","availability":"in_stock","availability_date":"2019-02-06T17:41:31.427+01:00","expiration_date":"2019-02-06T17:41:31.427+01:00","price":10,"sale_price":8,"currency":"EUR","image_link":"https://commandersact.com/images/shopping/mug_hi_res.jpg","link":"https://commandersact.com/shopping/mug","brand":"Commanders Act","width":6.4,"length":7.3,"height":9.5,"weight":80.7,"size":"medium","colors":["white","red"],"gtin":"134588842456789000","mpn":"134588842","custom":{"internal_category_id":721,"warehouse":"building B","box_barcode":1830135586179}}},{"id":"68cd1310-4b7a-454c-99fb-2510f0e156ec","original_quantity":3,"cancelled_quantity":1,"returned_quantity":1,"exchanged_quantity":0,"final_quantity":1,"original_amount":30,"cancelled_amount":10,"returned_amount":10,"exchanged_amount":0,"final_amount":10,"price":10,"original_item":true,"custom":{"remarketing_campaign":"christmas_2018","time_to_checkout":"25 minutes","ab_testing_group":"3245fcda"},"product":{"id":"db050bb1-810d-4420-a6fb-c1ce472a4ca9","name":"Mug Commanders Act","description":"White stoneware mug with C-Handle is the perfect cup for any beverage","category_1":"Home","category_2":"Kitchen","category_3":"Accessories","category_4":"Containers","category_5":"Mugs","tags":["mugs","handle","white","brand"],"condition":"new","availability":"in_stock","availability_date":"2019-02-06T17:41:31.427+01:00","expiration_date":"2019-02-06T17:41:31.427+01:00","price":10,"sale_price":8,"currency":"EUR","image_link":"https://commandersact.com/images/shopping/mug_hi_res.jpg","link":"https://commandersact.com/shopping/mug","brand":"Commanders Act","width":6.4,"length":7.3,"height":9.5,"weight":80.7,"size":"medium","colors":["white","red"],"gtin":"134588842456789000","mpn":"134588842","custom":{"internal_category_id":721,"warehouse":"building B","box_barcode":1830135586179}}}]}
Name | In | Type | Required | Description |
Authorization | header | string | true | Authorization token |
body | body | true | Conversions as newline delimited JSON strings |
Example responses
202 Response
{
"data": {
"accepted_object_count": 4,
"rejected_object_count": 0
}
}
400 Cannot parse nd-json line
{
"errors": [
{
"code": "PARSE_ERROR",
"detail": "Cannot parse nd-json"
}
],
"data": {}
}
400 Missing required property
{
"errors": [
{
"code": "MISSING_REQUIRED_PROPERTY",
"detail": "should have required property 'id'\n",
"meta": {
"line_numbers": [
34,
45
],
"error_count": 2,
"ids": [
"c9017b85-8016-4f13-88b4-18d57c67b866",
"12e0c3cb-7e8d-462f-9232-f7c61a900738"
]
}
}
],
"data": {
"accepted_object_count": 4,
"rejected_object_count": 2
}
}
400 Invalid property type
{
"errors": [
{
"code": "INVALID_PROPERTY_TYPE",
"detail": "\"original_amount\" property is not a number",
"meta": {
"property": "original_amount",
"line_numbers": [
34,
45
],
"error_count": 2,
"ids": [
"c9017b85-8016-4f13-88b4-18d57c67b866",
"12e0c3cb-7e8d-462f-9232-f7c61a900738"
]
}
}
],
"data": {
"accepted_object_count": 4,
"rejected_object_count": 2
}
}
400 Invalid property format
{
"errors": [
{
"code": "INVALID_PROPERTY_FORMAT",
"detail": "\"original_amount\" property is not a number",
"meta": {
"property": "original_amount",
"line_numbers": [
34,
45
],
"error_count": 2,
"ids": [
"c9017b85-8016-4f13-88b4-18d57c67b866",
"12e0c3cb-7e8d-462f-9232-f7c61a900738"
]
}
}
],
"data": {
"accepted_object_count": 4,
"rejected_object_count": 2
}
}
401 Authorization header is missing
{
"errors": [
{
"code": "MISSING_AUTHORIZATION_HEADER",
"detail": "The \"Authorization\" header is required"
}
]
}
401 Token type is missing
{
"errors": [
{
"code": "UNKNOWN_TOKEN_TYPE",
"detail": "The token type is missing"
}
]
}
401 The token type is invalid
{
"errors": [
{
"code": "INVALID_TOKEN_TYPE",
"detail": "The token type \"Bear\" is invalid. Expecting \"Bearer\" instead"
}
]
}
401 The provided token is unknown
{
"errors": [
{
"code": "UNKNOWN_TOKEN",
"detail": "The provided token is unknown. Please contact our support team [email protected]"
}
]
}
403 Response
{
"errors": [
{
"code": "SITE_ACCESS_FORBIDDEN",
"detail": "You cannot access this site"
}
]
}
Too Many Requests
{
"description": "You have too many open connections",
"errors": [
{
"code": "CONNECTION_LIMIT_REACHED",
"detail": "Your account is limited to 30 simultaneous connections"
}
]
}
{
"description": "You have reached the request limit",
"errors": [
{
"code": "REQUEST_LIMIT_REACHED",
"detail": "Your account is limited to 30 requests per second"
}
]
}
500 Response
{
"errors": [
{
"code": "SERVER_ERROR",
"detail": "An internal error occurred. Please contact our support team [email protected]"
}
]
}
Status | Meaning | Description | Schema |
202 | All objects are accepted for processing | None | |
400 | Cannot process request or part of the request due to client error | None | |
401 | Cannot identify the API caller | None | |
403 | API caller does not have access to this resource | None | |
429 | Too Many Requests | None | |
500 | Internal server error | None |
Code samples
POST https://api.commander1.com/v2/{siteId}/products/bulk HTTP/1.1
Host: api.commander1.com
Content-Type: application/x-ndjson
Authorization: Bearer NJtcKaoCYu...mGZDxRgMBMUw==
POST /products/bulkThis endpoint creates and updates products. Your request will be processed asynchronously. It can take up to 24 hours until the request is processed and updates are made in the database.
Body parameter
{"id":"db050bb1-810d-4420-a6fb-c1ce472a4ca9","name":"Mug Commanders Act","description":"White stoneware mug with C-Handle is the perfect cup for any beverage","category_1":"Home","category_2":"Kitchen","category_3":"Accessories","category_4":"Containers","category_5":"Mugs","tags":["mugs","handle","white","brand"],"condition":"new","availability":"in_stock","availability_date":"2019-02-06T17:41:31.427+01:00","expiration_date":"2019-02-06T17:41:31.427+01:00","price":10,"sale_price":8,"currency":"EUR","image_link":"https://commandersact.com/images/shopping/mug_hi_res.jpg","link":"https://commandersact.com/shopping/mug","brand":"Commanders Act","width":6.4,"length":7.3,"height":9.5,"weight":80.7,"size":"medium","colors":["white","red"],"gtin":"134588842456789000","mpn":"134588842","custom":{"internal_category_id":721,"warehouse":"building B","box_barcode":1830135586179}}
{"id":"db050bb1-810d-4420-a6fb-c1ce472a4ca9","name":"Mug Commanders Act","description":"White stoneware mug with C-Handle is the perfect cup for any beverage","category_1":"Home","category_2":"Kitchen","category_3":"Accessories","category_4":"Containers","category_5":"Mugs","tags":["mugs","handle","white","brand"],"condition":"new","availability":"in_stock","availability_date":"2019-02-06T17:41:31.427+01:00","expiration_date":"2019-02-06T17:41:31.427+01:00","price":10,"sale_price":8,"currency":"EUR","image_link":"https://commandersact.com/images/shopping/mug_hi_res.jpg","link":"https://commandersact.com/shopping/mug","brand":"Commanders Act","width":6.4,"length":7.3,"height":9.5,"weight":80.7,"size":"medium","colors":["white","red"],"gtin":"134588842456789000","mpn":"134588842","custom":{"internal_category_id":721,"warehouse":"building B","box_barcode":1830135586179}}
{"id":"db050bb1-810d-4420-a6fb-c1ce472a4ca9","name":"Mug Commanders Act","description":"White stoneware mug with C-Handle is the perfect cup for any beverage","category_1":"Home","category_2":"Kitchen","category_3":"Accessories","category_4":"Containers","category_5":"Mugs","tags":["mugs","handle","white","brand"],"condition":"new","availability":"in_stock","availability_date":"2019-02-06T17:41:31.427+01:00","expiration_date":"2019-02-06T17:41:31.427+01:00","price":10,"sale_price":8,"currency":"EUR","image_link":"https://commandersact.com/images/shopping/mug_hi_res.jpg","link":"https://commandersact.com/shopping/mug","brand":"Commanders Act","width":6.4,"length":7.3,"height":9.5,"weight":80.7,"size":"medium","colors":["white","red"],"gtin":"134588842456789000","mpn":"134588842","custom":{"internal_category_id":721,"warehouse":"building B","box_barcode":1830135586179}}
Name | In | Type | Required | Description |
Authorization | header | string | true | Authorization token |
body | body | true | Products as newline delimited JSON strings |
Status | Meaning | Description | Schema |
202 | Accepted | None | |
207 | Multi-Status | None | |
401 | Unauthorized | None | |
405 | Invalid input | None |
{
"id": "db050bb1-810d-4420-a6fb-c1ce472a4ca9",
"user": {
"email": "[email protected]",
"consent_categories": [1,3]
},
"type": "offline",
"status": "in_progress",
"created": "2018-01-01T20:00:00.000+01:00",
"updated": "2018-01-01T20:00:00.000+01:00",
"acknowledged": true,
"currency": "EUR",
"comment": "Package needs to be smaller than 30cm by 30cm",
"billing_address": {
"country": "France",
"iso_country_code": "FR",
"country_code": "FRA",
"region": "Ile-de-France",
"locality": "Paris",
"postal_code": "75009",
"recipient": "Commanders Act",
"street_address": "3-5 Rue Saint-Georges",
"full_address": null,
"label": "home",
"coordinates": {
"latitude": 48.857764,
"longitude": 2.33935
}
},
"contact_address": {
"country": "France",
"iso_country_code": "FR",
"country_code": "FRA",
"region": "Ile-de-France",
"locality": "Paris",
"postal_code": "75009",
"recipient": "Commanders Act",
"street_address": "3-5 Rue Saint-Georges",
"full_address": null,
"label": "home",
"coordinates": {
"latitude": 48.857764,
"longitude": 2.33935
}
},
"shipping_address": {
"country": "France",
"iso_country_code": "FR",
"country_code": "FRA",
"region": "Ile-de-France",
"locality": "Paris",
"postal_code": "75009",
"recipient": "Commanders Act",
"street_address": "3-5 Rue Saint-Georges",
"full_address": null,
"label": "home",
"coordinates": {
"latitude": 48.857764,
"longitude": 2.33935
}
},
"shipping_provider": "UPS",
"shipping_tracking_code": "702c7a16-2c3d-4946-bb35-69ba540773f6",
"payment_method": "card",
"original_quantity": 3,
"cancelled_quantity": 1,
"returned_quantity": 1,
"exchanged_quantity": 0,
"final_quantity": 1,
"original_amount": 30,
"cancelled_amount": 10,
"returned_amount": 10,
"exchanged_amount": 0,
"shipping_amount": 0,
"discount_amount": 0,
"tax_amount": 5,
"final_amount": 10,
"custom": {
"internal_reference": "fa34dc2",
"referer": "[email protected]",
"website_version": "2.4"
},
"conversion_items": [
{
"id": "68cd1310-4b7a-454c-99fb-2510f0e156ec",
"original_quantity": 3,
"cancelled_quantity": 1,
"returned_quantity": 1,
"exchanged_quantity": 0,
"final_quantity": 1,
"original_amount": 30,
"cancelled_amount": 10,
"returned_amount": 10,
"exchanged_amount": 0,
"final_amount": 10,
"price": 10,
"original_item": true,
"custom": {
"remarketing_campaign": "christmas_2018",
"time_to_checkout": "25 minutes",
"ab_testing_group": "3245fcda"
},
"product": {
"id": "db050bb1-810d-4420-a6fb-c1ce472a4ca9",
"name": "Mug Commanders Act",
"description": "White stoneware mug with C-Handle is the perfect cup for any beverage",
"category_1": "Home",
"category_2": "Kitchen",
"category_3": "Accessories",
"category_4": "Containers",
"category_5": "Mugs",
"tags": [
"mugs",
"handle",
"white",
"brand"
],
"condition": "new",
"availability": "in_stock",
"availability_date": "2019-02-06T17:41:31.427+01:00",
"expiration_date": "2019-02-06T17:41:31.427+01:00",
"price": 10,
"sale_price": 8,
"currency": "EUR",
"image_link": "https://commandersact.com/images/shopping/mug_hi_res.jpg",
"link": "https://commandersact.com/shopping/mug",
"brand": "Commanders Act",
"width": 6.4,
"length": 7.3,
"height": 9.5,
"weight": 80.7,
"size": "medium",
"colors": [
"white",
"red"
],
"gtin": "134588842456789000",
"mpn": "134588842",
"custom": {
"internal_category_id": 721,
"warehouse": "building B",
"box_barcode": 1830135586179
}
}
},
{
"id": "68cd1310-4b7a-454c-99fb-2510f0e156ec",
"original_quantity": 3,
"cancelled_quantity": 1,
"returned_quantity": 1,
"exchanged_quantity": 0,
"final_quantity": 1,
"original_amount": 30,
"cancelled_amount": 10,
"returned_amount": 10,
"exchanged_amount": 0,
"final_amount": 10,
"price": 10,
"original_item": true,
"custom": {
"remarketing_campaign": "christmas_2018",
"time_to_checkout": "25 minutes",
"ab_testing_group": "3245fcda"
},
"product": {
"id": "db050bb1-810d-4420-a6fb-c1ce472a4ca9",
"name": "Mug Commanders Act",
"description": "White stoneware mug with C-Handle is the perfect cup for any beverage",
"category_1": "Home",
"category_2": "Kitchen",
"category_3": "Accessories",
"category_4": "Containers",
"category_5": "Mugs",
"tags": [
"mugs",
"handle",
"white",
"brand"
],
"condition": "new",
"availability": "in_stock",
"availability_date": "2019-02-06T17:41:31.427+01:00",
"expiration_date": "2019-02-06T17:41:31.427+01:00",
"price": 10,
"sale_price": 8,
"currency": "EUR",
"image_link": "https://commandersact.com/images/shopping/mug_hi_res.jpg",
"link": "https://commandersact.com/shopping/mug",
"brand": "Commanders Act",
"width": 6.4,
"length": 7.3,
"height": 9.5,
"weight": 80.7,
"size": "medium",
"colors": [
"white",
"red"
],
"gtin": "134588842456789000",
"mpn": "134588842",
"custom": {
"internal_category_id": 721,
"warehouse": "building B",
"box_barcode": 1830135586179
}
}
}
]
}
It is recommended to use as many fields as you can in order to be able to build good segments with advanced conditions
Name | Type | Required | Restrictions | Description |
id | string(1-50) | true | none | Conversion id. Used as key for updates |
user | object | true | none | All properties that you add here will be used as conditions for matching users in our database. You must ensure that values used inside these properties are unique. Use same property names as those defined in variables interface for the user. |
» user.email | string(1-250) | false | none | Email of the user |
»user.consent_categories | string | false | none | Consent categories of the user, to be allowed to share conversions with partners |
type | string(1-250) | true | none | Type of conversion (online, offline, call etc.) |
status | string | true | none | Status of your conversion (see list of possible values below). Conversions with status "pending" are not included in default sum and counts aggregated on a user. |
created | string(ISO-8601) | true | none | Time when conversion occurred. See "Date formats" section above for a list of allowed formats. |
updated | string(ISO-8601) | false | none | Time when conversion was updated. See "Date formats" section above for a list of allowed formats. |
acknowledged | boolean | false | none | Set to true if conversion was acknowledged |
currency | string(ISO-4217) | true | none | Currency |
comment | string(1-250) | false | none | Comment of the buyer |
billing_address | false | none | It is recommended to use as many fields as you can in order to be able to build good segments with advanced conditions | |
contact_address | false | none | It is recommended to use as many fields as you can in order to be able to build good segments with advanced conditions | |
shipping_address | false | none | It is recommended to use as many fields as you can in order to be able to build good segments with advanced conditions | |
shipping_provider | string(1-250) | false | none | Shipping provider |
shipping_tracking_code | string(1-250) | false | none | Shipping tracking code |
payment_method | string | false | none | Payment method type (see list of possible values below) |
payment_provider | string | false | none | Payment provider used for this transaction |
original_quantity | float | false | read-only | Sum of all articles in the original conversion (CALCULATED) |
cancelled_quantity | float | false | read-only | Quantity of cancelled articles in the conversion (CALCULATED) |
returned_quantity | float | false | read-only | Quantity of returned articles in the conversion (CALCULATED) |
exchanged_quantity | float | false | read-only | Quantity of exchanged articles in the conversion (CALCULATED) |
final_quantity | float | false | read-only | Quantity of articles in final transaction for this conversion (original_quantity - cancelled_quantity - returned_quantity - exchanged_quantity) (CALCULATED) |
original_amount | float | false | write-once | Original amount for this conversion (shipping price and taxes included) |
cancelled_amount | float | false | none | Cancelled amount for this conversion |
returned_amount | float | false | none | Returned amount for this conversion |
exchanged_amount | float | false | none | Exchanged amount for this conversion |
shipping_amount | float | false | none | Shipping amount for this conversion |
discount_amount | float | false | none | Discount amount for this conversion |
tax_amount | float | false | none | Tax amount for this conversion |
final_amount | float | false | none | Final amount for this conversion after returns, exchanges, cancellations etc. (shipping price and taxes included). This represents the overall transaction amount between the buyer and the seller |
custom | object | false | none | Object containing custom properties |
conversion_items | true | none | List of products in the conversion + their own attributes. You cannot have the same product twice inside a conversion unless you provide a conversion item id |
Enumerated Values
Property | Value |
status | canceled |
status | delivered |
status | in_progress |
status | partially_delivered |
status | partially_returned |
status | partially_shipped |
status | pending_shipment |
status | returned |
status | shipped |
status | pending |
payment_method | by_bank_transfer_in_advance |
payment_method | by_invoice |
payment_method | card |
payment_method | check_in_advance |
payment_method | cod |
payment_method | coupon |
payment_method | direct_debit |
payment_method | online_payment_system |
payment_method | other |
{
"id": "68cd1310-4b7a-454c-99fb-2510f0e156ec",
"original_quantity": 3,
"cancelled_quantity": 1,
"returned_quantity": 1,
"exchanged_quantity": 0,
"final_quantity": 1,
"original_amount": 30,
"cancelled_amount": 10,
"returned_amount": 10,
"exchanged_amount": 0,
"final_amount": 10,
"price": 10,
"original_item": true,
"custom": {
"remarketing_campaign": "christmas_2018",
"time_to_checkout": "25 minutes",
"ab_testing_group": "3245fcda"
},
"product": {
"id": "db050bb1-810d-4420-a6fb-c1ce472a4ca9",
"name": "Mug Commanders Act",
"description": "White stoneware mug with C-Handle is the perfect cup for any beverage",
"category_1": "Home",
"category_2": "Kitchen",
"category_3": "Accessories",
"category_4": "Containers",
"category_5": "Mugs",
"tags": [
"mugs",
"handle",
"white",
"brand"
],
"condition": "new",
"availability": "in_stock",
"availability_date": "2019-02-06T17:41:31.427+01:00",
"expiration_date": "2019-02-06T17:41:31.427+01:00",
"price": 10,
"sale_price": 8,
"currency": "EUR",
"image_link": "https://commandersact.com/images/shopping/mug_hi_res.jpg",
"link": "https://commandersact.com/shopping/mug",
"brand": "Commanders Act",
"width": 6.4,
"length": 7.3,
"height": 9.5,
"weight": 80.7,
"size": "medium",
"colors": [
"white",
"red"
],
"gtin": "134588842456789000",
"mpn": "134588842",
"custom": {
"internal_category_id": 721,
"warehouse": "building B",
"box_barcode": 1830135586179
}
}
}
It is recommended to use as many fields as you can in order to be able to build good segments with advanced conditions
Name | Type | Required | Restrictions | Description |
id | string | true | none | Id of this item in the conversion. This id is required. If you don't have an item id in your database and the same product id cannot repeat within a conversion you can use the product id as value. This field is used for identifying the item in updates. |
original_quantity | float | true | none | Quantity of items in the original conversion |
cancelled_quantity | float | false | none | Quantity of cancelled items |
returned_quantity | float | false | none | Quantity of returned items |
exchanged_quantity | float | false | none | Quantity of exchanged items |
final_quantity | float | false | none | Quantity of items in final transaction (original_quantity - cancelled_quantity - returned_quantity - exchanged_quantity) |
original_amount | float | false | none | Original amount for this item |
cancelled_amount | float |