Events API Reference

Use the Events API to record user actions as they happen on your site. Sift Science provides a standardized set of events that capture common user actions in e-commerce businesses, as well as events specific to various business verticals. The more detail we capture about user behaviors, the better we are able to detect fraud.

Events API Overview

Credit cards don’t commit fraud, people do. Detecting fraud requires analyzing how users interact with your business. At Sift, we call these interactions events. Sift’s machine learning finds your business’s fraud signals from the event sequences and details you send.

  • Recommended events are the most valuable actions from which Sift can learn relevant fraud patterns when you are first starting your integration.
  • Supported events are actions common to e-commerce sites that get special analysis. Some of them are business-model specific.
  • Custom events are actions unique to your site.

Each event has fields, which provide details about that event.

  • For each event, there are some fields that are strictly required, however, we strongly recommend that you provide data for all fields listed. You can also add custom fields to events.
  • Since these details can take different forms (e.g., billing telephone number), Sift has different field types, so we can extract additional signals appropriately (e.g., area code).
  • Some field types are special — we call them complex field types, because they take nested objects as values.

Events API Endpoint

Sift Science’s Events API accepts event data as a JSON request body via a HTTP POST request at this endpoint:

https://api.siftscience.com/v203/events

Every event must contain your $api_key, the event $type, and a $user_id (if this is not available you can alternatively provide a $session_id ). The event can optionally include other custom fields as appropriate.

$create_order

Use $create_order to record when a user submits an order for products or services they intend to purchase. This API event should contain the products/services ordered, the payment instrument proposed, and user identification data. See: Integration Guides.

$typeString required

is "$create_order"

$api_keyString required

Your Sift API key.

$user_idUser ID required if known

The user’s internal account ID. This field is required on all events performed by the user while logged in. Users without an assigned $user_id will not show up in the console. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$session_idString required if no User ID is provided

The user’s current session ID, used to tie a user’s action before and after log in or account creation.

$order_idString

The ID for tracking this order in your system.

$user_emailEmail

Email of the user creating this order. Note: If the user’s email is also their account ID in your system, set both the $user_id and $user_email fields to their email address.

$amountInteger

Total transaction amount in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros.

$currency_codeString

ISO-4217 currency code for the amount. If your site uses alternative currencies, specify them here.

$billing_addressAddress

The billing address as entered by the user. Represented as a nested address object. See Address under Field Types for more details.

$payment_methodsArray of Payment Methods

The payment information associated with this order. Represented as an array of nested payment_method objects containing payment type, payment gateway, credit card bin, etc.

Note: As opposed to $transaction, $create_order takes an array of $payment_method object, so you can record orders that are paid for using multiple payments. See Payment Method under Complex Field Types for more details.

$shipping_addressAddress

The shipping address as entered by the user. Represented as a nested address object. See Address under Field Types for more details.

$expedited_shippingBoolean

Whether the user requested priority/expedited shipping on their order.

$itemsArray of Items

The list of items ordered. Represented as a JSON array of $item objects, as specified under $item. See Payment under Field Types for more details.

$seller_user_idUser ID

For marketplace businesses, this is the seller's user ID, typically a database primary key. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$shipping_methodString

Indicates the method of delivery to the user. Possible values: $electronic, $physical.

// Sample $create_order event
{
  // Required Fields
  "$type"             : "$create_order",
  "$api_key"          : "your_api_key_here",
  "$user_id"          : "billy_jones_301",

  // Supported Fields
  "$session_id"       : "gigtleqddo84l8cm15qe4il",
  "$order_id"         : "ORDER-28168441",
  "$user_email"       : "bill@gmail.com",
  "$amount"           : 506790000, // $506.79
  "$currency_code"    : "USD",
  "$billing_address"  : {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6041",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },
  "$payment_methods"  : [
      {
          "$payment_type"    : "$credit_card",
          "$payment_gateway" : "$braintree",
          "$card_bin"        : "542486",
          "$card_last4"      : "4444"
      }
  ],
  "$shipping_address"  : {
      "$name"          : "Bill Jones",
      "$phone"         : "1-415-555-6041",
      "$address_1"     : "2100 Main Street",
      "$address_2"     : "Apt 3B",
      "$city"          : "New London",
      "$region"        : "New Hampshire",
      "$country"       : "US",
      "$zipcode"       : "03257"
  },
  "$expedited_shipping" : true,
  "$items"             : [
    // A list of items
    {
      "$item_id"        : "12344321",
      "$product_title"  : "Microwavable Kettle Corn: Original Flavor",
      "$price"          : 4990000, // $4.99
      "$upc"            : "097564307560",
      "$sku"            : "03586005",
      "$brand"          : "Peters Kettle Corn",
      "$manufacturer"   : "Peters Kettle Corn",
      "$category"       : "Food and Grocery",
      "$tags"           : ["Popcorn", "Snacks", "On Sale"],
      "$quantity"       : 4
    },

    {
      "$item_id"        : "B004834GQO",
      "$product_title"  : "The Slanket Blanket-Texas Tea",
      "$price"          : 39990000, // $39.99
      "$upc"            : "67862114510011",
      "$sku"            : "004834GQ",
      "$brand"          : "Slanket",
      "$manufacturer"   : "Slanket",
      "$category"       : "Blankets & Throws",
      "$tags"           : ["Awesome", "Wintertime specials"],
      "$color"          : "Texas Tea",
      "$quantity"       : 16
    },

    {
      "$item_id"        : "10101042",
      "$product_title"  : "Delivering Happiness [eBook edition]",
      "$price"          : 6990000,  // $6.99
      "$isbn"           : "0446576220",
      "$sku"            : "10101042",
      "$brand"          : "Writers of the Round Table Press",
      "$manufacturer"   : "eBook Digital Services, Inc.",
      "$category"       : "Business books",
      "$tags"           : ["reprint", "paperback", "Tony Hsieh"],
      "$quantity"       : 1
    }
  ],

  // For marketplaces, use $seller_user_id to identify the seller
  "$seller_user_id"     : "slinkys_emporium",

  "$shipping_method"    : "$physical",

  // Sample Custom Fields
  "digital_wallet"      : "apple_pay" // "google_wallet", etc. 
  "coupon_code"         : "dollarMadness",
  "shipping_choice"     : "FedEx Ground Courier",
  "is_first_time_buyer" : false
}
import sift

client = sift.Client("your_api_key_here")

# Sample $create_order event
properties = {
  # Required Fields
  "$user_id"          : "billy_jones_301",
  # Supported Fields
  "$session_id"       : "gigtleqddo84l8cm15qe4il",
  "$order_id"         : "ORDER-28168441",
  "$user_email"       : "bill@gmail.com",
  "$amount"           : 506790000, # $506.79
  "$currency_code"    : "USD",
  "$billing_address"  : {
    "$name"         : "Bill Jones",
    "$phone"        : "1-415-555-6041",
    "$address_1"    : "2100 Main Street",
    "$address_2"    : "Apt 3B",
    "$city"         : "New London",
    "$region"       : "New Hampshire",
    "$country"      : "US",
    "$zipcode"      : "03257"
  },
  "$payment_methods"  : [
    {
      "$payment_type"    : "$credit_card",
      "$payment_gateway" : "$braintree",
      "$card_bin"        : "542486",
      "$card_last4"      : "4444"
    }
  ],
  "$shipping_address"  : {
    "$name"          : "Bill Jones",
    "$phone"         : "1-415-555-6041",
    "$address_1"     : "2100 Main Street",
    "$address_2"     : "Apt 3B",
    "$city"          : "New London",
    "$region"        : "New Hampshire",
    "$country"       : "US",
    "$zipcode"       : "03257"
  },
  "$expedited_shipping" : True,
  "$items"             : [
    # A list of items
    {
      "$item_id"        : "12344321",
      "$product_title"  : "Microwavable Kettle Corn: Original Flavor",
      "$price"          : 4990000, # $4.99
      "$upc"            : "097564307560",
      "$sku"            : "03586005",
      "$brand"          : "Peters Kettle Corn",
      "$manufacturer"   : "Peters Kettle Corn",
      "$category"       : "Food and Grocery",
      "$tags"           : ["Popcorn", "Snacks", "On Sale"],
      "$quantity"       : 4
    },
    {
      "$item_id"        : "B004834GQO",
      "$product_title"  : "The Slanket Blanket-Texas Tea",
      "$price"          : 39990000, # $39.99
      "$upc"            : "67862114510011",
      "$sku"            : "004834GQ",
      "$brand"          : "Slanket",
      "$manufacturer"   : "Slanket",
      "$category"       : "Blankets & Throws",
      "$tags"           : ["Awesome", "Wintertime specials"],
      "$color"          : "Texas Tea",
      "$quantity"       : 16
    },
    {
      "$item_id"        : "10101042",
      "$product_title"  : "Delivering Happiness [eBook edition]",
      "$price"          : 6990000,  # $6.99
      "$isbn"           : "0446576220",
      "$sku"            : "10101042",
      "$brand"          : "Writers of the Round Table Press",
      "$manufacturer"   : "eBook Digital Services, Inc.",
      "$category"       : "Business books",
      "$tags"           : ["reprint", "paperback", "Tony Hsieh"],
      "$quantity"       : 1
    }
  ],
  # For marketplaces, use $seller_user_id to identify the seller
  "$seller_user_id"     : "slinkys_emporium",

  "$shipping_method"    : "$physical",

  # Sample Custom Fields
  "digital_wallet"      : "apple_pay" # "google_wallet", etc.
  "coupon_code"         : "dollarMadness",
  "shipping_choice"     : "FedEx Ground Courier",
  "is_first_time_buyer" : False
}

response = client.track("$create_order", properties)
require "sift"

client = Sift::Client.new("your_api_key_here")

# Sample $create_order event
properties = {
  # Required Fields
  "$user_id"          => "billy_jones_301",
  # Supported Fields
  "$session_id"       => "gigtleqddo84l8cm15qe4il",
  "$order_id"         => "ORDER-28168441",
  "$user_email"       => "bill@gmail.com",
  "$amount"           => 506790000, # $506.79
  "$currency_code"    => "USD",
  "$billing_address"  => {
    "$name"         => "Bill Jones",
    "$phone"        => "1-415-555-6041",
    "$address_1"    => "2100 Main Street",
    "$address_2"    => "Apt 3B",
    "$city"         => "New London",
    "$region"       => "New Hampshire",
    "$country"      => "US",
    "$zipcode"      => "03257"
  },
  "$payment_methods"  => [
    {
      "$payment_type"    => "$credit_card",
      "$payment_gateway" => "$braintree",
      "$card_bin"        => "542486",
      "$card_last4"      => "4444"
    }
  ],
  "$shipping_address"  => {
    "$name"          => "Bill Jones",
    "$phone"         => "1-415-555-6041",
    "$address_1"     => "2100 Main Street",
    "$address_2"     => "Apt 3B",
    "$city"          => "New London",
    "$region"        => "New Hampshire",
    "$country"       => "US",
    "$zipcode"       => "03257"
  },
  "$expedited_shipping" => true,
  "$items"             => [
    # A list of items
    {
      "$item_id"        => "12344321",
      "$product_title"  => "Microwavable Kettle Corn: Original Flavor",
      "$price"          => 4990000, # $4.99
      "$upc"            => "097564307560",
      "$sku"            => "03586005",
      "$brand"          => "Peters Kettle Corn",
      "$manufacturer"   => "Peters Kettle Corn",
      "$category"       => "Food and Grocery",
      "$tags"           => ["Popcorn", "Snacks", "On Sale"],
      "$quantity"       => 4
    },
    {
      "$item_id"        => "B004834GQO",
      "$product_title"  => "The Slanket Blanket-Texas Tea",
      "$price"          => 39990000, # $39.99
      "$upc"            => "67862114510011",
      "$sku"            => "004834GQ",
      "$brand"          => "Slanket",
      "$manufacturer"   => "Slanket",
      "$category"       => "Blankets & Throws",
      "$tags"           => ["Awesome", "Wintertime specials"],
      "$color"          => "Texas Tea",
      "$quantity"       => 16
    },
    {
      "$item_id"        => "10101042",
      "$product_title"  => "Delivering Happiness [eBook edition]",
      "$price"          => 6990000,  # $6.99
      "$isbn"           => "0446576220",
      "$sku"            => "10101042",
      "$brand"          => "Writers of the Round Table Press",
      "$manufacturer"   => "eBook Digital Services, Inc.",
      "$category"       => "Business books",
      "$tags"           => ["reprint", "paperback", "Tony Hsieh"],
      "$quantity"       => 1
    }
  ],
  # For marketplaces, use $seller_user_id to identify the seller
  "$seller_user_id"     => "slinkys_emporium",

  "$shipping_method"    => "$physical",

  # Sample Custom Fields
  "digital_wallet"      => "apple_pay" # "google_wallet", etc.
  "coupon_code"         => "dollarMadness",
  "shipping_choice"     => "FedEx Ground Courier",
  "is_first_time_buyer" => false
}

response = client.track("$create_order", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient('your_api_key_here');

// Sample $create_order event
$properties = array(
  // Required Fields
  '$user_id'          => 'billy_jones_301',
  // Supported Fields
  '$session_id'       => 'gigtleqddo84l8cm15qe4il',
  '$order_id'         => 'ORDER-28168441',
  '$user_email'       => 'bill@gmail.com',
  '$amount'           => 506790000, // $506.79
  '$currency_code'    => 'USD',
  '$billing_address'  => array(
    '$name'         => 'Bill Jones',
    '$phone'        => '1-415-555-6041',
    '$address_1'    => '2100 Main Street',
    '$address_2'    => 'Apt 3B',
    '$city'         => 'New London',
    '$region'       => 'New Hampshire',
    '$country'      => 'US',
    '$zipcode'      => '03257'
  ),
  '$payment_methods'  =>array( 
    array(
      '$payment_type'    => '$credit_card',
      '$payment_gateway' => '$braintree',
      '$card_bin'        => '542486',
      '$card_last4'      => '4444'
    )
  ),
  '$shipping_address'  => array(
    '$name'          => 'Bill Jones',
    '$phone'         => '1-415-555-6041',
    '$address_1'     => '2100 Main Street',
    '$address_2'     => 'Apt 3B',
    '$city'          => 'New London',
    '$region'        => 'New Hampshire',
    '$country'       => 'US',
    '$zipcode'       => '03257'
  ),
  '$expedited_shipping' => True,
  '$items'             => array(
    // A list of items
    array(
      '$item_id'        => '12344321',
      '$product_title'  => 'Microwavable Kettle Corn: Original Flavor',
      '$price'          => 4990000, // $4.99
      '$upc'            => '097564307560',
      '$sku'            => '03586005',
      '$brand'          => 'Peters Kettle Corn',
      '$manufacturer'   => 'Peters Kettle Corn',
      '$category'       => 'Food and Grocery',
      '$tags'           => array('Popcorn', 'Snacks', 'On Sale'),
      '$quantity'       => 4
    ),
    array(
      '$item_id'        => 'B004834GQO',
      '$product_title'  => 'The Slanket Blanket-Texas Tea',
      '$price'          => 39990000, // $39.99
      '$upc'            => '67862114510011',
      '$sku'            => '004834GQ',
      '$brand'          => 'Slanket',
      '$manufacturer'   => 'Slanket',
      '$category'       => 'Blankets & Throws',
      '$tags'           => array('Awesome', 'Wintertime specials'),
      '$color'          => 'Texas Tea',
      '$quantity'       => 16
    ),
    array(
      '$item_id'        => '10101042',
      '$product_title'  => 'Delivering Happiness array[eBook edition]',
      '$price'          => 6990000,  // $6.99
      '$isbn'           => '0446576220',
      '$sku'            => '10101042',
      '$brand'          => 'Writers of the Round Table Press',
      '$manufacturer'   => 'eBook Digital Services, Inc.',
      '$category'       => 'Business books',
      '$tags'           => array('reprint', 'paperback', 'Tony Hsieh'),
      '$quantity'       => 1
    )
  ),
  // For marketplaces, use $seller_user_id to identify the seller
  '$seller_user_id'     => 'slinkys_emporium',

  '$shipping_method'    => '$physical',

  // Sample Custom Fields
  'digital_wallet'      => 'apple_pay' // 'google_wallet', etc.
  'coupon_code'         => 'dollarMadness',
  'shipping_choice'     => 'FedEx Ground Courier',
  'is_first_time_buyer' => False
);

$response = $client->track('$create_order', $properties);

$transaction

Use $transaction to record attempts to exchange money, credit or other tokens of value. $transaction is most commonly used to record the results of interactions with a payment gateway, e.g., recording that a credit card authorization attempt failed. See: Integration Guides.

$typeString required

is "$transaction"

$api_keyString required

Your Sift API key.

$user_idUser ID required

The user’s account ID according to your systems. Required on all events performed by the user while logged in. Users without an assigned $user_id will not show up in the console. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$user_emailEmail

Email of the user executing this transaction. Note: If the user’s email is also their account ID in your system, set both the $user_id and $user_email fields to their email address.

$transaction_typeString

The type of transaction being recorded. There are eight types.

$sale :
Authorization and capture of a payment performed together in one step. This is the most commonly used transaction type. This is the default $transaction_type if the transaction type is not provided.

$authorize :
Authorizing a payment by reserving the payment amount from the buyer’s account. Money does not change hands until capture.

$capture :
Capturing a payment reserved in the authorization step.

$void :
Cancelling a pending authorization or capture.

$refund :
Returning part or all of a captured payment to the buyer.

$deposit :
Depositing money into an account.

$withdrawal :
Withdrawing money from an account.

$transfer :
Transferring money from one account to another.

$transaction_statusStatus

Use $transaction_status to indicate the status of the transaction. The value can be $success (default value), $failure or $pending.

For instance, If the transaction was rejected by the payment gateway, set the value to $failure.

$amountInteger required

Total transaction amount in micros in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros.

$currency_codeString required

ISO-4217 currency code for the amount. e.g., USD, CAD, HKD. If your site uses alternative currencies, like bitcoin or points systems, specify that here.

$order_idString

The ID for this order in your system. Used for cross referencing an order in your internal systems.

$transaction_idString

The ID for identifying this transaction. Important for tracking transactions, and linking different parts of the same transaction together, e.g., linking a refund to its original transaction.

$billing_addressAddress

The billing address as entered by the user. Represented as a nested address object. See Address under Field Types for more details.

$payment_methodPayment Method

The payment information associated with this transaction. Represented as a single payment_method object containing payment method, payment gateway, credit card bin, etc.

Note: As opposed to $create_order, there should be only one $payment_method per $transaction. See Payment under Complex Field Types for more details.

$shipping_addressAddress

The shipping address as entered by the user. Represented as a nested address object. See Address under Field Types for more details.

$session_idString

The user’s current session ID, used to tie a user’s action before and after log in or account creation.

$seller_user_idUser ID

For marketplace businesses, this is the seller's user ID, typically a database primary key. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$transfer_recipient_user_idUser ID

For transfer transactions, the user ID of the user receiving the transfer. If $transfer_recipient_user_id is specified, $transaction_type must be set to $transfer; otherwise, the system will give an error.

// Sample $transaction event
{
  // Required Fields
  "$type"             : "$transaction",
  "$api_key"          : "your_api_key_here",
  "$user_id"          : "billy_jones_301",
  "$amount"           : 506790000, // $506.79
  "$currency_code"    : "USD",

  // Supported Fields
  "$user_email"       : "bill@gmail.com",
  "$transaction_type" : "$sale",
  "$transaction_status" : "$success",
  "$order_id"         : "ORDER-123124124",
  "$transaction_id"   : "719637215",

  "$billing_address"  : {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6041",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },
  "$payment_method"   : {
      "$payment_type"    : "$credit_card",
      "$payment_gateway" : "$braintree",
      "$card_bin"        : "542486",
      "$card_last4"      : "4444"
  },

  // Supported Fields
  "$shipping_address" : {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6041",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },
  "$session_id"       : "gigtleqddo84l8cm15qe4il",

  // For marketplaces, use $seller_user_id to identify the seller
  "$seller_user_id"     : "slinkys_emporium",

  // Sample Custom Fields
  "digital_wallet"      : "apple_pay" // "google_wallet", etc.
  "coupon_code"         : "dollarMadness",
  "shipping_choice"     : "FedEx Ground Courier",
  "is_first_time_buyer" : false
}
import sift

client = sift.Client("your_api_key_here")

# Sample $transaction event
properties = {
  # Required Fields
  "$user_id"          : "billy_jones_301",
  "$amount"           : 506790000, # $506.79
  "$currency_code"    : "USD",

  # Supported Fields
  "$user_email"       : "bill@gmail.com",
  "$transaction_type" : "$sale",
  "$transaction_status" : "$success",
  "$order_id"         : "ORDER-123124124",
  "$transaction_id"   : "719637215",

  "$billing_address"  : {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6041",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },
  "$payment_method"   : {
      "$payment_type"    : "$credit_card",
      "$payment_gateway" : "$braintree",
      "$card_bin"        : "542486",
      "$card_last4"      : "4444"
  },

  # Supported Fields
  "$shipping_address" : {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6041",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },
  "$session_id"       : "gigtleqddo84l8cm15qe4il",

  # For marketplaces, use $seller_user_id to identify the seller
  "$seller_user_id"     : "slinkys_emporium",

  # Sample Custom Fields
  "digital_wallet"      : "apple_pay" # "google_wallet", etc.
  "coupon_code"         : "dollarMadness",
  "shipping_choice"     : "FedEx Ground Courier",
  "is_first_time_buyer" : False
}

response = client.track("$transaction", properties)
require "sift"

client = Sift::Client.new("your_api_key_here")

# Sample $transaction event
properties = {
  # Required Fields
  "$user_id"          => "billy_jones_301",
  "$amount"           => 506790000, # $506.79
  "$currency_code"    => "USD",

  # Supported Fields
  "$user_email"       => "bill@gmail.com",
  "$transaction_type" => "$sale",
  "$transaction_status" => "$success",
  "$order_id"         => "ORDER-123124124",
  "$transaction_id"   => "719637215",

  "$billing_address"  => {
      "$name"         => "Bill Jones",
      "$phone"        => "1-415-555-6041",
      "$address_1"    => "2100 Main Street",
      "$address_2"    => "Apt 3B",
      "$city"         => "New London",
      "$region"       => "New Hampshire",
      "$country"      => "US",
      "$zipcode"      => "03257"
  },
  "$payment_method"   => {
      "$payment_type"    => "$credit_card",
      "$payment_gateway" => "$braintree",
      "$card_bin"        => "542486",
      "$card_last4"      => "4444"
  },

  # Supported Fields
  "$shipping_address" => {
      "$name"         => "Bill Jones",
      "$phone"        => "1-415-555-6041",
      "$address_1"    => "2100 Main Street",
      "$address_2"    => "Apt 3B",
      "$city"         => "New London",
      "$region"       => "New Hampshire",
      "$country"      => "US",
      "$zipcode"      => "03257"
  },
  "$session_id"       => "gigtleqddo84l8cm15qe4il",

  # For marketplaces, use $seller_user_id to identify the seller
  "$seller_user_id"     => "slinkys_emporium",

  # Sample Custom Fields
  "digital_wallet"      => "apple_pay" # "google_wallet", etc.
  "coupon_code"         => "dollarMadness",
  "shipping_choice"     => "FedEx Ground Courier",
  "is_first_time_buyer" => false
}

response = client.track("$transaction", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient('your_api_key_here');

// Sample $transaction event
$properties = array(
  // Required Fields
  '$user_id'          => 'billy_jones_301',
  '$amount'           => 506790000, // $506.79
  '$currency_code'    => 'USD',

  // Supported Fields
  '$user_email'       => 'bill@gmail.com',
  '$transaction_type' => '$sale',
  '$transaction_status' => '$success',
  '$order_id'         => 'ORDER-123124124',
  '$transaction_id'   => '719637215',

  '$billing_address'  => array(
      '$name'         => 'Bill Jones',
      '$phone'        => '1-415-555-6041',
      '$address_1'    => '2100 Main Street',
      '$address_2'    => 'Apt 3B',
      '$city'         => 'New London',
      '$region'       => 'New Hampshire',
      '$country'      => 'US',
      '$zipcode'      => '03257'
  ),
  '$payment_method'   => array(
      '$payment_type'    => '$credit_card',
      '$payment_gateway' => '$braintree',
      '$card_bin'        => '542486',
      '$card_last4'      => '4444'
  ),

  // Supported Fields
  '$shipping_address' => array(
      '$name'         => 'Bill Jones',
      '$phone'        => '1-415-555-6041',
      '$address_1'    => '2100 Main Street',
      '$address_2'    => 'Apt 3B',
      '$city'         => 'New London',
      '$region'       => 'New Hampshire',
      '$country'      => 'US',
      '$zipcode'      => '03257'
  ),
  '$session_id'       => 'gigtleqddo84l8cm15qe4il',

  // For marketplaces, use $seller_user_id to identify the seller
  '$seller_user_id'     => 'slinkys_emporium',

  // Sample Custom Fields
  'digital_wallet'      => 'apple_pay' // 'google_wallet', etc.
  'coupon_code'         => 'dollarMadness',
  'shipping_choice'     => 'FedEx Ground Courier',
  'is_first_time_buyer' => False
);

$response = $client->track('$transaction', $properties);

Supported Events

These are event types that are common to many e-commerce businesses for which we provide tailored support. We encourage you to implement as many of these as appropriate, since many of them provide high value fraud signals.

$create_account

Use $create_account to capture account creation and user details. To capture updates to an account after it is initially created, please use $update_account.

Note: if your business does not support user accounts at all, please reference the Anonymous User Activity guide for how to handle anonymous user activities.

$typeString required

is "$create_account"

$api_keyString required

Your Sift API key.

$user_idUser ID required if known

The user’s account ID according to your systems. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$session_idString required if no User ID is provided

The user’s current session ID, used to tie a user’s action before and after log in or account creation.

$user_emailEmail

Email of the user creating this account. Note: If the user’s email is also their account ID in your system, set both the $user_id and $user_email fields to their email address.

$nameString

the full name of the user here. Concatenate first name and last name together if you collect them separately in your system.

$phonePhone

The primary phone number of the user associated with this account. Provide the phone number as a string, starting with the country code. For example: "1-415-555-6041". If you collect other phone numbers for the account, provide them as additional custom fields, e.g., work_phone

$referrer_user_idUser ID

The ID of the user that referred the current user to your business. This field is required for detecting referral fraud. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$payment_methodsArray of Payment Methods

The payment method(s) associated with this account. Represented as an array of nested payment_method objects containing payment type, credit card bin, etc.

Note: $payment_methods takes an array of $payment_method object, so you can record accounts that have multiple payment methods. See Payment Method under Complex Field Types for more details.

$billing_addressAddress

The billing address associated with this user. Represented as a nested address object. See Address under Field Types for more details.

$social_sign_on_typeString

Provide the name of the social identity provider (e.g., $twitter, $facebook) in this field if the user uses them to log in to their account.

Possible values: $facebook, $google, $yahoo, $twitter, $other.

// Sample $create_account event
{
  // Required Fields
  "$type"       : "$create_account",
  "$api_key"    : "your_api_key_here",
  "$user_id"    : "billy_jones_301",

  // Supported Fields
  "$session_id"       : "gigtleqddo84l8cm15qe4il",
  "$user_email"       : "bill@gmail.com",
  "$name"             : "Bill Jones",
  "$phone"            : "1-415-555-6040",
  "$referrer_user_id" : "janejane101",
  "$payment_methods"  : [
      {
          "$payment_type"    : "$credit_card",
          "$card_bin"        : "542486",
          "$card_last4"      : "4444"
      }
  ],
  "$billing_address"  : {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6040",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },

  "$social_sign_on_type"   : "$twitter",

  // Suggested Custom Fields
  "twitter_handle"    : "billyjones",
  "work_phone"        : "1-347-555-5921",
  "location"          : "New London, NH",
  "referral_code"     : "MIKEFRIENDS",
  "email_confirmed"   : false
}
import sift

client = sift.Client("your_api_key_here")

# Sample $create_account event
properties = {
  # Required Fields
  "$user_id"    : "billy_jones_301",

  # Supported Fields
  "$session_id"       : "gigtleqddo84l8cm15qe4il",
  "$user_email"       : "bill@gmail.com",
  "$name"             : "Bill Jones",
  "$phone"            : "1-415-555-6040",
  "$referrer_user_id" : "janejane101",
  "$payment_methods"  : [
      {
          "$payment_type"    : "$credit_card",
          "$card_bin"        : "542486",
          "$card_last4"      : "4444"
      }
  ],
  "$billing_address"  : {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6040",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },

  "$social_sign_on_type"   : "$twitter",

  # Suggested Custom Fields
  "twitter_handle"    : "billyjones",
  "work_phone"        : "1-347-555-5921",
  "location"          : "New London, NH",
  "referral_code"     : "MIKEFRIENDS",
  "email_confirmed"   : False
}

response = client.track("$create_account", properties)
require "sift"

client = Sift::Client.new("your_api_key_here")

# Sample $create_account event
properties = {
  # Required Fields
  "$user_id"    => "billy_jones_301",

  # Supported Fields
  "$session_id"       => "gigtleqddo84l8cm15qe4il",
  "$user_email"       => "bill@gmail.com",
  "$name"             => "Bill Jones",
  "$phone"            => "1-415-555-6040",
  "$referrer_user_id" => "janejane101",
  "$payment_methods"  => [
      {
          "$payment_type"    => "$credit_card",
          "$card_bin"        => "542486",
          "$card_last4"      => "4444"
      }
  ],
  "$billing_address"  => {
      "$name"         => "Bill Jones",
      "$phone"        => "1-415-555-6040",
      "$address_1"    => "2100 Main Street",
      "$address_2"    => "Apt 3B",
      "$city"         => "New London",
      "$region"       => "New Hampshire",
      "$country"      => "US",
      "$zipcode"      => "03257"
  },

  "$social_sign_on_type"   => "$twitter",

  # Suggested Custom Fields
  "twitter_handle"    => "billyjones",
  "work_phone"        => "1-347-555-5921",
  "location"          => "New London, NH",
  "referral_code"     => "MIKEFRIENDS",
  "email_confirmed"   => false
}

response = client.track("$create_account", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient('your_api_key_here');

// Sample $create_account event
$properties = array(
  // Required Fields
  '$user_id'    => 'billy_jones_301',

  // Supported Fields
  '$session_id'       => 'gigtleqddo84l8cm15qe4il',
  '$user_email'       => 'bill@gmail.com',
  '$name'             => 'Bill Jones',
  '$phone'            => '1-415-555-6040',
  '$referrer_user_id' => 'janejane101',
  '$payment_methods'  => array(
      array(
          '$payment_type'    => '$credit_card',
          '$card_bin'        => '542486',
          '$card_last4'      => '4444'
      )
  ),
  '$billing_address'  => array(
      '$name'         => 'Bill Jones',
      '$phone'        => '1-415-555-6040',
      '$address_1'    => '2100 Main Street',
      '$address_2'    => 'Apt 3B',
      '$city'         => 'New London',
      '$region'       => 'New Hampshire',
      '$country'      => 'US',
      '$zipcode'      => '03257'
  ),

  '$social_sign_on_type'   => '$twitter',

  // Suggested Custom Fields
  'twitter_handle'    => 'billyjones',
  'work_phone'        => '1-347-555-5921',
  'location'          => 'New London, NH',
  'referral_code'     => 'MIKEFRIENDS',
  'email_confirmed'   => False
);

$response = $client->track('$create_account', $properties);

$update_account

Use $update_account to record changes to the user’s account information. For user accounts created prior to integrating with Sift, there’s no need to call $create_account before $update_account. Simply call $update_account and we’ll infer that account was created before integration.

$typeString required

is "$update_account"

$api_keyString required

Your Sift API key.

$user_idUser ID required

The user ID, typically a primary key in your database. Required on all events performed by the user while logged in. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$changed_passwordBoolean

If the user changed their password, set this field and mark as true.

$user_emailEmail

Updated value of the user’s email address. Note: If the user’s email is also their account ID in your system, set both the $user_id and $user_email fields to their email address.

$nameString

Provide the full name of the user here. Concatenate first name and last name together if you collect them separately in your system.

$phonePhone

Updated value of the user’s phone number.

$referrer_user_idUser ID

The ID of the user that referred the current user to your business. This field is required for detecting referral fraud. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$payment_methodsArray of Payment Methods

The payment method(s) associated with this account. Represented as an array of nested payment_method objects containing payment type, credit card bin, etc. If possible, please send all payment methods associated with the account each time payment methods are updated.

Note: $payment_methods takes an array of $payment_method object, so you can record accounts that have multiple payment methods. See Payment Method under Complex Field Types for more details.

$billing_addressAddress

The updated billing address. Represented as a nested address object. See Address under Complex Field Types for more details.

$social_sign_on_typeString

Provide the name of the social identity provider (e.g., $twitter, $facebook) in this field if the user uses them to log in to their account.

Possible values: $facebook, $google, $yahoo, $twitter, $other.

// Sample $update_account event
{
  // Required Fields
  "$type"       : "$update_account",
  "$api_key"    : "your_api_key_here",
  "$user_id"    : "billy_jones_301",

  // Supported Fields
  "$changed_password" : true,
  "$user_email"       : "bill@gmail.com",
  "$name"             : "Bill Jones",
  "$phone"            : "1-415-555-6040",
  "$referrer_user_id" : "janejane102",
  "$payment_methods"  : [
      {
          "$payment_type"    : "$credit_card",
          "$card_bin"        : "542486",
          "$card_last4"      : "4444"
      }
  ],
  "$billing_address"  :
  {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6041",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },

  "$social_sign_on_type"   : "$twitter",

  // Suggested Custom Fields
  "email_confirmed"   : true,
  "phone_confirmed"   : true
}
import sift

client = sift.Client("your_api_key_here")

# Sample $update_account event
properties = {
  # Required Fields
  "$user_id"    : "billy_jones_301",

  # Supported Fields
  "$changed_password" : True,
  "$user_email"       : "bill@gmail.com",
  "$name"             : "Bill Jones",
  "$phone"            : "1-415-555-6040",
  "$referrer_user_id" : "janejane102",
  "$payment_methods"  : [
      {
          "$payment_type"    : "$credit_card",
          "$card_bin"        : "542486",
          "$card_last4"      : "4444"
      }
  ],
  "$billing_address"  :
  {
      "$name"         : "Bill Jones",
      "$phone"        : "1-415-555-6041",
      "$address_1"    : "2100 Main Street",
      "$address_2"    : "Apt 3B",
      "$city"         : "New London",
      "$region"       : "New Hampshire",
      "$country"      : "US",
      "$zipcode"      : "03257"
  },

  "$social_sign_on_type"   : "$twitter",

  # Suggested Custom Fields
  "email_confirmed"   : True,
  "phone_confirmed"   : True
}

response = client.track("$update_account", properties)
require "sift"

client = Sift::Client.new("your_api_key_here")

# Sample $update_account event
properties = {
  # Required Fields
  "$user_id"    => "billy_jones_301",

  # Supported Fields
  "$changed_password" => true,
  "$user_email"       => "bill@gmail.com",
  "$name"             => "Bill Jones",
  "$phone"            => "1-415-555-6040",
  "$referrer_user_id" => "janejane102",
  "$payment_methods"  => [
      {
          "$payment_type"    => "$credit_card",
          "$card_bin"        => "542486",
          "$card_last4"      => "4444"
      }
  ],
  "$billing_address"  =>
  {
      "$name"         => "Bill Jones",
      "$phone"        => "1-415-555-6041",
      "$address_1"    => "2100 Main Street",
      "$address_2"    => "Apt 3B",
      "$city"         => "New London",
      "$region"       => "New Hampshire",
      "$country"      => "US",
      "$zipcode"      => "03257"
  },

  "$social_sign_on_type"   => "$twitter",

  # Suggested Custom Fields
  "email_confirmed"   => true,
  "phone_confirmed"   => true
}

response = client.track("$update_account", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient('your_api_key_here');

// Sample $update_account event
$properties = array(
  // Required Fields
  '$user_id'    => 'billy_jones_301',

  // Supported Fields
  '$changed_password' => True,
  '$user_email'       => 'bill@gmail.com',
  '$name'             => 'Bill Jones',
  '$phone'            => '1-415-555-6040',
  '$referrer_user_id' => 'janejane102',
  '$payment_methods'  => array(
      array(
          '$payment_type'    => '$credit_card',
          '$card_bin'        => '542486',
          '$card_last4'      => '4444'
      )
  ),
  '$billing_address'  =>
  array(
      '$name'         => 'Bill Jones',
      '$phone'        => '1-415-555-6041',
      '$address_1'    => '2100 Main Street',
      '$address_2'    => 'Apt 3B',
      '$city'         => 'New London',
      '$region'       => 'New Hampshire',
      '$country'      => 'US',
      '$zipcode'      => '03257'
  ),

  '$social_sign_on_type'   => '$twitter',

  // Suggested Custom Fields
  'email_confirmed'   => True,
  'phone_confirmed'   => True
);

$response = $client->track('$update_account', $properties);

$add_item_to_cart

Use $add_item_to_cart to record when a user adds an item to their shopping cart or list.

$typeString required

is "$add_item_to_cart"

$api_keyString required

Your Sift API key.

$session_idString required if no User ID is provided

The user’s current session ID, used to tie a user’s action before and after log in or account creation.

$user_idUser ID required if known

The user’s account ID according to your systems. Required on all events performed by the user while logged in. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$itemItem

The product item added to cart. Represented as a nested $item object. Required subfields are $item_id, $product_title, and $price. The $quantity is specified as a subfield.

See Item under Complex Field Types for more details.

// Sample $add_item_to_cart event
{
  // Required Fields
  "$type"       : "$add_item_to_cart",
  "$api_key"    : "your_api_key_here",
  "$user_id"    : "billy_jones_301",

  // Supported Fields
  "$session_id" : "gigtleqddo84l8cm15qe4il",
  "$item"       : {
    "$item_id"        : "B004834GQO",
    "$product_title"  : "The Slanket Blanket-Texas Tea",
    "$price"          : 39990000, // $39.99
    "$currency_code"  : "USD",
    "$upc"            : "67862114510011",
    "$sku"            : "004834GQ",
    "$brand"          : "Slanket",
    "$manufacturer"   : "Slanket",
    "$category"       : "Blankets & Throws",
    "$tags"           : ["Awesome", "Wintertime specials"],
    "$color"          : "Texas Tea",
    "$quantity"       : 16
  }
}
import sift

client = sift.Client("your_api_key_here")

# Sample $add_item_to_cart event
properties = {
  # Required Fields
  "$user_id"    : "billy_jones_301",

  # Supported Fields
  "$session_id" : "gigtleqddo84l8cm15qe4il",
  "$item"       : {
    "$item_id"        : "B004834GQO",
    "$product_title"  : "The Slanket Blanket-Texas Tea",
    "$price"          : 39990000, # $39.99
    "$currency_code"  : "USD",
    "$upc"            : "67862114510011",
    "$sku"            : "004834GQ",
    "$brand"          : "Slanket",
    "$manufacturer"   : "Slanket",
    "$category"       : "Blankets & Throws",
    "$tags"           : ["Awesome", "Wintertime specials"],
    "$color"          : "Texas Tea",
    "$quantity"       : 16
  }
}

response = client.track("$add_item_to_cart", properties)
require "sift"

client = Sift::Client.new("your_api_key_here")

# Sample $add_item_to_cart event
properties = {
  # Required Fields
  "$user_id"    => "billy_jones_301",

  # Supported Fields
  "$session_id" => "gigtleqddo84l8cm15qe4il",
  "$item"       => {
    "$item_id"        => "B004834GQO",
    "$product_title"  => "The Slanket Blanket-Texas Tea",
    "$price"          => 39990000, # $39.99
    "$currency_code"  => "USD",
    "$upc"            => "67862114510011",
    "$sku"            => "004834GQ",
    "$brand"          => "Slanket",
    "$manufacturer"   => "Slanket",
    "$category"       => "Blankets & Throws",
    "$tags"           => ["Awesome", "Wintertime specials"],
    "$color"          => "Texas Tea",
    "$quantity"       => 16
  }
}

response = client.track("$add_item_to_cart", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient('your_api_key_here');

// Sample $add_item_to_cart event
$properties = array(
  // Required Fields
  '$user_id'    => 'billy_jones_301',

  // Supported Fields
  '$session_id' => 'gigtleqddo84l8cm15qe4il',
  '$item'       => array(
    '$item_id'        => 'B004834GQO',
    '$product_title'  => 'The Slanket Blanket-Texas Tea',
    '$price'          => 39990000, // $39.99
    '$currency_code'  => 'USD',
    '$upc'            => '67862114510011',
    '$sku'            => '004834GQ',
    '$brand'          => 'Slanket',
    '$manufacturer'   => 'Slanket',
    '$category'       => 'Blankets & Throws',
    '$tags'           => array('Awesome', 'Wintertime specials'),
    '$color'          => 'Texas Tea',
    '$quantity'       => 16
  )
);

$response = $client->track('$add_item_to_cart', $properties);

$remove_item_from_cart

Use $remove_item_from_cart to record when a user removes an item from their shopping cart or list.

$typeString required

is "$remove_item_from_cart"

$api_keyString required

Your Sift API key.

$session_idString required if no User ID is provided

The user’s current session ID, used to tie a user’s action before and after log in or account creation.

$user_idUser ID required if known

The user’s account ID according to your systems. Required on all events performed by the user while logged in. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$itemItem

The product item removed from cart. Represented as a nested $item object. Strongly recommended subfields are $item_id, $product_title, and $price. The $quantity is specified as a subfield.

See Item under Complex Field Types for more details.

// Sample $remove_item_from_cart event
{
  // Required Fields
  "$type"       : "$remove_item_from_cart",
  "$api_key"    : "your_api_key_here",
  "$user_id"    : "billy_jones_301",

  // Supported Fields
  "$session_id" : "gigtleqddo84l8cm15qe4il",
  "$item"       : {
    "$item_id"        : "B004834GQO",
    "$product_title"  : "The Slanket Blanket-Texas Tea",
    "$price"          : 39990000, // $39.99
    "$currency_code"  : "USD",
    "$quantity"       : 2,
    "$upc"            : "67862114510011",
    "$sku"            : "004834GQ",
    "$brand"          : "Slanket",
    "$manufacturer"   : "Slanket",
    "$category"       : "Blankets & Throws",
    "$tags"           : ["Awesome", "Wintertime specials"],
    "$color"          : "Texas Tea"
  }
}
import sift

client = sift.Client("your_api_key_here")

# Sample $remove_item_from_cart event
properties = {
  # Required Fields
  "$user_id"    : "billy_jones_301",

  # Supported Fields
  "$session_id" : "gigtleqddo84l8cm15qe4il",
  "$item"       : {
    "$item_id"        : "B004834GQO",
    "$product_title"  : "The Slanket Blanket-Texas Tea",
    "$price"          : 39990000, # $39.99
    "$currency_code"  : "USD",
    "$quantity"       : 2,
    "$upc"            : "67862114510011",
    "$sku"            : "004834GQ",
    "$brand"          : "Slanket",
    "$manufacturer"   : "Slanket",
    "$category"       : "Blankets & Throws",
    "$tags"           : ["Awesome", "Wintertime specials"],
    "$color"          : "Texas Tea"
  }
}

response = client.track("$remove_item_from_cart", properties)
require "sift"

client = Sift::Client.new("your_api_key_here")

# Sample $remove_item_from_cart event
properties = {
  # Required Fields
  "$user_id"    => "billy_jones_301",

  # Supported Fields
  "$session_id" => "gigtleqddo84l8cm15qe4il",
  "$item"       => {
    "$item_id"        => "B004834GQO",
    "$product_title"  => "The Slanket Blanket-Texas Tea",
    "$price"          => 39990000, # $39.99
    "$currency_code"  => "USD",
    "$quantity"       => 2,
    "$upc"            => "67862114510011",
    "$sku"            => "004834GQ",
    "$brand"          => "Slanket",
    "$manufacturer"   => "Slanket",
    "$category"       => "Blankets & Throws",
    "$tags"           => ["Awesome", "Wintertime specials"],
    "$color"          => "Texas Tea"
  }
}

response = client.track("$remove_item_from_cart", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient('your_api_key_here');

// Sample $remove_item_from_cart event
$properties = array(
  // Required Fields
  '$user_id'    => 'billy_jones_301',

  // Supported Fields
  '$session_id' => 'gigtleqddo84l8cm15qe4il',
  '$item'       => array(
    '$item_id'        => 'B004834GQO',
    '$product_title'  => 'The Slanket Blanket-Texas Tea',
    '$price'          => 39990000, // $39.99
    '$currency_code'  => 'USD',
    '$quantity'       => 2,
    '$upc'            => '67862114510011',
    '$sku'            => '004834GQ',
    '$brand'          => 'Slanket',
    '$manufacturer'   => 'Slanket',
    '$category'       => 'Blankets & Throws',
    '$tags'           => array('Awesome', 'Wintertime specials'),
    '$color'          => 'Texas Tea'
  )
);

$response = $client->track('$remove_item_from_cart', $properties);

$submit_review

Use $submit_review to record a user-submitted review of a product or other users. e.g., a seller on your site.

$typeString required

is "$submit_review"

$api_keyString required

Your Sift API key.

$user_idUser ID required if known

The user’s account ID according to your systems. Required on all events performed by the user while logged in. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$session_idString required if no user ID is provided

The user’s current session ID, used to tie a user’s action before and after log in or account creation.

$contentString

The text content of review submitted.

$review_titleString

The title of review submitted.

$item_idString

The ID of the product or service being reviewed.

$reviewed_user_idUser ID

The user ID of the user being reviewed. Required to compute network graphs. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$submission_statusStatus

If reviews in your system must be approved, use $submission_status to represent the status of the review. The field value can be $success, $failure or $pending.

// Sample $submit_review event
{
  // Required Fields
  "$type"              : "$submit_review",
  "$api_key"           : "your_api_key_here",
  "$user_id"           : "billy_jones_301",


  // Supported Fields
  "$content"           : "Text content of submitted review goes here.",
  "$review_title"      : "Title of Review Goes Here",
  "$item_id"           : "V4C3D5R2Z6",
  "$reviewed_user_id"  : "billy_jones_301",
  "$submission_status" : "$success",

  // Sample Custom Fields
  "rating"             : "5"
}
import sift

client = sift.Client("your_api_key_here")

# Sample $submit_review event
properties = {
  # Required Fields

  "$user_id"           : "billy_jones_301",


  # Supported Fields
  "$content"           : "Text content of submitted review goes here.",
  "$review_title"      : "Title of Review Goes Here",
  "$item_id"           : "V4C3D5R2Z6",
  "$reviewed_user_id"  : "billy_jones_301",
  "$submission_status" : "$success",

  # Sample Custom Fields
  "rating"             : "5"
}

response = client.track("$submit_review", properties)
require "sift"

client = Sift::Client.new("your_api_key_here")

# Sample $submit_review event
properties = {
  # Required Fields
  "$user_id"           => "billy_jones_301",


  # Supported Fields
  "$content"           => "Text content of submitted review goes here.",
  "$review_title"      => "Title of Review Goes Here",
  "$item_id"           => "V4C3D5R2Z6",
  "$reviewed_user_id"  => "billy_jones_301",
  "$submission_status" => "$success",

  # Sample Custom Fields
  "rating"             => "5"
}

response = client.track("$submit_review", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient('your_api_key_here');

// Sample $submit_review event
$properties = array(
  // Required Fields
  '$user_id'           => 'billy_jones_301',


  // Supported Fields
  '$content'           => 'Text content of submitted review goes here.',
  '$review_title'      => 'Title of Review Goes Here',
  '$item_id'           => 'V4C3D5R2Z6',
  '$reviewed_user_id'  => 'billy_jones_301',
  '$submission_status' => '$success',

  // Sample Custom Fields
  'rating'             => '5'
);

$response = $client->track('$submit_review', $properties);

$send_message

Use $send_message to record when a user sends a message to another user i.e. the recipient.

$typeString required

is "$send_message"

$api_keyString required

Your Sift API key.

$user_idUser ID required

The user’s account ID according to your systems. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$session_idString required if no user ID is provided

The user’s current session ID, used to tie a user’s action before and after log in or account creation.

$recipient_user_idUser ID

The ID of the user receiving the message. Required to compute network graphs. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$subjectString

The subject of the message.

$contentString

The text content of the message.

// Sample $send_message event
{
  // Required Fields
  "$type"       : "$send_message",
  "$api_key"    : "your_api_key_here",
  "$user_id"    : "billy_jones_301",

  // Supported Fields
  "$recipient_user_id" : "512924123",
  "$subject"    : "Subject line of the message.",
  "$content"    : "Text content of message."
}
import sift

client = sift.Client("your_api_key_here")

# Sample $send_message event
properties = {
  # Required Fields

  "$user_id"    : "billy_jones_301",

  # Supported Fields
  "$recipient_user_id" : "512924123",
  "$subject"    : "Subject line of the message.",
  "$content"    : "Text content of message."
}

response = client.track("$send_message", properties)
require "sift"

client = Sift::Client.new("your_api_key_here")

# Sample $send_message event
properties = {
  # Required Fields

  "$user_id"    => "billy_jones_301",

  # Supported Fields
  "$recipient_user_id" => "512924123",
  "$subject"    => "Subject line of the message.",
  "$content"    => "Text content of message."
}

response = client.track("$send_message", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient('your_api_key_here');

// Sample $send_message event
$properties = array(
  // Required Fields

  '$user_id'    => 'billy_jones_301',

  // Supported Fields
  '$recipient_user_id' => '512924123',
  '$subject'    => 'Subject line of the message.',
  '$content'    => 'Text content of message.'
);

$response = $client->track('$send_message', $properties);

$create_content

Use $create_content to record when a user creates content on your site (for example, a job posting, sale listing, or blog post).

$typeString required

is "$create_content"

$api_keyString required

Your Sift API key.

$user_idUser ID required

The user’s account ID according to your systems. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$session_idString required if no user ID is provided

The user’s current session ID, used to tie a user’s action before and after log in or account creation.

$contact_emailEmail

The contact email provided with the posting.

$contact_phonePhone

The contact phone number provided with the posting.

$subjectString

The subject of the content.

$contentString

The text body of the content.

// Sample $create_content event
{
  // Required Fields
  "$type"       : "$create_content",
  "$api_key"    : "your_api_key_here",
  "$user_id"    : "billy_jones_301",

  // Supported Fields
  "$contact_email" : "bill@gmail.com",
  "$contact_phone" : "1-415-555-6040",
  "$subject"    : "Job available now",
  "$content"    : "Contact me for more details."
}
import sift

client = sift.Client("your_api_key_here")

# Sample $create_content event
properties = {
  # Required Fields

  "$user_id"    : "billy_jones_301",

  # Supported Fields
  "$contact_email" : "bill@gmail.com",
  "$contact_phone" : "1-415-555-6040",
  "$subject"    : "Job available now",
  "$content"    : "Contact me for more details."
}

response = client.track("$create_content", properties)
require "sift"

client = Sift::Client.new("your_api_key_here")

# Sample $send_message event
properties = {
  # Required Fields

  "$user_id"    => "billy_jones_301",

  # Supported Fields
  "$contact_email" => "bill@gmail.com",
  "$contact_phone" => "1-415-555-6040",
  "$subject" => "Job available now",
  "$content"  => "Contact me for more details."
}

response = client.track("$create_content", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient('your_api_key_here');

// Sample $send_message event
$properties = array(
  // Required Fields

  '$user_id'    => 'billy_jones_301',

  // Supported Fields
  '$contact_email' => 'bill@gmail.com',
  '$contact_phone' => '1-415-555-6040',
  '$subject' => 'Job available now',
  '$content'  => 'Contact me for more details.'
);

$response = $client->track('$create_content', $properties);

$login

Use $login to record when a user attempts to log in.

$typeString required

is "$login"

$api_keyString required

Your Sift API key.

$user_idUser ID required

The user’s account ID according to your systems. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

$session_idString recommended

The user’s current session ID, used to tie a user’s action before and after log in or account creation.

$login_statusStatus recommended

Use $login_status to represent the success or failure of the log in attempt. The field value can be $success (default value) or $failure.

// Sample $login event
{
  // Required Fields
  "$type"         : "$login",
  "$api_key"      : "your_api_key_here",
  "$user_id"      : "billy_jones_301",

  // Recommended Fields
  "$session_id"   : "gigtleqddo84l8cm15qe4il",
  "$login_status" : "$success"
}
import sift

client = sift.Client("your_api_key_here")

# Sample $login event
properties = {
  # Required Fields
  "$user_id"      : "billy_jones_301",

  # Recommended Fields
  "$session_id"   : "gigtleqddo84l8cm15qe4il",
  "$login_status" : "$success"
}

response = client.track("$login", properties)
require "sift"

client = Sift::Client.new("your_api_key_here")

# Sample $login event
properties = {
  # Required Fields
  "$user_id"      => "billy_jones_301",

  # Recommended Fields
  "$session_id"   => "gigtleqddo84l8cm15qe4il",
  "$login_status" => "$success"
}

response = client.track("$login", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient('your_api_key_here');

// Sample $login event
$properties = array(
  // Required Fields
  '$user_id'      => 'billy_jones_301',

  // Recommended Fields
  '$session_id'   => 'gigtleqddo84l8cm15qe4il',
  '$login_status' => '$success'
);

$response = $client->track('$login', $properties);

$logout

Use $logout to record when a user logs out.

$typeString required

is "$logout"

$api_keyString required

Your Sift API key.

$user_idUser ID required

The user’s account ID according to your systems. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

// Sample $logout event
{
  // Required Fields
  "$type"      : "$logout",
  "$api_key"   : "209f490k25lb9021",
  "$user_id"   : "billy_jones_301"
}
import sift

client = sift.Client("your_api_key_here")

# Sample $logout event
properties = {
  # Required Fields
  "$user_id"   : "billy_jones_301"
}

response = client.track("$logout", properties)
require "sift"

client = Sift::Client.new("your_api_key_here")

# Sample $logout event
properties = {
  # Required Fields
  "$user_id"   => "billy_jones_301"
}

response = client.track("$logout", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient('your_api_key_here');

// Sample $logout event
$properties = array(
  // Required Fields
  '$user_id'   => 'billy_jones_301'
);

$response = $client->track('$logout', $properties);

Custom Events

Custom events are events that you can come up with on your own, in order to capture user behavior not currently captured in Sift Science’s supported set of events. We analyze these events to extract what signals we can. Custom events that prove to be useful can graduate to become supported events.

For example, let’s say you have a voice over IP phone business, and you want to record when a user makes a call. You can create a custom event called make_call:

For every custom event, three fields are required:

  • the $type field where you specify the name of the custom event you’re creating. Note that the leading $ denotes reserved events, and may not be used in custom events. Custom event names may only include alphanumeric characters and _.
  • the $api_key field where you provide your Sift API key.
  • the $user_id or, if not available, the $session_id which identifies the user taking this action.

Custom events that follow Sift’s API grammar tend to be more effective. Some of our customers have created custom events recording where users are picked up and dropped off in car sharing services, how bids are placed in auctions, and when users subscribe to mailing lists. For guidance on how to create custom events, see our Creating Custom Events guide.

// A hypothetical custom event recording a call made
// using a number of formatted fields
{
  "$type"              : "make_call",
  "$api_key"           : "your_api_key_here",
  "$user_id"           : "billy_jones_301",
  "recipient_user_id"  : "marylee819",
  "call_duration"      : 4428
}
import sift

client = sift.Client("your_api_key_here")

# A hypothetical custom event recording a call made
# using a number of formatted fields
properties = {
  "$user_id"           : "billy_jones_301",
  "recipient_user_id"  : "marylee819",
  "call_duration"      : 4428
}

response = client.track("make_call", properties)
require "sift"

client = Sift::Client.new("your_api_key_here")

# A hypothetical custom event recording a call made
# using a number of formatted fields
properties = {
  "$user_id"           => "billy_jones_301",
  "recipient_user_id"  => "marylee819",
  "call_duration"      => 4428
}

response = client.track("make_call", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient('your_api_key_here');

// Sample $link_session_to_user event
$properties = array(
  '$user_id'           => 'billy_jones_301',
  'recipient_user_id'  => 'marylee819',
  'call_duration'      => 4428
);


$response = $client->track('make_call', $properties);

Fields Overview

Events have a number of fields that describe either the user or the action being performed unless otherwise specified. There are three categories of fields:

Required FieldsThese are fields that are strictly required to form a valid API request.
Supported FieldsThese are fields that are known to make an event more informative and help Sift compute extra fraud patterns that refine fraud detection accuracy. We encourage you to include as many supported fields in your events as possible.
Custom FieldsThese are fields you can add to events to represent information not covered by the required or supported fields. If your custom field is of a supported field type, it’s important to name the field properly so we can perform the relevant analysis on them. Custom field names may only include alphanumeric characters and _. See the Naming Custom Fields section in our Creating Custom Events tutorial for more information.

Formatted Field Types

In addition to the primitive field value types (e.g., String, Integer, Boolean), Sift Science also supports more specific data types. Since these types have specific semantics and internal structure, our algorithms are able to extract more information from them. Be sure to use these suffixes in custom fields so we can employ our field type algorithms properly.

Email

_email

Email addresses, sent as a String. Sift performs a number of fraud detection algorithms on emails, including matching against throw-away email domains, and looking for similarity to known fraudsters in the past.

To take advantage of Sift’s email processing algorithms, end field names with _email. For example: referrer_email, seller_email

Phone

_phone

Phone numbers, sent as a String. Sift can perform lookups to identify country and region of phone numbers if the data is well formed. For example: "1-415-555-6041".

To take advantage of Sift’s phone number processing algorithms, end field names with _phone. For example: secondary_phone, mobile_phone.

Latitude

_lat

Latitude, sent as a floating point number with at least two significant figures. Sift uses this data to calculate location and movement, which are particularly useful for businesses where location is an important part of the transaction and for mobile transactions. Typically used along with longitude.

To take advantage of Sift’s geolocation algorithms, end field names with _lat. For example: dropoff_location_lat.

Longitude

_lng

Longitude, sent as a floating point number with at least two significant figures. Sift uses this data to calculate location and movement, which are particularly useful for businesses where location is an important part of the transaction and for mobile transactions. Typically used along with latitude.

To take advantage of Sift’s geolocation algorithms, end field names with _lng. For example: pickup_location_lng.

User ID

_user_id

User ID, sent as a String. These should be the same IDs you can use to lookup users on your user managament systems. Note: User IDs are case sensitive. You may need to normalize the capitalization of your user IDs.

Valid characters in user IDs are limited to the alphanumeric characters (without space) and: =, ., -, _, +, @, :, &, ^, %, !, $.

Status

_status

Status of an event, sent as a String. The status field type accepts three possible values: $success, $failure, and $pending. Many events in e-commerce (e.g., payment authorization, email verification) result in some permission or verification state. End field names with _status capture these permission state.

Example of Formatted Field Type Usage

Here is a sample custom event that uses the _user_id and status fields.

// A sample customer event called request_friend
{
  "$api_key"           : "your_api_key_here",
  "$type"              : "request_friend",
  "$user_id"           : "billy_jones_301",
  "recipient_user_id"  : "marylee819",
  "request_status"     : "$pending"
}
import sift

client = sift.Client("your_api_key_here")

# A hypothetical custom event recording a call made
# using a number of formatted fields
properties = {
  "$user_id"           : "billy_jones_301",
  "recipient_user_id"  : "marylee819",
  "request_status"     : "$pending"
}

response = client.track("request_friend", properties)
require "sift"

client = Sift::Client.new("your_api_key_here")

# A hypothetical custom event recording a call made
# using a number of formatted fields
properties = {
  "$user_id"           => "billy_jones_301",
  "recipient_user_id"  => "marylee819",
  "request_status"     => "$pending"
}

response = client.track("request_friend", properties)
require 'sift-php/lib/Services_JSON-1.0.3/JSON.php';
require 'sift-php/lib/SiftRequest.php';
require 'sift-php/lib/SiftResponse.php';
require 'sift-php/lib/SiftClient.php';
require 'sift-php/lib/Sift.php';

$client = new SiftClient('your_api_key_here');

// Sample $link_session_to_user event
$properties = array(
  '$user_id'           => 'billy_jones_301',
  'recipient_user_id'  => 'marylee819',
  'request_status'     => '$pending'
);


$response = $client->track('request_friend', $properties);

Complex Fields Types

Many fields in events have a complex internal structure. We accomodate this by allowing nested JSON objects. In order to properly parse the structure, we need to know the type of the field. The types of fields we support are:

Address

The Address field type represents a physical address, such as a billing or shipping address. The value must be a nested object with the appropriate address subfields. We extract many geolocation features from these values. An address is represented as a nested JSON object.

Fields of this type: $billing_address, $shipping_address

Subfields in Address

$nameString

Provide the full name associated with the address here. Concatenate first name and last name together if you collect them separately in your system.

$address_1String

Address first line, e.g., "2100 Main Street".

$address_2String

Address second line, e.g., "Apt 3B".

$cityString

The city or town name.

$regionString

The region portion of the address. In the USA, this corresponds to the state.

$countryString

The ISO-3166 country code for the billing address.

$zipcodeString

The postal code associated with the address, e.g., "90210".

$phonePhone

The phone number associated with the address, e.g., "1-415-555-6041".

// Sample $address field value
"$billing_address"  : {  // or "$shipping_address"
  "$name"         : "Bill Jones",
  "$phone"        : "1-415-555-6041",
  "$address_1"    : "2100 Main Street",
  "$address_2"    : "Apt 3B",
  "$city"         : "New London",
  "$region"       : "New Hampshire",
  "$country"      : "US",
  "$zipcode"      : "03257"
}
# Sample $address field value
billing_address  = {  # or shipping_address
  "$name"         : "Bill Jones",
  "$phone"        : "1-415-555-6041",
  "$address_1"    : "2100 Main Street",
  "$address_2"    : "Apt 3B",
  "$city"         : "New London",
  "$region"       : "New Hampshire",
  "$country"      : "US",
  "$zipcode"      : "03257"
}
# Sample $address field value
billing_address  = {  # or shipping_address
  "$name"         => "Bill Jones",
  "$phone"        => "1-415-555-6041",
  "$address_1"    => "2100 Main Street",
  "$address_2"    => "Apt 3B",
  "$city"         => "New London",
  "$region"       => "New Hampshire",
  "$country"      => "US",
  "$zipcode"      => "03257"
}
// Sample $address field value
$billingAddress  = array(  // or $shippingAddress
  '$name'         => 'Bill Jones',
  '$phone'        => '1-415-555-6041',
  '$address_1'    => '2100 Main Street',
  '$address_2'    => 'Apt 3B',
  '$city'         => 'New London',
  '$region'       => 'New Hampshire',
  '$country'      => 'US',
  '$zipcode'      => '03257'
);

Item

The Item field type represents a product or service for sale in your business. The value must be a nested object with the appropriate item subfields. Generally used in the $add_item_to_cart and $remove_item_from_cart events. An item is represented as a nested JSON object.

Subfields in Item

$item_idString

The item’s unique identifier according to your systems. Use the same ID that you would use to look up items on your website’s database.

$product_titleString

The item’s name, e.g., "Men’s Running Springblade Drive Shoes, US10".

$priceInteger

The item unit price in micros, in the base unit of the $currency_code. 1 cent = 10,000 micros. $1.23 USD = 123 cents = 1,230,000 micros.

$currency_codeString

ISO-4217 currency code for the price.

$quantityInteger

Quantity of the item.

$upcString

If the item has a Universal Product Code, (UPC) provide it here.

$skuString

If the item has a Stock-keeping Unit ID (SKU), provide it here.

$isbnString

If the item is a book with an International Standard Book Number (ISBN), provide it here.

$brandString

The brand name of the item.

$manufacturerString

Name of the item’s manufacturer.

$categoryString

The category this item is listed under in your business. e.g., "kitchen appliance", "menswear > pants"

$tagsArray of Strings

The tags used to describe this item in your business. e.g., "funny", "halloween"

$colorString

The color of the item.

$sizeString

The size of the item.

// Example 1
"$item" : {
  "$item_id"        : "B004834GQO",
  "$product_title"  : "The Slanket Blanket-Texas Tea",
  "$price"          : 39990000,  // $39.99
  "$currency_code"  : "USD",
  "$upc"            : "67862114510011",
  "$sku"            : "004834GQ",
  "$brand"          : "Slanket",
  "$manufacturer"   : "Slanket",
  "$category"       : "Blankets & Throws",
  "$tags"           : ["Awesome", "Wintertime specials"],
  "$color"          : "Texas Tea",
  "$quantity"       : 6
}

// Example 2
"$item" : {
  "$item_id"        : "10101042",
  "$product_title"  : "Delivering Happiness [eBook edition]",
  "$price"          : 6990000, // $6.99
  "$currency_code"  : "CDN",
  "$isbn"           : "0446576220",
  "$sku"            : "10101042",
  "$brand"          : "Writers of the Round Table Press",
  "$manufacturer"   : "eBook Digital Services, Inc.",
  "$category"       : "Business books",
  "$tags"           : ["reprint", "paperback", "Tony Hsieh"],
  "$quantity"       : 1
}
# Example 1
item = {
  "$item_id"        : "B004834GQO",
  "$product_title"  : "The Slanket Blanket-Texas Tea",
  "$price"          : 39990000,  # $39.99
  "$currency_code"  : "USD",
  "$upc"            : "67862114510011",
  "$sku"            : "004834GQ",
  "$brand"          : "Slanket",
  "$manufacturer"   : "Slanket",
  "$category"       : "Blankets & Throws",
  "$tags"           : ["Awesome", "Wintertime specials"],
  "$color"          : "Texas Tea",
  "$quantity"       : 6
}

# Example 2
item = {
  "$item_id"        : "10101042",
  "$product_title"  : "Delivering Happiness [eBook edition]",
  "$price"          : 6990000, # $6.99
  "$currency_code"  : "CDN",
  "$isbn"           : "0446576220",
  "$sku"            : "10101042",
  "$brand"          : "Writers of the Round Table Press",
  "$manufacturer"   : "eBook Digital Services, Inc.",
  "$category"       : "Business books",
  "$tags"           : ["reprint", "paperback", "Tony Hsieh"],
  "$quantity"       : 1
}
# Example 1
item = {
  "$item_id"        => "B004834GQO",
  "$product_title"  => "The Slanket Blanket-Texas Tea",
  "$price"          => 39990000,  # $39.99
  "$currency_code"  => "USD",
  "$upc"            => "67862114510011",
  "$sku"            => "004834GQ",
  "$brand"          => "Slanket",
  "$manufacturer"   => "Slanket",
  "$category"       => "Blankets & Throws",
  "$tags"           => ["Awesome", "Wintertime specials"],
  "$color"          => "Texas Tea",
  "$quantity"       => 6
}

# Example 2
item = {
  "$item_id"        => "10101042",
  "$product_title"  => "Delivering Happiness [eBook edition]",
  "$price"          => 6990000, # $6.99
  "$currency_code"  => "CDN",
  "$isbn"           => "0446576220",
  "$sku"            => "10101042",
  "$brand"          => "Writers of the Round Table Press",
  "$manufacturer"   => "eBook Digital Services, Inc.",
  "$category"       => "Business books",
  "$tags"           => ["reprint", "paperback", "Tony Hsieh"],
  "$quantity"       => 1
}
// Example 1
$item = array(
  '$item_id'        => 'B004834GQO',
  '$product_title'  => 'The Slanket Blanket-Texas Tea',
  '$price'          => 39990000,  // $39.99
  '$currency_code'  => 'USD',
  '$upc'            => '67862114510011',
  '$sku'            => '004834GQ',
  '$brand'          => 'Slanket',
  '$manufacturer'   => 'Slanket',
  '$category'       => 'Blankets & Throws',
  '$tags'           => ['Awesome', 'Wintertime specials'],
  '$color'          => 'Texas Tea',
  '$quantity'       => 6
);

// Example 2
$item = array(
  '$item_id'        => '10101042',
  '$product_title'  => 'Delivering Happiness [eBook edition]',
  '$price'          => 6990000, // $6.99
  '$currency_code'  => 'CDN',
  '$isbn'           => '0446576220',
  '$sku'            => '10101042',
  '$brand'          => 'Writers of the Round Table Press',
  '$manufacturer'   => 'eBook Digital Services, Inc.',
  '$category'       => 'Business books',
  '$tags'           => ['reprint', 'paperback', 'Tony Hsieh'],
  '$quantity'       => 1
);

Payment Method

The payment_method field type represents information about the payment methods provided by the user. The value must be a nested object with the appropriate item subfields for the given payment method. Generally used with the $create_order or $transaction events.

Subfields in Payment Method

$payment_typeString

Possible values: $credit_card, $electronic_fund_transfer, $crypto_currency, $cash, $store_credit, $gift_card, $points, $financing, $check, $money_order, $voucher, $interac, $masterpass, $third_party_processor

If your payment system is not covered by one of the values above, contact us.

$payment_gatewayString

The payment processor used for this payment.

Supported values: $adyen, $affirm, $alipay, $altapay, $amazon_payments, $authorizenet, $balanced, $beanstream, $bluepay, $braintree, $chase_paymentech, $cielo, $cofinoga, $coinbase, $collector, $compropago, $conekta, $cuentadigital, $cybersource, $datacash, $debitway, $dibs, $digital_river, $elavon, $epayeu, $eprocessing_network, $eway, $first_data, $giropay, $global_payments, $globalcollect, $ingenico, $internetsecure, $intuit_quickbooks_payments, $iugu, $mastercard_payment_gateway, $mercadopago, $merchant_esolutions, $mirjeh, $mollie, $moneris_solutions, $nmi, $ogone, $openpaymx, $optimal_payments, $payfast, $paygate, $payment_express, $paymill, $payone, $paypal, $paystation, $paytrace, $paytrail, $payture, $payu, $payulatam, $payza, $pinpayments, $pivotal_payments, $princeton_payment_solutions, $psigate, $qiwi, $quickpay, $raberil, $rede, $redpagos, $rewardspay, $rocketgate, $sagepay, $sermepa, $simplify_commerce, $skrill, $smartcoin, $sofort, $sps_decidir, $stripe, $synapsepay, $telerecargas, $towah, $unionpay, $usa_epay, $vantiv, $veritrans, $vindicia, $virtual_card_services, $vme, $worldpay

If the payment gateway you use is not supported, please let us know.

$card_binString

The first six digits of the credit card number. These numbers contain information about the card issuer, the geography and other card details.

$card_last4String

The last four digits of the credit card number.

$avs_result_codeString

Response code from the AVS address verification system. Used in payments involving credit cards.

$cvv_result_codeString

Response code from the credit card company indicating if the CVV number entered matches the number on record. Used in payments involving credit cards.

$verification_statusString

Use $verification_status to indicate the payment method has been verified. The value can be $success, $failure or $pending.

For instance, if you request payment method verification from a payment processor and receive a failure set the value to $failure.

$routing_numberString

This is the ABA routing number used for electronic fund transfers.

$decline_reason_codeString

In case of a declined payment, response code received from the payment processor indicating the reason for the decline.

$paypal_payer_idString

Payer ID returned by Paypal.

$paypal_payer_emailString

Payer email address returned by Paypal.

$paypal_payer_statusString

Payer status returned by Paypal.

$paypal_address_statusString

Payer address status returned by Paypal.

$paypal_protection_eligibilityString

Seller protection eligibility returned by Paypal.

$paypal_payment_statusString

Payment status returned by Paypal.

$stripe_tokenString

User token returned by Stripe.

$stripe_cvc_checkString

CVC verification result returned by Stripe.

$stripe_address_line1_checkString

Address line 1 verification result returned by Stripe.

$stripe_address_line2_checkString

Address line 2 verification result returned by Stripe.

$stripe_address_zip_checkString

Address zip code verification result returned by Stripe.

$stripe_fundingString

Funding source returned by Stripe.

$stripe_brandString

Card brand returned by Stripe.

// A Credit Card Payment and a Gift Card used together,
// as $payment_methods in $create_order.
// Note: A $create_order event can have multiple payment
// methods, and thus takes an array of objects.
"$payment_methods" : [
  {
    "$payment_type"    : "$credit_card",
    "$payment_gateway" : "$stripe",
    "$card_bin"        : "542486",
    "$card_last4"      : "4242",
    "$cvv_result_code" : "M",
    "$avs_result_code" : "Y",
    "$stripe_address_line1_check" : "pass",
    "$stripe_address_line2_check" : "pass",
    "$stripe_address_zip_check"   : "pass"
  },
  {
    "$payment_type"    : "$gift_card"
  }
]

// A Electronic Fund Transfer Payment,
// as it would appear in a $create_order event.
"$payment_methods" : [
  {
    "$payment_type"  : "$electronic_fund_transfer",
    "$routing_number"  : "021001088"
  }
]

// A Paypal Payment, as it would appear 
// in a $create_order event.
"$payment_methods" : [
  {
    "$payment_type"  : "$third_party_processor",
    "$payment_gateway" : "$paypal",
    "$paypal_payer_id" : "7E7MGXCWKTKK2",
    "$paypal_payer_email" : "bill@gmail.com",
  }
]

// A Points or Alternative Currency Payment,
// as it would appear in a $transaction event.
// Note: There is one payment method per $transaction.
"$payment_method" : {
  "$payment_type"  : "$points"
}
# A Credit Card Payment and a Gift Card used together,
# as $payment_methods in $create_order.
# Note: A $create_order event can have multiple payment
# methods, and thus takes an array of objects.
payment_methods = [
  {
    "$payment_type"    : "$credit_card",
    "$payment_gateway" : "$stripe",
    "$card_bin"        : "542486",
    "$card_last4"      : "4242",
    "$cvv_result_code" : "M",
    "$avs_result_code" : "Y",
    "$stripe_address_line1_check" : "pass",
    "$stripe_address_line2_check" : "pass",
    "$stripe_address_zip_check"   : "pass"
  },
  {
    "$payment_type"    : "$gift_card"
  }
]

# A Electronic Fund Transfer Payment,
# as it would appear in a $create_order event.
payment_methods = [
  {
    "$payment_type"  : "$electronic_fund_transfer",
    "$routing_number"  : "021001088"
  }
]

# A Paypal Payment, as it would appear 
# in a $create_order event.
payment_methods = [
  {
    "$payment_type"  : "$third_party_processor",
    "$payment_gateway" : "$paypal",
    "$paypal_payer_id" : "7E7MGXCWKTKK2",
    "$paypal_payer_email" : "bill@gmail.com",
  }
]

# A Points or Alternative Currency Payment,
# as it would appear in a $transaction event.
# Note: There is one payment method per $transaction.
payment_method = {
  "$payment_type"  : "$points"
}
# A Credit Card Payment and a Gift Card used together,
# as $payment_methods in $create_order.
# Note: A $create_order event can have multiple payment
# methods, and thus takes an array of objects.
payment_methods = [
  {
    "$payment_type"    => "$credit_card",
    "$payment_gateway" => "$stripe",
    "$card_bin"        => "542486",
    "$card_last4"      => "4242",
    "$cvv_result_code" => "M",
    "$avs_result_code" => "Y",
    "$stripe_address_line1_check" => "pass",
    "$stripe_address_line2_check" => "pass",
    "$stripe_address_zip_check"   => "pass"
  },
  {
    "$payment_type"    => "$gift_card"
  }
]

# A Electronic Fund Transfer Payment,
# as it would appear in a $create_order event.
payment_methods = [
  {
    "$payment_type"  => "$electronic_fund_transfer",
    "$routing_number"  => "021001088"
  }
]

# A Paypal Payment, as it would appear 
# in a $create_order event.
payment_methods = [
  {
    "$payment_type"  => "$third_party_processor",
    "$payment_gateway" => "$paypal",
    "$paypal_payer_id" => "7E7MGXCWKTKK2",
    "$paypal_payer_email" => "bill@gmail.com",
  }
]

# A Points or Alternative Currency Payment,
# as it would appear in a $transaction event.
# Note: There is one payment method per $transaction.
payment_method = {
  "$payment_type"  => "$points"
}
// A Credit Card Payment and a Gift Card used together,
// as $payment_methods in $create_order.
// Note: A $create_order event can have multiple payment
// methods, and thus takes an array of objects.
$paymentMethods = array(
  array(
    '$payment_type'    => '$credit_card',
    '$payment_gateway' => '$stripe',
    '$card_bin'        => '542486',
    '$card_last4'      => '4242',
    '$cvv_result_code' => 'M',
    '$avs_result_code' => 'Y',
    '$stripe_address_line1_check' => 'pass',
    '$stripe_address_line2_check' => 'pass',
    '$stripe_address_zip_check'   => 'pass'
  ),
  array(
    '$payment_type'    => '$gift_card'
  )
);

// A Electronic Fund Transfer Payment,
// as it would appear in a $create_order event.
$paymentMethods = array(
  array(
    '$payment_type'  => '$electronic_fund_transfer',
    '$routing_number'  => '021001088'
  )
);

// A Paypal Payment, as it would appear 
// in a $create_order event.
"$payment_methods" : [
  {
    "$payment_type"  : "$third_party_processor",
    "$payment_gateway" : "$paypal",
    "$paypal_payer_id" : "7E7MGXCWKTKK2",
    "$paypal_payer_email" : "bill@gmail.com",
  }
]



// A Points or Alternative Currency Payment,
// as it would appear in a $transaction event.
// Note: There is one payment method per $transaction.
$paymentMethod = array(
  '$payment_type'  => '$points'
);

Error Codes

A successful API request will respond with an HTTP 200. An invalid API request will respond with an HTTP 400. The response body will be a JSON object describing why the request failed.

Any non-zero status indicates an error

Possible status codes are listed here:

NameDescription
0Success
51Invalid API key
52Invalid characters in field name
53Invalid characters in field value
55Missing required field
56Invalid JSON in request
57Invalid HTTP body
60Rate limited; please contact us to increase this limit
104Invalid API version
105Not a valid reserved field

If our servers are dealing with unexpected problems, you’ll likely see an HTTP 500 response.

{
    "status" : 51,         // Non-zero status indicates an error!
    "error_message" : "Invalid API Key. Please check your credentials and try again.",
    "time" : 1327604222,   // When we received the original request (as seconds since the epoch)
    "request" : "{ \"$api_key\": \"XXXXXXXXXXX\", \"$type\": \"$capture_payment\"... }"
}
# To check if the call was successfull:
response.is_ok() # returns true on successful calls, false on failed score requests.

response.api_status         # returns Sift Error Code, 51 in this case.

response.api_error_message  # returns the error message associated with the api_status, "Invalid API Key. Please check your credentials and try again." in this case.
# To check if the call was successfull:
response.ok? # returns true on successful calls, false on failed score requests.

response.api_status         # returns Sift Error Code, 51 in this case.

response.api_error_message  # returns the error message associated with the api_status, "Invalid API Key. Please check your credentials and try again." in this case.
// To check if the call was successfull:
response->isOk() // returns true on successful calls, false on failed score requests.

response->apiStatus         // returns Sift Error Code, 51 in this case.

response->apiErrorMessage  // returns the error message associated with the api_status, "Invalid API Key. Please check your credentials and try again." in this case.