/track/v2/projects/{projectToken}/batch

Executes a batch of commands.

Use this route when you want to execute several commands from the Tracking API group at once. You can send up to 50 commands in a batch comprising of multiple update customer properties and add event for one or more customers at once.

However, this should not be used to run high-volume imports. This is considered bad practice and will be blocked.

Definition

Authorization

In this API call you can use any of these 2 types of authorization accesses:

Available access types

Permissions needed

Public access

Customer properties > Set
and/or
Events > Set

Private access

Customer properties > Set
and/or
Events > Set

Read more about:

Path parameters

Parameter

Type

Description

Required

projectToken

string

The ID of your project

required

Body parameters

Parameter

Type

Description

Required

commands

array of objects

The list of Commands you want to submit. See definition below.

At least 1 required

Commands object attributes

Parameter

Type

Description

Required

name

string

Route name of the command: customers, customers/events.

Required

data

object

Command payload, same format as if tracked individually.

Required

command_id

string

Identification of command will be returned in response with success status. Used to match errors with original command.

Optional

Headers

Headers

Type

Description

Required

authorization

string

Read more on how to authenticate in the Authentication section.

required

content-type

string

application/json

required

Additional payload and response examples

{
    "commands": [
        {"name": "system/time"},
        {
        "name": "customers",
        "command_id": "abc",
        "data": {
            "customer_ids": {
                "registered": "[email protected]"
            },
            "properties": {
                "first_name": "Marian",
                "last_name": "Galik"
            }
        }
    },
    {
        "name": "customers/events",
        "data": {
            "customer_ids": {
            "registered": "[email protected]"
        },
            "event_type": "purchase",
            "timestamp": 123456.78, 
            "properties": {
            "total_price": 1234.50,
            "voucher_code": "KA54-548C-TEST"
            }
        }
    }
    ]
}
{
    "results": [
        {
            "success": false,
            "errors": [
                "At least one id should be specified."
            ],
            "command_id": "my command 1"
        },
        {
            "success": false,
            "errors": [
                "Field 'event_type' is required."
            ],
            "command_id": "my command 2"
        }
    ],
    "start_time": 1614948195.829981,
    "end_time": 1614948195.8301175,
    "success": true
}

Limitations

Message size

  • Each command size must be less than 800 KBytes
  • The value of every event/customer property must be less than 16 KBytes

In general, all routes mentioned in the Tracking API section can be used as part of the command. However, the maximum allowed size of a single request is 50 commands.

Error handling

Some specific errors that you might encounter with this request involve:

Error

Description

HTTP 200 with result success = false

One of the commands in the request was not processed. Commands with result success = true have been accepted. Retrying the failed command will not help, you need to look for a mistake in that specific failed command, the rest of the request was successful.

See example response above.

Language
Click Try It! to start a request and see the response here!