API Conversions and Product catalog

Commanders Act Data API v2.0.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/)

Rate-limits

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

Rate limiting examples

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

Limitations

You can send up to 150 conversion items

Date formats

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

Errors are always returned as an array of objects in the top-level "errors" property.

Errors in bulk operations

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 object

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

Authentication

HTTP Authentication, scheme: bearer Token will be provided by our support/consulting team

Default

Upsert conversions

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/bulk

This endpoint creates and updates conversions. Your request will be processed asynchronously. It can take up to 1 hour until the request is processed and updates are made in the database.

Body parameter

{"id":"db050bb1-810d-4420-a6fb-c1ce472a4ca9","user":{"user_email":"user@example.com"},"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":"user@example.com","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":"user@example.com"},"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":"user@example.com","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":"user@example.com"},"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":"user@example.com","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}}}]}

Parameters

Name

Type

Required

Description

Authorization

header

string

true

Authorization token

overwrite

query

boolean

false

Determines if conversions should be fully replaced (true) or partially updated (false - default).

body

true

Conversions as newline delimited JSON strings

Overwrite Parameter Behavior

The overwrite url parameter determines how conversions are processed when an existing id is found:

false (default):
- Only the specified fields will be updated.
- Unspecified fields will retain their existing values.
true:
- The existing conversion will be fully replaced with the new data provided.

If you need to replace a conversion entirely, set overwrite=true.

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 support@commandersact.com"
    }
  ]
}

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 support@commandersact.com"
    }
  ]
}

Responses

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

Response Schema

Upsert products

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/bulk

This 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}}

Parameters

Name

Type

Required

Description

Authorization

header

string

true

Authorization token

body

true

Products as newline delimited JSON strings

Responses

Status

Meaning

Description

Schema

202

Accepted

None

207

Multi-Status

None

401

Unauthorized

None

405

Invalid input

None

Schemas

Conversion

{
  "id": "db050bb1-810d-4420-a6fb-c1ce472a4ca9",
  "user": {
    "email": "user@example.com", 
    "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": "user@example.com",
    "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

Properties

Name

Type

Required

Restrictions

Description

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

ConversionItem

{
  "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",