The Zaius SDK for PHP. Validated for use in zaius-magento-2, users in custom environments are encouraged to test and validate thoroughly (and note any issues via the GitHub issue tracker).

1.0.1 2019-12-11 17:44 UTC


Getting Started

The Zaius SDK provides a programmatic interface for the Zaius API as documented at .

To get started, include the library in your project:

composer require zaius/zaius_sdk

You can get an instance of the Zaius client using:

$zaiusClient = new \ZaiusSDK\ZaiusClient($apiKey);

The API key can be obtained from your Zaius account at . Click on the "Private" tab and use the private API key.

Available methods

Customer management

Create/update a customer

The method takes in a single array with the customer object or an array of customer objects


$profile = array();
$profile['email'] = '';
$ret = $zaiusClient->postCustomer($profile);

Get a customer

This method takes in a filter array with the following possible keys:

  • email
  • vuid
  • customer_id

Note that you need to pass only one of the above. Also, the API supports only exact matches for each field.


$filter = ['email'=>''];
$profile = $zaiusClient->getCustomer($filter);


Post an event

Posts an event. The event array object method must have the following keys:

  • type - the type of the event (i.e. product)
  • action - the event's action (i.e. add_to_cart)
  • identifiers - an array with the identifiers. Valid keys are vuid and email
  • data - an array with the event-specific data. The full list of the supported values is available at

You can pass an array of events for bulk upload.


$event = array();
$event['type'] = 'test';
$event['action'] = 'test';
$event['identifiers'] = ['vuid'=>'test'];
$event['data'] = ['a'=>'b'];
$ret = $zaiusClient->postEvent($event);

List management

Create a list

Creates a list with the given name.


$list = array();
$list['name'] = uniqid();


Get all lists

Returns all lists.


$lists = $zaiusClient->getLists();

Update a list

Updates a list's name. The method expects the following parameters:

  • $listId - the ID of the list to change (get it with a getLists() call)
  • $newName - the new name for the list


$zaiusClient->changeListName('madison_island_newsletter','Renamed list');

Subscription management

Get subscriptions

Gets subscriptions based on a filter. The lists of accepted filters is available at .


$filters = ['email'=>''];
$subscriptions = $zaiusClient->getSubscriptions($filters);

Update subscription

Updates a subscription. The subscription array can have three keys:

  • list_id (optional) - the list for which to update the subscription
  • email - the email to update the subscription for
  • subscribed - true/false - whether to subscribe or unsubscribe the user

The method also supports passing an array of subscriptions for bulk updates.


$subscription = array();
$subscription['list_id'] = 'zaius_all';
$subscription['email'] = '';
$subscription['subscribed'] = true;

$ret = $zaiusClient->updateSubscription($subscription);

Update channel opt-in

Updates a subscription. Parameters:

  • optedIn - true/false
  • email - email address




Export all objects

Exports all objects. Parameters:

  • objects - array with objects type to export, i.e. array('orders','products'). Leave empty to export all object types
  • format - one of csv, parquet. Defaults to csv
  • delimiter - one of comma,tab, pipe. Defaults to comma.



Export filtered objects

Export objects given a filter.




Get the export status

Gets the status of an export. Parameters:

  • exportId - the export id



Schema API

Get all available objects

Returns an array with all available objects schemas.



Get object schema

Returns the schema for the specified object.


  • objectType - a valid object type. Get all object types with the getObjects() method



Create a new object type

Creates a new object type. Parameters:

  • object (unique) id
  • object name
  • alias
  • field definition array
  • relation definition array


$fields =  [
        'name' => 'object_id',
        "display_name"=> "New Object Identifier",
        "type"=> "string",
        "primary"=> true
        "name"=> "another_field",
        "display_name"=> "Another Fields",
        "type"=> "string"
        "name"=> "child_id",
        "display_name"=> "Child Identifier",
        "type"=> "number"

$relations = [

$zaiusClient->createObjectSchema('test_objects', 'Test Object', 'test_object', $fields, $relations);

Get an object's fields

Gets the fields for an object. Parameters:

  • object id



Create a new field for an object

Creates a new field for an object. Parameters:

  • object id
  • field id
  • field type
  • field name
  • field description


$zaiusClient->createObjectField('products','test_field','string','Test field','Test description');

Get all object's relations

Gets all relations for an object. Parameters:

  • object id



Posting objects

Post a product

$product = array();
$product['name'] = "Test product";
$product['sku'] = 'test-sku';
$product['product_id'] = 32;

$ret = $zaiusClient->postProduct($product);

This method also supports passing an array of products for bulk updates.

Post a customer

$profile = array();
$profile['email'] = '';
$ret = $zaiusClient->postCustomer($profile);

This method also supports passing an array of customers for bulk updates.

Post an order

$order = array();
$order['name'] = "Test customer";
$order['order_id'] = '11111';
$order['total'] = 32;
$order['items'] = [[

$ret = $zaiusClient->postOrder($order);

This method also supports passing an array of orders for bulk updates.

Posting custom objects

Creates (or updates) an object. Parameters:

  • object id
  • array with the object data. Must include all required fields per the object's schema.

This method supports passing an array of objects for bulk updates.


$zaiusClient->postObject('products',['product_id'=>33,'name'=>'test product']);

Bulk upload objects to S3

The S3 client can be obtained from the Zaius Client:

$zaiusClient = new \ZaiusSDK\ZaiusClient($apiKey);
$s3Client = $zaiusClient->getS3Client(ZAIUS_TRACKER_ID,ZAIUS_S3_KEY_ID,ZAIUS_S3_SECRET);

To get the needed keys, check


$event1 = array();
$event1['type'] = 'product';
$event1['action'] = 'addtocart';
$event1['identifiers'] = ['customer_id'=>99];
$event1['data'] = ['hostname'=>'','page'=>'Bar'];

$event2 = array();
$event2['type'] = 'product';
$event2['action'] = 'addtocart';
$event2['identifiers'] = ['customer_id'=>99];
$event2['data'] = ['hostname'=>'','page'=>'Foo'];

$events = [$event1,$event2];



$product1 = array();
$product1['product_id'] = 1;
$product1['sku'] = '1234';
$product1['name'] = "Planet of the Apes";
$product1['category'] = 'Books';

$product2 = array();
$product2['product_id'] = 2;
$product2['sku'] = '4321';
$product2['name'] = "Escape from Planet of the Apes";
$product2['category']  = 'Movies';

$products = [



$customer1 = array();
$customer1['customer_id'] = 1100;
$customer1['email'] = "";
$customer1['first_name'] = "Floyd";
$customer1['last_name'] = 'Dogg';
$customer1['foo'] = 'bar';

$customer2 = array();
$customer2['customer_id'] = 1200;
$customer2['email'] = "";
$customer2['first_name'] = "Johnny";
$customer2['last_name'] = 'Zaius';

$customers = [



$orderData = [];
$order1 = array();
$order1['order_id'] = '1009';
$order1['subtotal'] = 6.99;
$order1['tax'] = 0;
$order1['shipping'] = 25.75;
$order1['total'] = 32.74;
$order1['email'] = '';
$order1['first_name'] = 'Floyd';
$order1['last_name'] = 'Dogg';
$order1['phone'] = '123456780';

$orderData['order'] = $order1;
$orderData['identifiers'] = ['ts'=>1460392935,'ip'=>'','email'=>'','action'=>'purchase'];

$orders = [$orderData];


Supported object types

All Zaius methods expect arrays in a specific format. Besides the keys listed for each object, any other key/value pair is accepted and will be sent as a custom field, if it was defined via the Zaius dashboard/schema API

To see the full list of available fields, access after logging in into your Zaius account.


Key Type Other details
email string
gender string
name string
first_name string
last_name string
phone string
timezone string The timezone of the user in the following format:
street1 string
street2 string
city string
state string
zip string
country string
image_url string
customer_id string


$customer = array();
$customer['email'] = '';


Key Type Other details
type string
action string string
identifiers.vuid string
data.ts integer Timestamp of the event in unix time (epoch time). Automatically set to now if not present.
data.product_id string
data.category string string string User agent
data.ip string
data.title string
data.hostname string string
data.source string
data.medium string
data.campaign string
data.content string
data.keywords string
data.language string
data.character_set string
data.days_since_last_visit integer
data.landing bool
data.referrer string
data.search_term string
data.filter_field string
data.filter_value string
data.sort_direction string
data.sort_field string


$event = array();
$event['type'] = 'test';
$event['action'] = 'test';
$event['identifiers'] = ['vuid'=>'test'];
$event['data'] = ['a'=>'b'];


Key Type Other details
brand string
category_id integer
description string
image_url string
is_in_stock bool
name string
parent_product_id integer
price number
product_id string
qty integer
sku string
special_price number
special_price_from_date timestamp
special_price_to_date timestamp
upc string


$product = array();
$product['name'] = "Test product";
$product['sku'] = 'test-sku';
$product['product_id'] = 32;


Key Type Other details
bill_address string
coupon_code string
first_name string
last_name string
name string
discount number
email string
order_id string
phone string
ship_address string
shipping number
status text
subtotal number
tax number
total number
user_id string
items.product_id string
items.sku string
items.quantity integer
items.subtotal number


$order = array();
$order['name'] = "Test customer";
$order['order_id'] = '11111';
$order['total'] = 32;
$order['items'] = [[

Generic API calls

While the SDK covers all specific operations, it is possible to initiate a general call to the API by using the call() method. Three parameters are expected:

  • $parameters - an array of parameters. For get calls, they will be sent as url parameters. For post / put calls, they will be sent as post fields
  • $method - a valid http method name, i.e. post or get
  • $url - the full endpoint url

The method returns the raw API response. Note that most of the time, this will be a json encoded string.

The method throws a ZaiusException in case the response code is any other than 20x or 404. A 404 response code returns a null body and represents the fact that no entry was found for the provided query.


$zaiusClient = $this->getZaiusClient(ZAIUS_PRIVATE_API_KEY);
$filter = ['email'=>''];
$profile = json_decode($zaiusClient->call($filter,'get',ZaiusClient::API_URL_V3.'/profiles'),true);

Batch processing

While the Zaius API is fast, it is possible to completely decouple it by using batch processing. We are making use of DJJob, as a general queueing mechanism.


Initialize the mysql database:

mysql my_database < vendor/seatgeek/djjob/jobs.sql

Before making a call to push to the queue, you need to ensure that the mysql credentials were initialized:

    'driver' => 'mysql',
    'host' => '',
    'dbname' => 'my_database',
    'user' => 'my_user',
    'password' => 'my_password',

Push events to the queue

All posting methods have a queue bool parameter that you can set to push to the queue instead of processing instantly:

$profile = array();
$profile['email'] = '';
$ret = $zaiusClient->postCustomer($profile,true);

$product = array();
$product['name'] = "Test product";
$product['sku'] = 'test-sku';
$product['product_id'] = 32;
$ret = $zaiusClient->postProduct($product,true);

The returned value from the post calls will be the mysql insert id of the pushed object.

You can later process the queue with:

$worker = new \ZaiusSDK\Zaius\Worker();