Introduction
Welcome to the Drip API! The REST API communicates exclusively in JSON over SSL (HTTPS).
All endpoint URLs begin with https://api.getdrip.com/. Additionally, the REST API requires the use of a client which supports SNI.
Parameters must be serialized in JSON and passed in the request body (not in the query string or form parameters). You should use the media type designation of application/json.
REST Section
Authentication
For private integrations, you will need to use your personal API Token (found here) via the
api_keysetting. The API Token is the username portion of the Basic Authentication scheme, with an empty password. (Note the trailing colon to indicate an empty password.)
require 'drip-ruby'
client = Drip::Client.new do |c|
c.api_key = "YOUR_API_KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')(
{
token: YOUR_API_KEY,
accountId: YOUR_ACCOUNT_ID
}
);
curl "api_endpoint_here" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-H 'Authorization: Basic $(echo YOUR_API_KEY: | base64)'
curl "api_endpoint_here" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u 'YOUR_API_KEY:'
For public integrations, for example, when allowing your customers within your application to authorize access directly to their Drip accounts, pass in the user's OAuth token via the
access_tokensetting or pass theBearertoken type when using the JS wrapper:
client = Drip::Client.new do |c|
c.access_token = "YOUR_ACCESS_TOKEN"
c.account_id = "YOUR_ACCOUNT_ID"
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')(
{
token: YOUR_API_KEY,
tokenType: "Bearer",
accountId: YOUR_ACCOUNT_ID
}
);
curl "api_endpoint_here" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
The REST API accepts both token-based authentication (intended for private integrations), and full OAuth 2 authentication (for public integrations).
OAuth
For public integrations with Drip, you must use OAuth based authentication. Here's a quick overview of how to get going.
- Get your favorite OAuth Library
- Register your application with us. We will then supply you with an client id and client secret. Please be aware that you must also enter a valid callback url before you will be able to activate your application.
- Configure your OAuth client with the credentials supplied to you when you created your application. Request authorization at:
https://www.getdrip.com/oauth/authorize. You should only have to do this once, as tokens do not expire. - Activate your application and you're on your way!
If you're not going to use a library and will be rolling your own OAuth 2 client, here's the long form of how you can get going.
{
"access_token": "822bbf7cd12243df...",
"token_type": "bearer",
"scope": "public"
}
- First and foremost remember to register your app with us as outlined above.
- Once you have registered your app, it will then need to request authorization by redirecting your user to the following url:
https://www.getdrip.com/oauth/authorize?response_type=code&client_id=<your_client_id>&redirect_uri=<your_redirect_uri> - We will then authenticate their Drip account and ask if it's ok to give access to your app.
- The user will then be redirected back to your app with a verification code that will expire in 10 minutes.
- Your app will then need to make a request to trade that verification code for an access token:
POST https://www.getdrip.com/oauth/token?response_type=token&client_id=<your_client_id>&client_secret=<your_client_secret>&code=<your_verification_code>&redirect_uri=<your_redirect_uri>&grant_type=authorization_code - We will then authenticate your app and issue you an access token as shown on the right.
- You can now use that access token in the header of your API requests as follows:
Authorization: Bearer 822bbf7cd12243df...
Rate Limiting
All API requests subject to rate limiting contain information regarding your current rate limit status in the response headers:
HTTP/1.1 200 OK
Status: 200 OK
X-RateLimit-Limit: 3600
X-RateLimit-Remaining: 3597
If you exceed your rate limit, the API will returns a 429 status:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{
"message": "API rate limit exceeded. Please try again in an hour.",
"documentation": "https://www.getdrip.com/docs/rest-api#rate-limting"
}
You can make up to 50 requests per hour for batch endpoints and 3,600 individual requests per hour for other API endpoints. Each batch request accommodates up to 1,000 records in the payload for a total of 50,000 updates per hour.
To minimize your API requests, use the Batch API.
Batch API
Create or update a batch of subscribers
To create or update a batch of subscribers:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/subscribers/batches" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"batches": [{
"subscribers": [
{
"email": "john@acme.com",
"time_zone": "America/Los_Angeles",
"tags": ["Customer", "SEO"],
"custom_fields": {
"shirt_size": "Medium"
}
},
{
"email": "joe@acme.com",
"time_zone": "America/Los_Angeles",
"tags": ["Prospect"],
"custom_fields": {
"shirt_size": "Medium"
}
}
]
}]
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
# An array of subscribers
subscribers = [
{
"email": "john@acme.com"
},
{
"email": "jane@acme.com"
}
# ...
]
response = client.create_or_update_subscribers(subscribers)
if response.success?
# ...
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const batch = {
"batches": [{
"subscribers": [
{
"email": "john@acme.com",
"tags": "Dog Person"
},
{
"email": "jane@acme.com",
"tags": "Cat Person"
}
// Lots more subscribers...
]
}]
};
client.updateBatchSubscribers(batch, (errors, responses, bodies) => {
// Do stuff
}
);
Responds with a
201 Createdresponse and an empty JSON response if successful:
{}
We recommend using this API endpoint when you need to create or update a collection of subscribers at once.
Note: Since our batch APIs process requests in the background, there may be a delay between the time you submit your request and the time your data appears in the user interface.
HTTP Endpoint
POST /v2/:account_id/subscribers/batches
Arguments
| Key | Description |
|---|---|
subscribers |
Required. An Array with between 1 and 1000 objects containing subscriber data. |
Unsubscribe a batch of subscribers
To globally unsubscribe a batch of subscribers:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/unsubscribes/batches" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"batches": [{
"subscribers": [
{
"email": "john@acme.com"
},
{
"email": "jane@acme.com"
}
]
}]
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
# An array of subscribers
subscribers = [
{
"email": "john@acme.com"
},
{
"email": "jane@acme.com"
}
# ...
]
response = client.unsubscribe_subscribers(subscribers)
if response.success?
# ...
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const payload = {
batches:
[
{
subscribers: [
{
email: "someone@example.com"
}
]
}
]
};
client.unsubscribeBatchSubscribers(payload)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
Responds with a
204 No Contentresponse if successful.
HTTP Endpoint
POST /v2/:account_id/unsubscribes/batches
Arguments
| Key | Description |
|---|---|
subscribers |
Required. An Array with between 1 and 1000 objects containing subscriber data. |
Record a batch of events
To record a batch of events:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/events/batches" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"batches": [{
"events": [
{
"email": "john@acme.com",
"action": "Opened a door"
},
{
"email": "joe@acme.com",
"action": "Closed a door"
}
]
}]
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
# An array of events
events = [
{
"email": "john@acme.com",
"action": "Opened a door"
},
{
"email": "joe@acme.com",
"action": "Closed a door"
}
# ...
]
response = client.track_events(events)
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const payload = [{
events: [
{
email: "john@acme.com",
action: "Opened a door"
},
{
email: "joe@acme.com",
action: "Closed a door"
}
]
}];
client.recordBatchEvents(payload)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
Responds with a
201 Createdresponse and an empty JSON response if successful:
{}
We recommend using this API endpoint when you need to record a collection of events at once that will likely exceed the regular rate limit of 3,600 requests per hour.
Note: Since our batch APIs process requests in the background, there may be a delay between the time you submit your request and the time your data appears in the user interface.
HTTP Endpoint
POST /v2/:account_id/events/batches
Arguments
| Key | Description |
|---|---|
events |
Required. An Array with between 1 and 1000 objects containing event data. |
Create or update a batch of carts
To create or update a batch of carts:
curl -X POST "https://api.getdrip.com/v3/YOUR_ACCOUNT_ID/shopper_activity/cart/batch" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"carts": [
{
"provider": "my_custom_platform",
"email": "user@gmail.com",
"action": "created",
"cart_id": "456445746",
"occurred_at": "2019-01-17T20:50:00Z",
"cart_public_id": "#5",
"grand_total": 16.99,
"total_discounts": 5.34,
"currency": "USD",
"cart_url": "https://mysuperstore.com/cart/456445746",
"items": [
{
"product_id": "B01J4SWO1G",
"product_variant_id": "B01J4SWO1G-CW-BOTT",
"sku": "XHB-1234",
"name": "The Coolest Water Bottle",
"brand": "Drip",
"categories": [
"Accessories"
],
"price": 11.16,
"quantity": 2,
"discounts": 5.34,
"total": 16.99,
"product_url": "https://mysuperstore.com/dp/B01J4SWO1G",
"image_url": "https://www.getdrip.com/images/example_products/water_bottle.png",
"product_tag": "Best Seller"
}
]
},
{
"provider": "my_custom_platform",
"email": "john@acme.com",
"action": "created",
"occurred_at": "2019-03-12T15:31:58Z",
"cart_id": "63754763",
"cart_public_id": "#4",
"grand_total": 54.00,
"total_discounts": 1.00,
"currency": "USD",
"order_url": "http://myorders.com/orders/4",
"items": [{
"product_id": "B01F9AQ99M",
"product_variant_id": "B01F9AQ99M-YEL-BT",
"sku": "JDT-4321",
"name": "Yellow Boots of Might",
"brand": "Drip",
"categories": [
"Of Might",
"Outdoors"
],
"price": 55.00,
"quantity": 1,
"discounts": 1.00,
"total": 54.00,
"color": "black",
"product_url": "https://mysuperstore.com/dp/B01F9AQ99M",
"image_url": "https://www.getdrip.com/images/example_products/boots.png"
}]
}
]
}
EOF
Responds with a
202 Acceptedif successful. That means the server accepted the request and queued it for processing. The response includes a list of unique request_ids that can be used to check the status of the request later on:
{
"request_ids": [
"db8a7b16-32dd-4863-8b6e-818e3eaab99a",
"002048e9-3692-4f0a-8bbf-80a077acf642"
]
}
We recommend using this API endpoint when you need to import a collection of carts that will likely exceed the regular rate limit of 3,600 requests per hour.
Note: Since our batch APIs process requests in the background, there may be a delay between the time you submit your request and the time your data appears in the user interface.
HTTP Endpoint
POST /v3/:account_id/shopper_activity/cart/batch
Arguments
| Key | Description |
|---|---|
carts |
Required. An Array with between 1 and 1000 objects containing cart activity. |
Create or update a batch of orders (Legacy)
To create or update a batch of orders:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/orders/batches" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"batches": [{
"orders": [
{
"email": "john@acme.com",
"provider": "shopify",
"upstream_id": "abcdef",
"identifier": "Order_123456",
"amount": 4900,
"tax": 100,
"fees": 0,
"discount": 0,
"permalink": "http://myorders.com/orders/123456",
"currency_code": "USD",
"properties": {
"shirt_size": "Medium",
"color": "red"
},
"occurred_at": "2013-06-21T10:31:58Z",
"closed_at": "2013-06-21T10:35:58Z",
"cancelled_at": null,
"financial_state": "paid",
"fulfillment_state": "fulfilled",
"billing_address": {
"name": "Bill Billington",
"first_name": "Bill",
"last_name": "Billington",
"company": "Bills R US",
"address_1": "123 Bill St.",
"address_2": "Apt. B",
"city": "Billtown",
"state": "CA",
"zip": "01234",
"country": "United States",
"phone": "555-555-5555",
"email": "bill@bills.com"
},
"shipping_address": {
"name": "Ship Shippington",
"first_name": "Ship",
"last_name": "Shipington",
"company": "Shipping 4 Less",
"address_1": "123 Ship St.",
"address_2": "null",
"city": "Shipville",
"state": "CA",
"zip": "01234",
"country": "United States",
"phone": "555-555-5555",
"email": "ship@shipping.com"
},
"items": [{
"id": "8888888",
"product_id": "765432",
"sku": "4444",
"amount": 4900,
"name": "Canoe",
"quantity": 1,
"upstream_id": "hijkl",
"upstream_product_id": "opqrs",
"upstream_product_variant_id": "zyxwv",
"price": 4900,
"tax": 100,
"fees": 0,
"discount": 100,
"taxable": true,
"properties": {
"color": "black"
}
}]
},
{
"email": "joe@acme.com",
"provider": "shopify",
"upstream_id": "fedcba",
"identifier": "Order_654321",
"amount": 4900,
"tax": 100,
"fees": 0,
"discount": 0,
"permalink": "http://myorders.com/orders/654321",
"currency_code": "USD",
"properties": {
"size": "small",
"color": "blue"
},
"occurred_at": "2013-05-18T10:31:58Z",
"closed_at": "2013-05-18T10:35:58Z",
"cancelled_at": null,
"financial_state": "paid",
"fulfillment_state": "fulfilled",
"billing_address": {
"name": "Bill Billington",
"first_name": "Bill",
"last_name": "Billington",
"company": "Bills R US",
"address_1": "123 Bill St.",
"address_2": "Apt. B",
"city": "Billtown",
"state": "CA",
"zip": "01234",
"country": "United States",
"phone": "555-555-5555",
"email": "bill@bills.com"
},
"shipping_address": {
"name": "Ship Shippington",
"first_name": "Ship",
"last_name": "Shipington",
"company": "Shipping 4 Less",
"address_1": "123 Ship St.",
"address_2": "null",
"city": "Shipville",
"state": "CA",
"zip": "01234",
"country": "United States",
"phone": "555-555-5555",
"email": "ship@shipping.com"
},
"items": [{
"id": "8888888",
"product_id": "765432",
"sku": "4444",
"amount": 4900,
"name": "Canoe",
"quantity": 1,
"upstream_id": "hijkl",
"upstream_product_id": "opqrs",
"upstream_product_variant_id": "zyxwv",
"price": 4900,
"tax": 100,
"fees": 0,
"discount": 100,
"taxable": true,
"properties": {
"color": "black"
}
}]
}
]
}]
}
EOF
Responds with a
202 Acceptedresponse and an empty JSON response:
{}
We recommend using this API endpoint when you need to create a collection of orders and subscribers at once that will likely exceed the regular rate limit of 3,600 requests per hour.
Note: Since our batch APIs process requests in the background, there may be a delay between the time you submit your request and the time your data appears in the user interface.
HTTP Endpoint
POST /v2/:account_id/orders/batches
Arguments
| Key | Description |
|---|---|
orders |
Required. An Array with between 1 and 1000 objects containing order data. |
Create or update a batch of orders
To create or update a batch of orders:
curl -X POST "https://api.getdrip.com/v3/YOUR_ACCOUNT_ID/shopper_activity/order/batch" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"orders": [
{
"provider": "my_custom_platform",
"email": "john@acme.com",
"action": "placed",
"occurred_at": "2019-03-12T15:31:58Z",
"order_id": "63754763",
"order_public_id": "#4",
"grand_total": 54.00,
"total_discounts": 1.00,
"total_taxes": 1.00,
"total_fees": 0,
"total_shipping": 5.00,
"currency": "USD",
"order_url": "http://myorders.com/orders/4",
"items": [{
"product_id": "B01F9AQ99M",
"product_variant_id": "B01F9AQ99M-YEL-BT",
"sku": "JDT-4321",
"name": "Yellow Boots of Might",
"brand": "Drip",
"categories": [
"Of Might",
"Outdoors"
],
"price": 49.00,
"quantity": 1,
"discounts": 1.00,
"taxes": 1.00,
"fees": 0,
"shipping": 5.00,
"total": 54.00,
"color": "black",
"product_url": "https://mysuperstore.com/dp/B01F9AQ99M",
"image_url": "https://www.getdrip.com/images/example_products/boots.png"
}],
"billing_address": {
"label": "Primary Billing",
"first_name": "Bill",
"last_name": "Billington",
"company": "Bills R US",
"address_1": "123 Bill St.",
"address_2": "Apt. B",
"city": "Billtown",
"state": "CA",
"postal_code": "01234",
"country": "United States",
"phone": "555-555-5555"
},
"shipping_address": {
"label": "Downtown Office",
"first_name": "Ship",
"last_name": "Shipington",
"company": "Shipping 4 Less",
"address_1": "123 Ship St.",
"address_2": "null",
"city": "Shipville",
"state": "CA",
"postal_code": "01234",
"country": "United States",
"phone": "555-555-5555"
}
},
{
"provider": "my_custom_platform",
"email": "user@gmail.com",
"action": "updated",
"occurred_at": "2019-03-12T15:27:16Z",
"order_id": "456445746",
"order_public_id": "#5",
"grand_total": 21.48,
"total_discounts": 5.34,
"total_taxes": 1.00,
"total_fees": 2.00,
"total_shipping": 5.00,
"currency": "USD",
"order_url": "https://mysuperstore.com/order/5",
"items": [
{
"product_id": "B01J4SWO1G",
"product_variant_id": "B01J4SWO1G-CW-BOTT",
"sku": "XHB-1234",
"name": "The Coolest Water Bottle",
"brand": "Drip",
"categories": [
"Accessories"
],
"price": 11.16,
"sale_price": 10.16,
"quantity": 2,
"discounts": 5.34,
"taxes": 1.00,
"fees": 0.50,
"shipping": 5.00,
"total": 21.48,
"product_url": "https://mysuperstore.com/dp/B01J4SWO1G",
"image_url": "https://www.getdrip.com/images/example_products/water_bottle.png",
"product_tag": "Best Seller"
}
],
"billing_address": {
"label": "Primary Billing",
"first_name": "Bill",
"last_name": "Billington",
"company": "Bills R US",
"address_1": "123 Bill St.",
"address_2": "Apt. B",
"city": "Billtown",
"state": "CA",
"postal_code": "01234",
"country": "United States",
"phone": "555-555-5555"
},
"shipping_address": {
"label": "Downtown Office",
"first_name": "Ship",
"last_name": "Shipington",
"company": "Shipping 4 Less",
"address_1": "123 Ship St.",
"city": "Shipville",
"state": "CA",
"postal_code": "01234",
"country": "United States",
"phone": "555-555-5555"
}
}
]
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
response = client.create_order_activity_events(
[
{
provider: "my_custom_platform",
email: "john@acme.com",
action: "placed",
occurred_at: "2019-03-12T15:31:58Z",
order_id: "63754763",
order_public_id: "#4",
grand_total: 54.00,
total_discounts: 1.00,
total_taxes: 1.00,
total_fees: 0,
total_shipping: 5.00,
currency: "USD",
order_url: "http://myorders.com/orders/4",
items: [{
product_id: "B01F9AQ99M",
product_variant_id: "B01F9AQ99M-YEL-BT",
sku: "JDT-4321",
name: "Yellow Boots of Might",
brand: "Drip",
categories: [
"Of Might",
"Outdoors"
],
price: 49.00,
quantity: 1,
discounts: 1.00,
taxes: 1.00,
fees: 0,
shipping: 5.00,
total: 54.00,
color: "black",
product_url: "https://mysuperstore.com/dp/B01F9AQ99M",
image_url: "https://www.getdrip.com/images/example_products/boots.png"
}],
billing_address: {
label: "Primary Billing",
first_name: "Bill",
last_name: "Billington",
company: "Bills R US",
address_1: "123 Bill St.",
address_2: "Apt. B",
city: "Billtown",
state: "CA",
postal_code: "01234",
country: "United States",
phone: "555-555-5555"
},
shipping_address: {
label: "Downtown Office",
first_name: "Ship",
last_name: "Shipington",
company: "Shipping 4 Less",
address_1: "123 Ship St.",
address_2: "null",
city: "Shipville",
state: "CA",
postal_code: "01234",
country: "United States",
phone: "555-555-5555"
}
},
{
provider: "my_custom_platform",
email: "user@gmail.com",
action: "updated",
occurred_at: "2019-03-12T15:27:16Z",
order_id: "456445746",
order_public_id: "#5",
grand_total: 21.48,
total_discounts: 5.34,
total_taxes: 1.00,
total_fees: 2.00,
total_shipping: 5.00,
currency: "USD",
order_url: "https://mysuperstore.com/order/5",
items: [
{
product_id: "B01J4SWO1G",
product_variant_id: "B01J4SWO1G-CW-BOTT",
sku: "XHB-1234",
name: "The Coolest Water Bottle",
brand: "Drip",
categories: [
"Accessories"
],
price: 11.16,
sale_price: 10.16,
quantity: 2,
discounts: 5.34,
taxes: 1.00,
fees: 0.50,
shipping: 5.00,
total: 21.48,
product_url: "https://mysuperstore.com/dp/B01J4SWO1G",
image_url: "https://www.getdrip.com/images/example_products/water_bottle.png",
product_tag: "Best Seller"
}
],
billing_address: {
label: "Primary Billing",
first_name: "Bill",
last_name: "Billington",
company: "Bills R US",
address_1: "123 Bill St.",
address_2: "Apt. B",
city: "Billtown",
state: "CA",
postal_code: "01234",
country: "United States",
phone: "555-555-5555"
},
shipping_address: {
label: "Downtown Office",
first_name: "Ship",
last_name: "Shipington",
company: "Shipping 4 Less",
address_1: "123 Ship St.",
city: "Shipville",
state: "CA",
postal_code: "01234",
country: "United States",
phone: "555-555-5555"
}
}
]
)
if response.success?
puts "Request accepted"
else
puts "Error occurred"
end
Responds with a
202 Acceptedif successful. That means the server accepted the request and queued it for processing. The response includes a list of unique request_ids that can be used to check the status of the request later on:
{
"request_ids": [
"db8a7b16-32dd-4863-8b6e-818e3eaab99a",
"002048e9-3692-4f0a-8bbf-80a077acf642"
]
}
We recommend using this API endpoint when you need to import a collection of orders that will likely exceed the regular rate limit of 3,600 requests per hour.
Note: Since our batch APIs process requests in the background, there may be a delay between the time you submit your request and the time your data appears in the user interface.
HTTP Endpoint
POST /v3/:account_id/shopper_activity/order/batch
Arguments
| Key | Description |
|---|---|
orders |
Required. An Array with between 1 and 1000 objects containing order activity. |
Create or update a batch of products
To create or update a batch of products:
curl -X POST "https://api.getdrip.com/v3/YOUR_ACCOUNT_ID/shopper_activity/product/batch" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"products": [
{
"provider": "my_custom_platform",
"action": "created",
"occurred_at": "2019-01-28T12:15:23Z",
"product_id": "B01J4SWO1G",
"product_variant_id": "B01J4SWO1G-CW-BOTT",
"sku": "XHB-1234",
"name": "The Coolest Water Bottle",
"brand": "Drip",
"categories": [
"Accessories"
],
"price": 11.16,
"inventory": 42,
"product_url": "https://mysuperstore.com/dp/B01J4SWO1G",
"image_url": "https://www.getdrip.com/images/example_products/water_bottle.png"
},
{
"provider": "my_custom_platform",
"action": "created",
"occurred_at": "2019-01-28T12:15:23Z",
"product_id": "B01J4SWO1G2",
"product_variant_id": "B01J4SWO1G-CW-BOTT2",
"sku": "XHB-1235",
"name": "The Coolest Water Bottle",
"brand": "Drip",
"categories": [
"Accessories"
],
"price": 11.16,
"inventory": 42,
"product_url": "https://mysuperstore.com/dp/B01J4SWO1G2",
"image_url": "https://www.getdrip.com/images/example_products/water_bottle.png"
},
{
"provider": "my_custom_platform",
"action": "created",
"occurred_at": "2019-01-28T12:15:23Z",
"product_id": "B01J4SWO1G3",
"product_variant_id": "B01J4SWO1G-CW-BOTT3",
"sku": "XHB-1236",
"name": "The Coolest Water Bottle",
"brand": "Drip",
"categories": [
"Accessories"
],
"price": 11.16,
"inventory": 42,
"product_url": "https://mysuperstore.com/dp/B01J4SWO1G3",
"image_url": "https://www.getdrip.com/images/example_products/water_bottle.png"
}
]
}
EOF
Responds with a
202 Acceptedif successful. That means the server accepted the request and queued it for processing. The response includes a list of unique request_ids that can be used to check the status of the request later on:
{
"request_ids": [
"db8a7b16-32dd-4863-8b6e-818e3eaab99a",
"002048e9-3692-4f0a-8bbf-80a077acf642"
]
}
We recommend using this API endpoint when you need to import a collection of products that will likely exceed the regular rate limit of 3,600 requests per hour.
Note: Since our batch APIs process requests in the background, there may be a delay between the time you submit your request and the time your data appears in the user interface.
HTTP Endpoint
POST /v3/:account_id/shopper_activity/product/batch
Arguments
| Key | Description |
|---|---|
products |
Required. An Array with between 1 and 1000 products containing product activity. |
Pagination
An example
metapayload:
{
"page": 1,
"count": 100,
"total_pages": 3,
"total_count": 300
}
Some endpoints that return collections are paginated. For these endpoints,
the meta object will tell you the current page, count,
total number of pages, and total count of the collection.
By default, the API will return the first page of results. Each page contains
a maximum of 100 items, unless otherwise noted below. To fetch a particular page,
use the page query parameter.
Errors
If you are authenticated but attempt to access a resource for which you do not have sufficient permissions, you will receive a
403 Forbiddenresponse.
{
"errors": [{
"code": "authorization_error",
"message": "You are not authorized to access this resource"
}]
}
If the resource is not found, you will receive a
404 Not Foundresponse.
{
"errors": [{
"code": "not_found_error",
"message": "The resource you requested was not found"
}]
}
Drip responds to invalid requests in a number of different ways. Exceptions to these rules will be noted for any applicable endpoints. Assume authentication is required on all endpoints unless otherwise noted.
If you attempt to anonymously access a resource that requires authentication, you will receive a 401 Unauthorized response.
Validation Errors
An example response:
{
"errors": [
{
"code": "presence_error",
"attribute": "email",
"message": "Email is required"
},
{
"code": "length_error",
"attribute": "name",
"message": "Name must be between 2 and 20 characters"
}
]
}
If validation errors occur while attempting to create or update a resource, you will receive a 422 Unprocessable Entity response with an errors object detailing which attributes are invalid. One of the following codes will assigned to each error object:
| Code | Description |
|---|---|
presence_error |
The attribute is required. |
length_error |
The length of the attribute is out of bounds. |
uniqueness_error |
The attribute must be unique. |
email_error |
The attribute must be a valid email address. |
sms_error |
The attribute must be a valid US mobile number with E.164 formatting. E.g. "+16125551212". |
url_error |
The attribute must be a valid URL. |
domain_error |
The attribute must be a valid domain name. |
time_error |
The attribute must be a valid time in ISO-8601 format. |
email_address_list_error |
The attribute must be a valid comma-separated list of email addresses. |
days_of_the_week_error |
The attribute must be a valid days of the week mask of the format /\A(0|1){7}\z/ (excluding 0000000). |
unavailable_error |
A resource has been disabled or deleted. |
format_error |
A resource identifier or object is not formatted correctly. |
range_error |
A numeric value is out of range. |
Transition Errors
An example response:
{
"errors": [
{
"code": "no_postal_address_error"
}
]
}
State transition endpoints will respond with a 403 Forbidden and an errors object if the transition is not allowed.
Accounts
Accounts are represented as follows:
{
"id": "9999999",
"name": "Acme, Inc.",
"url": "www.acme.com",
"default_from_name": "John Doe",
"default_from_email": "john@acme.com",
"default_postal_address": "123 Anywhere St\nFresno, CA 99999",
"primary_email": "john@acme.com",
"enable_third_party_cookies": false,
"phone_number": "999-999-9999",
"created_at": "2013-06-21T10:31:58Z",
"href": "https://api.getdrip.com/v2/accounts/9999999"
}
All responses containing account data also include the following top-level link data:
{
"links": {
"accounts.broadcasts": "https://api.getdrip.com/v2/{accounts.id}/broadcasts",
"accounts.campaigns": "https://api.getdrip.com/v2/{accounts.id}/campaigns",
"accounts.goals": "https://api.getdrip.com/v2/{accounts.id}/goals"
}
}
Properties
| Property | Description |
|---|---|
id |
A read-only Drip generated unique id used to identify each subscriber record. |
name |
The name assigned to each account. Defaults to the account's website URL. |
url |
The account's website URL. |
default_from_name |
A default "from name" that appears in your sent emails and can be changed on a per email basis. |
default_from_email |
A default "from email" that appears in your sent emails and can be changed on a per email basis. |
default_postal_address |
As required by the CAN-SPAM Act, this is a default postal address used for all sent emails and can be changed on a per email basis. |
primary_email |
The account owner's email address. |
enable_third_party_cookies |
When enabled allows tracking visitors across multiple domains (e.g. you use a shopping cart system hosted on a different site). |
phone_number |
The account's primary contact number. |
created_at |
A read-only Drip generated timestamp for when the account was first created. |
href |
The url designated for retrieving the account record via the REST API. |
links |
An object containing URLs for campaign and conversion resources. Note, conversions are represented as "Goals". |
List all accounts
To list all accounts the authenticated user has access to:
curl "https://api.getdrip.com/v2/accounts" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
response = client.accounts
if response.success?
puts response.body["accounts"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
client.listAccounts()
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The accounts property is an array of account objects.
{
"links": { ... },
"accounts": [ ... ]
}
HTTP Endpoint
GET /v2/accounts
Arguments
None.
Fetch an account
To fetch a specific account:
curl "https://api.getdrip.com/v2/accounts/ACCOUNT_ID" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
account_id = 9999999
response = client.account(account_id)
if response.success?
puts response.body
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
client.fetchAccount(accountId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The accounts property is an array of one account object.
{
"links": { ... },
"accounts": [{ ... }]
}
HTTP Endpoint
GET /v2/accounts/:account_id
Arguments
None.
Single-Email Campaigns
(aka Broadcasts)
Single-Email Campaigns are represented as follows:
{
"id": "123456",
"status": "sent",
"name": "4 Marketing Automation Trends for 2015",
"from_name": "John Doe",
"from_email": "john@example.com",
"postal_address": "123 Anywhere St\nFresno, CA 99999",
"localize_sending_time": true,
"send_at": "2015-07-01T10:00:00Z",
"bcc": null,
"created_at": "2015-06-21T10:31:58Z",
"href": "https://api.getdrip.com/v2/9999999/broadcast/123456",
"subject": "4 Marketing Automation Trends for 2015",
"html_body": "HTML body",
"text_body": "Text body",
"links": {
"account": "9999999"
}
}
All responses containing Single-Email Campaign data also include the following top-level link data:
{
"links": {
"broadcasts.account": "https://api.getdrip.com/v2/accounts/{broadcasts.account}",
}
}
Properties
| Property | Description |
|---|---|
id |
A read-only Drip generated unique id used to identify each Single-Email Campaign record. |
status |
Returns whether the Single-Email Campaign is draft, canceled, scheduled, sent or sending. |
name |
The private name given to the Single-Email Campaign. |
from_name |
A "from name" that appears in your sent emails and can be changed on a per email basis. This setting overrides the account's default from name. |
from_email |
A "from email" that appears in your sent emails and can be changed on a per email basis. This setting overrides the account's default from email. |
postal_address |
As required by the CAN-SPAM Act, this is a postal address used for all sent emails and can be changed on a per email basis. |
localize_sending_time |
The scheduled send_at time if set to be sent in the subscriber's time zone. |
send_at |
The timestamp representing when the Single-Email Campaign will be delivered. |
bcc |
A list of emails designated to receive a blind copy of the Single-Email Campaign. |
created_at |
A read-only Drip generated timestamp for when the Single-Email Campaign was first created. |
href |
The url designated for retrieving the account record via the REST API. |
subject |
The Single-Email Campaign's subject. |
html_body |
The HTML content used in the email's body. |
text_body |
The plain text content used in the email's body. |
links |
An object containing the account's REST API URL. |
List all Single-Email Campaigns
To list Single-Email Campaigns in an account:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/broadcasts" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
response = client.broadcasts
if response.success?
puts response.body["broadcasts"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const options = { status: "sent" };
client.listBroadcasts(options)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The broadcasts property is an array of broadcast objects.
{
"links": { ... },
"meta": {
"page": 1,
"sort": "created_at",
"direction": "asc",
"count": 5,
"total_pages": 1,
"total_count": 5,
"status": "all"
},
"broadcasts": [ ... ]
}
HTTP Endpoint
GET /v2/:account_id/broadcasts
Arguments
| Key | Description |
|---|---|
status |
Optional. Filter by one of the following statuses: draft, scheduled, or sent. Defaults to all. |
sort |
Optional. Sort results by one of these fields: created_at, send_at, or name. Defaults to created_at. |
direction |
Optional. Filter sort direction with: asc or desc. Defaults to asc. |
Fetch a Single-Email Campaign
To fetch a specific Single-Email Campaign:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/broadcasts/BROADCAST_ID" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
broadcast_id = 9999999
response = client.broadcast(broadcast_id)
if response.success?
puts response.body
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const broadcastId = 9998888;
client.fetchBroadcast(broadcastId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The broadcasts property is an array of one broadcast object.
{
"links": { ... },
"broadcasts": [{ ... }]
}
HTTP Endpoint
GET /v2/:account_id/broadcasts/:broadcast_id
Arguments
None.
Email Series Campaigns
Email Series Campaigns are represented as follows:
{
"id": "123456",
"status": "active",
"name": "SEO Email Course",
"from_name": "John Doe",
"from_email": "john@example.com",
"postal_address": "123 Anywhere St\nFresno, CA 99999",
"minutes_from_midnight": 440,
"localize_sending_time": true,
"days_of_the_week_mask": "0111110",
"start_immediately": true,
"double_optin": true,
"send_to_confirmation_page": false,
"use_custom_confirmation_page": false,
"confirmation_url": null,
"notify_subscribe_email": "derrick@getdrip.com",
"notify_unsubscribe_email": "derrick@getdrip.com",
"bcc": null,
"email_count": 10,
"active_subscriber_count": 320,
"unsubscribed_subscriber_count": 5,
"created_at": "2013-06-21T10:31:58Z",
"href": "https://api.getdrip.com/v2/9999999/campaigns/123456",
"links": {
"account": "9999999",
"forms": ["888"]
}
}
All responses containing Email Series Campaign data also include the following top-level link data:
{
"links": {
"campaigns.account": "https://api.getdrip.com/v2/accounts/{campaigns.account}",
"campaigns.form": "https://api.getdrip.com/v2/{campaigns.account}/forms/{campaigns.forms}",
"campaigns.subscribers": "https://api.getdrip.com/v2/{campaigns.account}/campaigns/{campaigns.id}/subscribers"
}
}
Properties
| Property | Description |
|---|---|
id |
A read-only Drip generated unique id used to identify each Email Series Campaign record. |
status |
Returns whether the Email Series Campaign is active, paused or in draft. |
name |
The private name given to the Email Series Campaign. |
from_name |
A "from name" that appears in your sent emails. This setting overrides the account's default from name. |
from_email |
A "from email" that appears in your sent emails. This setting overrides the account's default from email. |
postal_address |
As required by the CAN-SPAM Act, this is a postal address used for all sent emails. |
minutes_from_midnight |
The number of minutes after midnight for the time of day set for email sending. |
localize_sending_time |
The scheduled send_at time if set to be sent in the subscriber's time zone. |
days_of_the_week_mask |
A representation of the days of week when emails are set to be sent. For example, 1111100 represents sending enabled only for Mondays to Fridays while 1111111 represents sending enabled for all days of the week. |
start_immediately |
Returns true if the first email in the Email Series Campaign is set to be delivered immediately after a Email Series Campaign subscription. |
double_optin |
Returns true if double opt-in is enabled for the Email Series Campaign. |
send_to_confirmation_page |
Deprecated |
use_custom_confirmation_page |
Deprecated |
post_confirmation_url |
Deprecated |
notify_subscribe_email |
An email address set that receives a notification whenever a subscriber subscribes via a form submission. |
notify_unsubscribe_email |
An email address set that receives a notification whenever a subscriber unsubscribes via their subscription management page. |
bcc |
A blind copy email address set for all Email Series Campaign email deliveries. |
email_count |
Returns a count of all emails associated with the Email Series Campaign. Includes all email statuses. |
active_subscriber_count |
Returns a count of all subscribers who are actively subscribed to the Email Series Campaign. |
unsubscribed_subscriber_count |
Returns a count of all subscribers who unsubscribed from the Email Series Campaign via a delivered email. |
created_at |
A timestamp representing when the Email Series Campaign was first created. |
href |
The url designated for retrieving the Email Series Campaign record via the REST API. |
links |
An object containing the REST API URL for the account, any associated Email Series Campaign forms and subscribers subscribed to the Email Series Campaign. |
forms |
An object containing the associated form created for the Email Series Campaign. This is only populated if a form is created for the Email Series Campaign. Refer to Forms for an overview of the properties returned here. |
List all Email Series Campaigns
To list all Email Series Campaigns:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/campaigns" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
response = client.campaigns
if response.success?
puts response.body["campaigns"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const options = { status: "active" };
client.listCampaigns(options)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The campaigns property is an array of campaign objects.
{
"links": { ... },
"meta": {
"page": 1,
"sort": "created_at",
"direction": "asc",
"count": 5,
"total_pages": 1,
"total_count": 5,
"status": "all"
},
"campaigns": [ ... ]
}
HTTP Endpoint
GET /v2/:account_id/campaigns
Arguments
| Key | Description |
|---|---|
status |
Optional. Filter by one of the following statuses: draft, active, or paused. Defaults to all. |
sort |
Optional. Sort results by one of these fields: created_at or name. Defaults to created_at. |
direction |
Optional. Filter sort direction with: asc or desc. Defaults to asc. |
Fetch an Email Series Campaign
To fetch a specific Email Series Campaign:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/campaigns/CAMPAIGN_ID" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
campaign_id = 9999999
response = client.campaign(campaign_id)
if response.success?
puts response.body
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const campaignId = 9998888;
client.fetchCampaign(campaignId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The campaigns property is an array of campaign objects.
# The forms property is an array of forms that feed directly into to the campaign.
{
"links": { ... },
"campaigns": [{ ... }],
"linked": {
"forms": [{ ... }]
}
}
HTTP Endpoint
GET /v2/:account_id/campaigns/:campaign_id
Arguments
None.
Activate an Email Series Campaign
To activate an Email Series Campaign:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/campaigns/CAMPAIGN_ID/activate" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
campaign_id = 9999999
response = client.activate_campaign(campaign_id)
if response.success?
puts response.body
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const campaignId = 9998888;
client.activateCampaign(campaignId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
Responds with a
204 No Contentif successful. If the Email Series Campaign cannot be activated, returns a422 Unprocessable Entity.
HTTP Endpoint
POST /v2/:account_id/campaigns/:campaign_id/activate
Arguments
None.
Pause an Email Series Campaign
To pause an Email Series Campaign:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/campaigns/CAMPAIGN_ID/pause" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
campaign_id = 9999999
response = client.pause_campaign(campaign_id)
if response.success?
puts response.body
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const campaignId = 9998888;
client.pauseCampaign(campaignId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
Responds with a
204 No Contentif successful. If the Email Series Campaign cannot be paused, returns a422 Unprocessable Entity.
HTTP Endpoint
POST /v2/:account_id/campaigns/:campaign_id/pause
Arguments
None.
List all subscribers subscribed to an Email Series Campaign
To list subscribers on an Email Series Campaign:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/campaigns/CAMPAIGN_ID/subscribers" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
campaign_id = 9999999
response = client.campaign_subscribers(campaign_id)
if response.success?
puts response.body["subscribers]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const campaignId = 9998888;
client.listAllSubscribesToCampaign(campaignId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The subscribers property is an array of subscriber objects.
{
"links": { ... },
"meta": {
"page": 1,
"direction": "desc",
"count": 20,
"total_pages": 1,
"total_count": 20
},
"subscribers": [ ... ]
}
HTTP Endpoint
GET /v2/:account_id/campaigns/:campaign_id/subscribers
Arguments
| Key | Description |
|---|---|
status |
Optional. The status to filter by: active, unsubscribed, or removed. Defaults to active. |
page |
Optional. The page number. Defaults to 1. |
direction |
Optional. The direction to sort the results for created_at: asc or desc. Defaults to desc. |
per_page |
Optional. The number of records to be returned on each page. Defaults to 100. Maximum 1000. |
Subscribe someone to an Email Series Campaign
To start a subscriber on an Email Series Campaign:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/campaigns/CAMPAIGN_ID/subscribers" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"subscribers": [{
"email": "john@acme.com",
"utc_offset": 660,
"double_optin": true,
"starting_email_index": 0,
"reactivate_if_removed": true,
"custom_fields": {
"shirt_size": "Medium"
}
}]
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
campaign_id = 9999999
email = "someone@example.com"
options = {
time_zone: "America/Los_Angeles",
custom_fields: {
name: "Jane Doe"
}
}
response = client.subscribe(email, campaign_id, options)
if response.success?
# ...
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const campaignId = 9998888;
const payload = {
subscribers: [{
email: "someone@example.com",
time_zone: "Asia/Kuala_Lumpur",
custom_fields: {
name: "Jane Doe"
}
}]
}
client.subscribeToCampaign(campaignId, payload)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The subscribers property is an array of one object.
{
"links": { ... },
"subscribers": [{ ... }]
}
HTTP Endpoint
POST /v2/:account_id/campaigns/:campaign_id/subscribers
Arguments
| Key | Description |
|---|---|
email |
Required. The subscriber's email address. |
user_id |
Optional. A unique identifier for the user in your database, such as a primary key. |
time_zone |
Optional. The subscriber's time zone (in Olson format). Defaults to Etc/UTC |
double_optin |
Optional. If true, the double opt-in confirmation email is sent; if false, the confirmation email is skipped. Defaults to the value set on the Email Series Campaign. |
starting_email_index |
Optional. The index (zero-based) of the email to send first. Defaults to 0. |
custom_fields |
Optional. An Object containing custom field data. E.g. { "shirt_size": "Medium" }. |
tags |
Optional. An Array containing one or more tags. E.g. ["Customer", "SEO"]. |
reactivate_if_removed |
Optional. If true, re-subscribe the subscriber to the Email Series Campaign if there is a removed subscriber in Drip with the same email address; otherwise, respond with 422 Unprocessable Entity. Defaults to true. |
prospect |
Optional. A Boolean specifiying whether we should attach a lead score to the subscriber (when lead scoring is enabled). Defaults to true.
Note: This flag used to be called potential_lead, which we will continue to accept for backwards compatibility. |
base_lead_score |
Optional. An Integer specifying the starting value for lead score calculation for this subscriber. Defaults to 30. |
eu_consent |
Optional. A String specifying whether the subscriber granted or denied GDPR consent. |
eu_consent_message |
Optional. A String containing the message the subscriber granted or denied their consent to. |
List all of a subscriber's Email Series Campaign subscriptions
To list Email Series Campaign subscriptions for a subscriber:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/subscribers/SUBSCRIBER_ID/campaign_subscription" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
subscriber_id = "bihfwo84teh35dgt99"
response = client.campaign_subscriptions(subscriber_id)
if response.success?
puts response.body["campaign_subscriptions"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const subscriberId = "iuyfgfweufgr9hvrugegff";
client.subscriberCampaignSubscriptions(subscriberId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The Email Series Campaign subscriptions property is an array of campaign subscription objects.
{
"links": {
"campaign_subscriptions.account": "https://api.getdrip.com/v2/accounts/{campaign_subscriptions.account}",
"campaign_subscriptions.subscriber": "https://api.getdrip.com/v2/subscribers/{campaign_subscriptions.subscriber}"
},
"meta": {
"page": 1,
"count": 5,
"total_pages": 1,
"total_count": 5
},
"campaign_subscriptions": [{
"id": "123456",
"campaign_id": "999999",
"status": "active",
"is_complete": false,
"lap": 1,
"last_sent_email_index": 0,
"last_sent_email_at": "2016-03-25T11:00:00Z",
"links": {
"account": "9999999",
"subscriber": "z1togz2hcjrkpp5treip"
}
}]
}
HTTP Endpoint
GET /v2/:account_id/subscribers/:subscriber_id/campaign_subscriptions
Arguments
None.
Custom Fields
List all custom field identifiers used in an account
To list all custom fields:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/custom_field_identifiers" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
response = client.custom_fields
if response.success?
puts response.body["custom_field_identifiers"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
client.listAllCustomFields()
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
{
"custom_field_identifiers": [ "first_name", "last_name" ]
}
Properties
| Property | Description |
|---|---|
custom_field_identifiers |
Returns a list of all active custom field identifiers used in the target account. |
HTTP Endpoint
GET /v2/:account_id/custom_field_identifiers
Arguments
None.
Conversions
Conversions are represented as follows:
{
"id": "99999",
"status": "active",
"name": "Trial Signup",
"url": "/receipt",
"default_value": 2000,
"counting_method": "one_per_visitor",
"created_at": "2013-06-21T10:31:58Z",
"href": "https://api.getdrip.com/v2/9999999/goals/99999",
"links": {
"account": "9999999"
}
}
All responses containing conversion data also include the following top-level link data:
{
"links": {
"goals.account": "https://api.getdrip.com/v2/accounts/{goals.account}"
}
}
Properties
| Property | Description |
|---|---|
id |
A read-only Drip generated unique id used to identify each conversion record. |
status |
Returns whether the conversion is enabled or disabled. |
name |
The private name given to the conversion. |
url |
A URL used for detecting and recording conversions. |
default_value |
A default value assigned to a tracked conversion. Conversion values must be less than 2,147,483,647. |
counting_method |
Set either as one_per_visitor or all and determines whether a maximum of one conversion is counted per person or all. |
created_at |
A timestamp representing when the conversion was first created. |
href |
The url designated for retrieving the conversion record via the REST API. |
links |
An object containing the REST API URL for the account. |
See the Events API for recording conversion events.
List all conversions
To list all conversions in an account:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/goals" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
response = client.conversions
if response.success?
puts response.body["goals"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const options = { status: "active" };
client.listConversions(options)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The goals property is an array of conversion goal objects.
{
"links": { ... },
"goals": [ ... ]
}
HTTP Endpoint
GET /v2/:account_id/goals
Arguments
| Key | Description |
|---|---|
status |
Optional. The status to filter by: active, disabled, or all. Defaults to all. |
sort |
Optional. Sort results by one of these fields: created_at or name. Defaults to created_at. |
direction |
Optional. Filter sort direction with: asc or desc. Defaults to asc. |
Fetch a conversion
To fetch a conversion:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/goals/CONVERSION_ID" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
conversion_id = 9999999
response = client.conversion(conversion_id)
if response.success?
puts response.body["goals"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const conversionId = 8889999;
client.fetchConversion(conversionId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The goals property is an array of one conversion goal object.
{
"links": { ... },
"goals": [{ ... }]
}
HTTP Endpoint
GET /v2/:account_id/goals/:conversion_id
Arguments
None.
Events
Record an event
To create or update a subscriber:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/events" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"events": [{
"email": "john@acme.com",
"action": "Logged in",
"properties": {
"affiliate_code": "XYZ"
},
"occurred_at": "2014-03-22T03:00:00Z"
}]
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
email = "someone@example.com"
action = "Docked with space station"
properties = {
station: "Mars Endeavor"
}
response = client.track_event(email, action, properties)
if response.success?
# ...
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const payload = {
email: "john@acme.com",
action: "Logged in",
properties: {
affiliate_code: "XYZ"
}
};
client.recordEvent(payload)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
Responds with a
204 No Contentif successful.
If you need to create or update a collection of events at once, use the Batch API instead.
HTTP Endpoint
POST /v2/:account_id/events
Arguments
| Key | Description |
|---|---|
email |
Optional. The subscriber's email address. Either email or id must be included. |
id |
Optional. The subscriber's Drip id. Either email or id must be included. |
action |
Required. The name of the action taken. E.g. "Logged in" |
prospect |
Optional. A Boolean specifiying whether we should attach a lead score to the subscriber (when lead scoring is enabled). Defaults to true.
Note: This flag used to be called potential_lead, which we will continue to accept for backwards compatibility. |
properties |
Optional. An Object containing custom event properties. If this event is a conversion, include the value (in cents) in the in the properties with a value key.
Conversion values must be less than 2,147,483,647.
|
occurred_at |
Optional. The String time at which the event occurred in ISO-8601 format. Defaults to the current time. |
List all custom events actions used in an account
To list custom event actions:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/event_actions" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
response = client.event_actions
if response.success?
puts response["event_actions"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const options = { per_page: 200 };
client.listEventActions(options)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
{
"meta": {
"count": 2,
"page": 1,
"total_count": 2,
"total_pages": 1
},
"event_actions": [
"Ate a sandwich",
"Started a trial"
]
}
HTTP Endpoint
GET /v2/:account_id/event_actions
Arguments
| Key | Description |
|---|---|
page |
Optional. The page number. Defaults to 1. |
per_page |
Optional. The number of records to be returned on each page. Defaults to 100. Maximum 1000. |
Forms
Forms are represented as follows:
{
"id": "77777",
"href": "https://api.getdrip.com/v2/9999999/forms/77777",
"headline": "Long Tail SEO Course",
"description": "Get our FREE email course",
"button_text": "Sign Up!",
"confirmation_heading": "Thank you for subscribing",
"confirmation_text": "Please click the link in your email",
"send_ga_event": true,
"seconds_before_popup": 5,
"days_between_popup": 5,
"days_between_popup_after_close": 10,
"orientation": "bottom_right_tab",
"opacity": 0.8,
"show_labels": false,
"primary_color": "#333333",
"secondary_color": "#d8ab93",
"is_widget_enabled": true,
"whitelist": [ "/landing", "/public" ],
"blacklist": [],
"is_whitelist_enabled": true,
"is_blacklist_enabled": false,
"hide_on_mobile": false,
"is_embeddable": true,
"created_at": "2013-06-21T10:31:58Z",
"links": {
"account": "9999999"
}
}
All responses containing form data also include the following top-level link data:
{
"links": {
"forms.account": "https://api.getdrip.com/v2/accounts/{forms.account}"
}
}
Properties
| Property | Description |
|---|---|
id |
A read-only Drip generated unique id used to identify each form record. |
href |
The url designated for retrieving the form record via the REST API. |
headline |
The visible headline on the form widget or embedded form. |
description |
A description shown in the body of the form widget or in the embedded form. |
button_text |
The text shown on the submission button for the form. |
confirmation_heading |
A heading shown after a subscriber submits the form. |
confirmation_text |
The text shown after a subscriber submits the form. |
send_ga_event |
Returns true if an event is sent to Google Analytics upon submission. |
seconds_before_popup |
A delay in seconds before the form widget is displayed. |
days_between_popup |
A delay in days between each appearance of the form widget. |
days_between_popup_after_close |
A delay in days between each appearance of the form widget after a visitor closes the form. |
orientation |
The position on the page where the form widget is displayed. Possible values are bottom_left_tab, bottom_right_tab, side_left_tab, side_right_tab, embedded or lightbox. |
opacity |
The opacity set for form field labels. |
show_labels |
Returns true if form field labels are shown above text boxes. |
primary_color |
The tab color for the form. |
secondary_color |
The headline color for the form. |
is_widget_enabled |
Returns true if the form widget is enabled and shown. |
whitelist |
An array of URL paths where the form is shown. |
blacklist |
An array of URL paths where the form is hidden. |
is_whitelist_enabled |
Returns true if whitelisted URLs are set. |
is_blacklist_enabled |
Returns true if blacklisted URLs are set. |
hide_on_mobile |
Returns true if the form widget is disabled for mobile devices. |
is_embeddable |
Deprecated |
created_at |
A timestamp representing when the form was first created. |
links |
An object containing the REST API URL for the account. |
List all forms
To list all forms in an account:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/forms" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
response = client.forms
if response.success?
puts response.body["forms"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
client.listForms()
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The forms property is an array of form objects.
{
"links": { ... },
"forms": [ ... ]
}
HTTP Endpoint
GET /v2/:account_id/forms
Arguments
None.
Fetch a form
To fetch a specific form:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/forms/FORM_ID" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
form_id = 9999999
response = client.form(form_id)
if response.success?
puts response.body["forms"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const formId = 9998888;
client.fetchForm(formId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The forms property is an array of one form object.
{
"links": { ... },
"forms": [{ ... }]
}
HTTP Endpoint
GET /v2/:account_id/forms/:form_id
Arguments
None.
Orders (Legacy)
Orders are represented as follows:
{
"id": "9999999",
"provider": "shopify",
"upstream_id": "abcdef",
"identifier": "Order_123456",
"amount": 4900,
"tax": 100,
"fees": 0,
"discount": 0,
"permalink": "http://myorders.com/orders/123456",
"currency_code": "USD",
"properties": {
"shirt_size": "Medium",
"color": "red"
},
"occurred_at": "2013-06-21T10:31:58Z",
"closed_at": "2013-06-21T10:35:58Z",
"cancelled_at": null,
"financial_state": "paid",
"fulfillment_state": "fulfilled",
"billing_address": {
"name": "Bill Billington",
"first_name": "Bill",
"last_name": "Billington",
"company": "Bills R US",
"address_1": "123 Bill St.",
"address_2": "Apt. B",
"city": "Billtown",
"state": "CA",
"zip": "01234",
"country": "United States",
"phone": "555-555-5555",
"email": "bill@bills.com"
},
"shipping_address": {
"name": "Ship Shippington",
"first_name": "Ship",
"last_name": "Shipington",
"company": "Shipping 4 Less",
"address_1": "123 Ship St.",
"address_2": "null",
"city": "Shipville",
"state": "CA",
"zip": "01234",
"country": "United States",
"phone": "555-555-5555",
"email": "ship@shipping.com"
},
"items": [{
"id": "8888888",
"product_id": "765432",
"sku": "4444",
"amount": 4900,
"name": "Canoe",
"quantity": 1,
"upstream_id": "hijkl",
"upstream_product_id": "opqrs",
"upstream_product_variant_id": "zyxwv",
"price": 4900,
"tax": 100,
"fees": 0,
"discount": 100,
"taxable": true,
"properties": {
"color": "black"
}
}],
"links": {
"account": "9999999",
"subscriber": "5555555"
}
}
Properties
| Property | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id |
A read-only Drip generated unique id used to identify each order record. | ||||||||||||||||||||||||||||||
provider |
The identifier for the provider from which the order data was received in lower snake cased form. For example, shopify or my_store |
||||||||||||||||||||||||||||||
amount |
The total amount of the order in cents (e.g. if the order was $49.99, set the amount to 4999). |
||||||||||||||||||||||||||||||
tax |
The tax on the order in cents (e.g. if the order was $1.00, set the tax to 100). |
||||||||||||||||||||||||||||||
fees |
The fees on the order in cents (e.g. if the order was $1.00, set the fees to 100). |
||||||||||||||||||||||||||||||
discount |
The discount on the order in cents (e.g. if the order was $5.00, set the discount to 500). |
||||||||||||||||||||||||||||||
permalink |
A URL for the human-readable interface to view the order details. | ||||||||||||||||||||||||||||||
currency_code |
The alphabetic ISO 4217 code for the currency of the purchase. | ||||||||||||||||||||||||||||||
upstream_id |
A unique, internal id for the order (generally the primary key generated by the order management system). | ||||||||||||||||||||||||||||||
identifier |
A unique, external identifier for the order. This will be displayed in the Drip UI and should correspond to what a customer sees on invoices, email confirmations, etc. | ||||||||||||||||||||||||||||||
properties |
An Object containing properties about the order. E.g. { "size": "large" } |
||||||||||||||||||||||||||||||
occurred_at |
The String time at which the order occurred in ISO-8601 format. Defaults to the current time. | ||||||||||||||||||||||||||||||
closed_at |
The String time at which the order closed in ISO-8601 format. | ||||||||||||||||||||||||||||||
cancelled_at |
The String time at which the order was cancelled in ISO-8601 format. For an order that was not cancelled, this will be nil. |
||||||||||||||||||||||||||||||
financial_state |
The financial status of the order. One of the following values: pending, authorized, partially_paid, paid, partially_refunded, refunded, voided. |
fulfillment_state |
The fulfillment status of the order. One of the following values: not_fulfilled, partially_fulfilled, fulfilled. |
||||||||||||||||||||||||||||
billing_address |
An object containing billing address information.
|
||||||||||||||||||||||||||||||
shipping_address |
An object containing shipping address information.
|
||||||||||||||||||||||||||||||
items |
An Array of objects containing information about specific order items.
|
||||||||||||||||||||||||||||||
links |
An object containing the REST API URL for the account. |
Create or update an order
To create or update an order for a subscriber:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
order = {
provider: "shopify",
upstream_id: "abcdef",
identifier: "Order_123456",
amount: 4900,
tax: 100,
fees: 0,
discount: 0,
permalink: "http://myorders.com/orders/123456",
currency_code: "USD",
properties: {
shirt_size: "Medium",
color: "red"
},
occurred_at: "2013-06-21T10:31:58Z",
closed_at: "2013-06-21T10:35:58Z",
financial_state: "paid",
fulfillment_state: "fulfilled",
billing_address: {
name: "Bill Billington",
first_name: "Bill",
last_name: "Billington",
company: "Bills R US",
address_1: "123 Bill St.",
address_2: "Apt. B",
city: "Billtown",
state: "CA",
zip: "01234",
country: "United States",
phone: "555-555-5555",
email: "bill@bills.com"
},
shipping_address: {
name: "Ship Shippington",
first_name: "Ship",
last_name: "Shipington",
company: "Shipping 4 Less",
address_1: "123 Ship St.",
address_2: "null",
city: "Shipville",
state: "CA",
zip: "01234",
country: "United States",
phone: "555-555-5555",
email: "ship@shipping.com"
},
items: [{
id: "8888888",
product_id: "765432",
sku: "4444",
amount: 4900,
name: "Canoe",
quantity: 1,
upstream_id: "hijkl",
upstream_product_id: "opqrs",
upstream_product_variant_id: "zyxwv",
price: 4900,
tax: 100,
fees: 0,
discount: 100,
taxable: true,
properties: {
color: "black"
}
}]
}
response = client.create_or_update_order("john@acme.com", order)
if response.success?
# ...
end
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/orders" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-H "Content-Type: application/json" \
-u YOUR_API_KEY: \
-d @- << EOF
{
"orders": [{
"email": "john@acme.com",
"provider": "shopify",
"upstream_id": "abcdef",
"identifier": "Order_123456",
"amount": 4900,
"tax": 100,
"fees": 0,
"discount": 0,
"permalink": "http://myorders.com/orders/123456",
"currency_code": "USD",
"properties": {
"shirt_size": "Medium",
"color": "red"
},
"occurred_at": "2013-06-21T10:31:58Z",
"closed_at": "2013-06-21T10:35:58Z",
"financial_state": "paid",
"fulfillment_state": "fulfilled",
"billing_address": {
"name": "Bill Billington",
"first_name": "Bill",
"last_name": "Billington",
"company": "Bills R US",
"address_1": "123 Bill St.",
"address_2": "Apt. B",
"city": "Billtown",
"state": "CA",
"zip": "01234",
"country": "United States",
"phone": "555-555-5555",
"email": "bill@bills.com"
},
"shipping_address": {
"name": "Ship Shippington",
"first_name": "Ship",
"last_name": "Shipington",
"company": "Shipping 4 Less",
"address_1": "123 Ship St.",
"address_2": "null",
"city": "Shipville",
"state": "CA",
"zip": "01234",
"country": "United States",
"phone": "555-555-5555",
"email": "ship@shipping.com"
},
"items": [{
"id": "8888888",
"product_id": "765432",
"sku": "4444",
"amount": 4900,
"name": "Canoe",
"quantity": 1,
"upstream_id": "hijkl",
"upstream_product_id": "opqrs",
"upstream_product_variant_id": "zyxwv",
"price": 4900,
"tax": 100,
"fees": 0,
"discount": 100,
"taxable": true,
"properties": {
"color": "black"
}
}]
}]
}
EOF
Responds with a
202 Acceptedand an empty JSON response:
{}
When an order is created, the subscriber's lifetime_value attribute
will be automatically incremented by the total amount of the order.
To update an existing order, include the provider and upstream_id for that order in the payload.
Note: A matching subscriber record must already be present in Drip before an order can be created.
HTTP Endpoint
POST /v2/:account_id/orders
Arguments
| Property | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
email |
Optional. The email address of the order's subscriber. Either email or id must be included. |
||||||||||||||||||||||||||||||
id |
Optional. The Drip id of the order's subscriber. Either email or id must be included. |
||||||||||||||||||||||||||||||
amount |
Required. The total amount of the order in cents (e.g. if the order was $49.99, set the amount to 4999). |
||||||||||||||||||||||||||||||
provider |
Optional. Required for updates. The identifier for the provider from which the order data was received in lower snake cased form. For example, shopify or my_store. Used to identify the order for updates. |
||||||||||||||||||||||||||||||
tax |
Optional. The tax on the order in cents (e.g. if the order was $1.00, set the tax to 100). |
||||||||||||||||||||||||||||||
fees |
Optional. The fees on the order in cents (e.g. if the order was $1.00, set the fees to 100). |
||||||||||||||||||||||||||||||
discount |
Optional. The discount on the order in cents (e.g. if the order was $5.00, set the discount to 500). |
||||||||||||||||||||||||||||||
permalink |
Optional. A URL for the human-readable interface to view the order details. | ||||||||||||||||||||||||||||||
currency_code |
Optional. The alphabetic ISO 4217 code for the currency of the purchase. | ||||||||||||||||||||||||||||||
upstream_id |
Optional. Required for updates. A unique, internal id for the order (generally the primary key generated by the order management system). Used to identify the order for updates. | ||||||||||||||||||||||||||||||
identifier |
Optional. A unique, external identifier for the order. This will be displayed in the Drip UI and should correspond to what a customer sees on invoices, email confirmations, etc. | ||||||||||||||||||||||||||||||
properties |
Optional. An Object containing properties about the order. E.g. { "size": "large" } |
||||||||||||||||||||||||||||||
occurred_at |
Optional. The String time at which the order occurred in ISO-8601 format. Defaults to the current time. | ||||||||||||||||||||||||||||||
closed_at |
Optional. The String time at which the order closed in ISO-8601 format. | ||||||||||||||||||||||||||||||
cancelled_at |
Optional. The String time at which the order was cancelled in ISO-8601 format. For an order that was not cancelled, this will be nil. |
||||||||||||||||||||||||||||||
financial_state |
Optional. The financial status of the order. One of the following values: pending, authorized, partially_paid, paid, partially_refunded, refunded, voided. |
fulfillment_state |
Optional. The fulfillment status of the order. One of the following values: not_fulfilled, partially_fulfilled, fulfilled. |
||||||||||||||||||||||||||||
billing_address |
Optional. An object containing billing address information.
|
||||||||||||||||||||||||||||||
shipping_address |
Optional. An object containing shipping address information.
|
||||||||||||||||||||||||||||||
items |
Optional. An Array of objects containing information about specific order items.
|
Create or update a refund
To create or update a refund for an order:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/refunds" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"refunds": [{
"provider": "shopify",
"order_upstream_id": "abcdef",
"upstream_id": "tuvwx",
"amount": 2000,
"note": "Incorrect size",
"processed_at": "2013-06-22T10:41:11Z"
}]
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
refund = {
provider: "shopify",
order_upstream_id: "abcdef",
upstream_id: "tuvwx",
amount: 2000,
note: "Incorrect size",
processed_at: "2013-06-22T10:41:11Z"
}
response = client.create_or_update_refund(refund)
if response.success?
# ...
end
Responds with a
202 Acceptedand an empty JSON response:
{}
When a refund is created, the subscriber's lifetime_value attribute
will be automatically decremented by the total amount of the refund.
To update an existing refund, include the upstream_id for that refund in the payload.
HTTP Endpoint
POST /v2/:account_id/refunds
Arguments
| Property | Description |
|---|---|
provider |
Required. The provider for the Order being refunded. |
order_upstream_id |
Required. The upstream_id for the Order being refunded. |
amount |
Required. The amount of the refund. |
upstream_id |
Optional. Required for updates. The unique id of refund in the order management system. Used to identify the refund for updates. |
note |
Optional. A note about the refund. |
processed_at |
Optional. The String time at which the refund was processed in ISO-8601 format. |
Order events
Drip automatically records a number of events in the life cycle of an order. You can find
triggers for these events by selecting Drip Order API from the provider dropdown in your Drip automation.
| Event | Description |
|---|---|
Placed an order |
This event is fired when an order is created. |
Updated an order |
This event is fired when an existing order is updated. |
Paid an order |
This event is fired when the financial_state on an order is set to paid. |
Fulfilled an order |
This event is fired when the fulfillment_state on an order is set to fulfilled. |
Canceled an order |
This event is fired when the cancelled_at time on an order is set. |
Refunded an order |
This event is fired when a refund is created for an order. |
Subscribers
Subscribers are represented as follows:
{
"id": "z1togz2hcjrkpp5treip",
"status": "active",
"email": "john@acme.com",
"first_name": "John",
"last_name": "Doe",
"address1": "123 Main St.",
"address2": "Suite 200",
"city": "Los Angeles",
"state": "CA",
"zip": "90210",
"country": "US",
"phone": "555-555-5555",
"sms_number": "+16125551212",
"sms_consent": true,
"eu_consent": "granted",
"time_zone": "America/Los_Angeles",
"utc_offset": -440,
"visitor_uuid": "sa8f7sdf78sdsdahf788d7asf8sd",
"custom_fields": {
"shirt_size": "Medium"
},
"tags": ["Customer", "SEO"],
"ip_address": "111.111.111.11",
"user_agent": "Chrome/36.0.1985.143",
"original_referrer": "http://www.getdrip.com",
"landing_url": "https://www.getdrip.com/docs/rest-api",
"prospect": true,
"lead_score": 72,
"lifetime_value": 10000,
"created_at": "2013-06-21T10:31:58Z",
"href": "https://api.getdrip.com/v2/9999999/subscribers/12345",
"user_id": "12345",
"base_lead_score": 30,
"links": {
"account": "9999999"
}
}
All responses containing subscriber data also include the following top-level link data:
{
"links": {
"subscribers.account": "https://api.getdrip.com/v2/accounts/{subscribers.account}"
}
}
Note: All subscriber API endpoints only work with your active people. Attempting to modify or delete an inactive person will result in an error.
Properties
| Property | Description |
|---|---|
id |
A read-only Drip generated unique id used to identify each subscriber record. |
status |
The subscriber's status whether active or unsubscribed. |
initial_status |
The subscriber's known status whether active or unsubscribed. To be used instead of status if subscriber's status is unchanged. |
email |
The subscriber's email address. |
first_name |
The subscriber's first name. |
last_name |
The subscriber's last name. |
address1 |
The subscriber's mailing address. |
address2 |
An additional field for the subscriber's mailing address. |
city |
The city, town, or village in which the subscriber resides. |
state |
The region in which the subscriber resides. Typically a province, a state, or a prefecture. |
zip |
The postal code in which the subscriber resides, also known as zip, postcode, Eircode, etc. |
country |
The country in which the subscriber resides. |
phone |
The subscriber's primary phone number. |
sms_number |
Optional. String. The subscriber's mobile phone number in E.164 formatting. E.g. "+16125551212". Only US-based numbers are supported at this time. |
sms_consent |
Optional. Boolean. true if the person has granted consent to receive marketing and other communication via SMS; false otherwise. Default: false. If you’re unsure whether or not you have gained legal SMS consent, check out our TCPA requirements article. |
eu_consent |
A string describing whether the subscriber GDPR consent is granted, denied, or unknown. |
time_zone |
The subscriber's time zone (in Olson format). |
utc_offset |
The UTC offset in minutes relative to UTC/GMT. |
visitor_uuid |
A read-only Drip generated unique id used to identify each subscriber's visitor record if available. |
custom_fields |
An Object containing custom field data. E.g. { "shirt_size": "Medium" }. |
tags |
An Array containing one or more tags. E.g. ["Customer", "SEO"]. |
ip_address |
The subscriber's IP address if available. |
user_agent |
The subscriber's browser User Agent if available. |
original_referrer |
The initial referral URL when the subscriber first visited your site if available. |
landing_url |
The first page visited by the subscriber if available. |
prospect |
Returns true if the subscriber is marked as a lead. |
lead_score |
The subscriber's lead score. |
lifetime_value |
The subscriber's lifetime value in cents. |
created_at |
A timestamp representing when the subscriber record was first created. |
href |
The url designated for retrieving the subscriber record via the REST API. |
user_id |
A unique identifier for the user in your database, such as a primary key. |
base_lead_score |
An Integer specifying the starting value for lead score calculation for this subscriber. Defaults to 30. |
links |
An object containing the REST API URL for the account. |
Create or update a subscriber
To create or update a subscriber:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/subscribers" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-H 'Content-Type: application/json' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"subscribers": [{
"email": "john@acme.com",
"time_zone": "America/Los_Angeles",
"custom_fields": {
"shirt_size": "Medium"
}
}]
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
subscriber_email = "john@acme.com"
options = {
time_zone: "America/Los_Angeles",
custom_fields: {
shirt_size: "Medium"
}
}
response = client.create_or_update_subscriber(subscriber_email, options)
if response.success?
puts response.body["subscribers"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const payload = {
email: "john@acme.com",
time_zone: "America/Los_Angeles",
custom_fields: {
shirt_size: "Medium"
}
};
client.createUpdateSubscriber(payload)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The subscribers property is an array of one object.
{
"links": { ... },
"subscribers": [{ ... }]
}
HTTP Endpoint
POST /v2/:account_id/subscribers
If you need to create or update a collection of subscribers at once, use our batch API instead.
Note: Concurrently updating the same subscriber via multiple API calls is not supported and will fail with a rate limit error and the message "Too many concurrent requests for the same subscriber". You should retry the call after a short wait period to let the other requests to the same subscriber complete. Triggering this rate limit does not mean you've consumed your overall API rate limited capacity.
Arguments
| Key | Description |
|---|---|
email |
Optional. The subscriber's email address. Either email or id or visitor_uuid must be included. |
id |
Optional. The subscriber's Drip id. Either email or id or visitor_uuid must be included. |
visitor_uuid |
Optional. The uuid for a subscriber's visitor record. Either email or id or visitor_uuid must be included. |
new_email |
Optional. A new email address for the subscriber. If provided and a subscriber with the email above does not exist, this address will be used to create a new subscriber. |
first_name |
Optional. The subscriber's first name. |
last_name |
Optional. The subscriber's last name. |
address1 |
Optional. The subscriber's mailing address. |
address2 |
Optional. An additional field for the subscriber's mailing address. |
city |
Optional. The city, town, or village in which the subscriber resides. |
state |
Optional. The region in which the subscriber resides. Typically a province, a state, or a prefecture. |
zip |
Optional. The postal code in which the subscriber resides, also known as zip, postcode, Eircode, etc. |
country |
Optional. The country in which the subscriber resides. |
phone |
Optional. The subscriber's primary phone number. |
sms_number |
Optional. String. The subscriber's mobile phone number in E.164 formatting. E.g. "+16125551212". Only US-based numbers are supported at this time. |
sms_consent |
Optional. Boolean. true if the person has granted consent to receive marketing and other communication via SMS; false otherwise. Default: false. If you’re unsure whether or not you have gained legal SMS consent, check out our TCPA requirements article. |
user_id |
Optional. A unique identifier for the user in your database, such as a primary key. |
time_zone |
Optional. The subscriber's time zone (in Olson format). Defaults to Etc/UTC |
lifetime_value |
Optional. The lifetime value of the subscriber (in cents). |
ip_address |
Optional. The subscriber's ip address E.g. "111.111.111.11" |
custom_fields |
Optional. An Object containing custom field data. E.g. { "shirt_size": "Medium" }. |
tags |
Optional. An Array containing one or more tags. E.g. ["Customer", "SEO"]. |
remove_tags |
Optional. An Array containing one or more tags to be removed from the subscriber. E.g. ["Customer", "SEO"]. |
prospect |
Optional. A Boolean specifiying whether we should attach a lead score to the subscriber (when lead scoring is enabled). Defaults to true.
Note: This flag used to be called potential_lead, which we will continue to accept for backwards compatibility. |
base_lead_score |
Optional. An Integer specifying the starting value for lead score calculation for this subscriber. Defaults to 30. |
eu_consent |
Optional. A String specifying whether the subscriber granted or denied GDPR consent. |
eu_consent_message |
Optional. A String containing the message the subscriber granted or denied their consent to. |
status |
Optional. A String specifying the subscriber's status: either active or unsubscribed. |
initial_status |
Optional. A String specifying the subscriber's known status: either active or unsubscribed. To be used if subscriber's status is unchanged. |
List all subscribers
To list subscribers:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/subscribers" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
response = client.subscribers
if response.success?
puts response.body["subscribers"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const options = { status: "active", subscribed_before: "2017-01-01T00:00:00Z" };
client.listSubscribers(options)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The subscribers property is an array subscriber objects.
# The meta property contains pagination information.
{
"links": { ... },
"meta": {
"page": 1,
"count": 5,
"total_pages": 1,
"total_count": 5
},
"subscribers": [{ ... }]
}
HTTP Endpoint
GET /v2/:account_id/subscribers
Arguments
| Key | Description |
|---|---|
status |
Optional. Filter by one of the following statuses: all, active, unsubscribed, active_or_unsubscribed or undeliverable. Defaults to active. |
tags |
Optional. A comma separated list of tags. When included, returns only subscribers who have at least one of the listed tags. |
subscribed_before |
Optional. A ISO-8601 datetime. When included, returns only subscribers who were created before the date. Eg. "2017-01-01T00:00:00Z" |
subscribed_after |
Optional. A ISO-8601 datetime. When included, returns only subscribers who were created after the date. Eg. "2016-01-01T00:00:00Z" |
page |
Optional. The page number. Defaults to 1. |
per_page |
Optional. The number of records to be returned on each page. Defaults to 100. Maximum 1000. |
Fetch a subscriber
To fetch a subscriber:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/subscribers/ID_OR_EMAIL_OR_VISITOR_UUID" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
subscriber_email = "john@acme.com"
response = client.subscriber(subscriber_email)
if response.success?
puts response.body["subscribers"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const idOrEmail = "someone@example.com";
client.fetchSubscriber(idOrEmail)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The subscribers property is an array of one object.
{
"links": { ... },
"subscribers": [{ ... }]
}
HTTP Endpoint
GET /v2/:account_id/subscribers/:id_or_email_or_visitor_uuid
Arguments
None.
Remove a subscriber from one or all Email Series Campaigns
To remove a subscriber from all Email Series s:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/subscribers/ID_OR_EMAIL/remove" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
##
# To remove a subscriber from all Email Series Campaigns:
##
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
subscriber_email = "john@acme.com"
response = client.unsubscribe(subscriber_email)
if response.success?
puts response.body["subscribers"]
end
##
# To remove a subscriber from a specific campaign:
##
subscriber_email = "john@acme.com"
options = {
campaign_id: 9999999
}
response = client.unsubscribe(subscriber_email, options)
if response.success?
puts response.body["subscribers"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const idOrEmail = "someone@example.com";
const campaignId = 9998888;
client.unsubscribeFromCampaign(idOrEmail, campaignId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
To remove a subscriber from a specific campaign:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/subscribers/ID_OR_EMAIL/remove?campaign_id=CAMPAIGN_ID" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
The response looks like this:
# The subscribers property is an array of one object.
{
"links": { ... },
"subscribers": [{ ... }]
}
HTTP Endpoint
POST /v2/:account_id/subscribers/:id_or_email/remove
This endpoint was previously labeled unsubscribe.
Arguments
| Key | Description |
|---|---|
campaign_id |
Optional. The Email Series Campaign from which to remove the subscriber. Defaults to all. |
Unsubscribe from all mailings
To unsubscribe a subscriber from all mailings:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/subscribers/ID_OR_EMAIL/unsubscribe_all" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
subscriber_email = "john@acme.com"
response = client.unsubscribe_from_all(subscriber_email)
if response.success?
puts response.body["subscribers"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const idOrEmail = "someone@example.com";
client.unsubscribeFromAllMailings(idOrEmail)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The subscribers property is an array of one object.
{
"links": { ... },
"subscribers": [{ ... }]
}
HTTP Endpoint
POST /v2/:account_id/subscribers/:id_or_email/unsubscribe_all
Arguments
None.
Delete a subscriber
To delete a subscriber:
curl -X DELETE "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/subscribers/ID_OR_EMAIL" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
subscriber_email = "john@acme.com"
response = client.delete_subscriber(subscriber_email)
if response.success?
# ...
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const idOrEmail = "someone@example.com";
client.deleteSubscriber(idOrEmail)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
Responds with
204 No Contentif successful.
HTTP Endpoint
DELETE /v2/:account_id/subscribers/:id_or_email
Arguments
None.
Tags
List all tags used in an account
To list all tags:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/tags" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
response = client.tags
if response.success?
puts response.body["tags"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
client.listAllTags()
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
{
"tags": [
"Customer",
"SEO"
]
}
Properties
| Property | Description |
|---|---|
email |
The subscriber's email address. |
tag |
The String tag to apply. E.g. "Customer". |
HTTP Endpoint
GET /v2/:account_id/tags
Arguments
None.
Apply a tag to a subscriber
To apply a tag to a specific subscriber:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/tags" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"tags": [{
"email": "john@acme.com",
"tag": "Customer"
}]
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
subscriber_email = "john@acme.com"
tag = "Customer"
response = client.apply_tag(subscriber_email, tag)
if response.success?
# ...
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const payload = {
tags: [{
email: "john@acme.com",
tag: "Customer"
}]
};
client.tagSubscriber(payload)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
Responds with a
201 Createdand an empty JSON response:
{}
HTTP Endpoint
POST /v2/:account_id/tags
Arguments
| Key | Description |
|---|---|
email |
The subscriber's email address. |
tag |
The String tag to apply. E.g. "Customer" |
Remove a tag from a subscriber
To apply a tag to a specific subscriber:
curl -X DELETE "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/subscribers/ID_OR_EMAIL/tags/TAG" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
subscriber_email = "john@acme.com"
tag = "Customer"
response = client.remove_tag(subscriber_email, tag)
if response.success?
# ...
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const email = "john@acme.com";
const tag = "Customer";
client.removeSubscriberTag(email, tag)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
Responds with a
204 No Contentif successful.
HTTP Endpoint
DELETE /:account_id/subscribers/:email/tags/:tag
Arguments
None.
Users
Users are represented as follows:
{
"email": "john@acme.com",
"name": "John Doe",
"time_zone": "America/Los_Angeles"
}
Fetch the authenticated user
To fetch the current user:
curl "https://api.getdrip.com/v2/user" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
client.fetchUser()
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
{
"users":[{
"email": "john@acme.com",
"name": "John Doe",
"time_zone": "America/Los_Angeles"
}]
}
HTTP Endpoint
GET /v2/user
Arguments
None.
Workflows
Workflows are represented as follows:
{
"id": "123456",
"href": "https://api.getdrip.com/v2/9999999/workflows/123456",
"name": "Main Funnel",
"status": "active",
"created_at": "2016-07-01T10:00:00Z",
"links": {
"account": "9999999"
}
}
All responses containing workflow data also include the following top-level link data:
{
"links": {
"workflows.account": "https://api.getdrip.com/v2/accounts/{workflows.account}"
}
}
Properties
| Property | Description |
|---|---|
id |
A read-only Drip generated unique id used to identify each workflow record. |
href |
The url designated for retrieving the workflow record via the REST API. |
name |
The name assigned to the workflow. |
status |
The workflow's status whether draft, active, or paused. |
created_at |
A timestamp representing when the workflow record was first created. |
links |
An object containing the REST API URL for the account. |
List all workflows
To list all workflows:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/workflows" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
response = client.workflows
if response.success?
puts response.body["workflows"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const options = { status: "active" };
client.listAllWorkflows(options)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The workflows property is an array of workflow objects.
{
"links": { ... },
"meta": {
"page": 1,
"sort": "sort_order",
"direction": "desc",
"count": 5,
"total_pages": 1,
"total_count": 5,
"status": "all"
},
"workflows": [ ... ]
}
HTTP Endpoint
GET /v2/:account_id/workflows
Arguments
| Key | Description |
|---|---|
status |
Optional. Filter by one of the following statuses: draft, active, or paused. Defaults to all. |
sort |
Optional. Sort results by one of these fields: created_at or name. Defaults to created_at. |
direction |
Optional. Filter sort direction with: asc or desc. Defaults to asc. |
Fetch a workflow
To fetch a workflow:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/workflows/WORKFLOW_ID" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
workflow_id = 9999999
response = client.workflow(workflow_id)
if response.success?
puts response.body["workflows"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const workflowId = 222333;
client.fetchWorkflow(workflowId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The workflows property is an array of one workflow object.
{
"links": { ... },
"workflows": [{ ... }]
}
HTTP Endpoint
GET /v2/:account_id/workflows/:workflow_id
Arguments
None.
Activate a workflow
To activate a workflow:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/workflows/WORKFLOW_ID/activate" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
workflow_id = 9999999
response = client.activate_workflow(workflow_id)
if response.success?
# ...
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const workflowId = 222333;
client.activateWorkflow(workflowId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
Responds with a
204 No Contentif successful.
HTTP Endpoint
POST /v2/:account_id/workflows/:workflow_id/activate
Arguments
None.
Pause a workflow
To pause a workflow:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/workflows/WORKFLOW_ID/pause" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
workflow_id = 9999999
response = client.pause_workflow(workflow_id)
if response.success?
# ...
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const workflowId = 222333;
client.pauseWorkflow(workflowId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
Responds with a
204 No Contentif successful.
HTTP Endpoint
POST /v2/:account_id/workflows/:workflow_id/pause
Arguments
None.
Start someone on a workflow
To start a someone on a workflow:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/workflows/WORKFLOW_ID/subscribers" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"subscribers": [{
"email": "john@acme.com",
"time_zone": "America/Los_Angeles",
"custom_fields": {
"shirt_size": "Medium"
}
}]
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
workflow_id = 9999999
options = {
email: "john@acme.com",
time_zone: "America/Los_Angeles",
custom_fields: {
shirt_size: "Medium"
}
}
response = client.start_subscriber_workflow(workflow_id, options)
if response.success?
puts response.body["subscribers"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const workflowId = 222333;
const payload = {
subscribers: [{
email: "john@acme.com",
time_zone: "America/Los_Angeles",
custom_fields: {
shirt_size: "Medium"
}
}]
}
client.startOnWorkflow(workflowId, payload)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The subscribers property is an array of one object.
{
"links": { ... },
"subscribers": [{ ... }]
}
If the workflow is not active, the subscriber will not be added to the workflow.
HTTP Endpoint
POST /v2/:account_id/workflows/:workflow_id/subscribers
Arguments
| Key | Description |
|---|---|
email |
Optional. The subscriber's email address. Either email or id must be included. |
id |
Optional. The subscriber's Drip id. Either email or id must be included. |
first_name |
Optional. The subscriber's first name. |
last_name |
Optional. The subscriber's last name. |
address1 |
Optional. The subscriber's mailing address. |
address2 |
Optional. An additional field for the subscriber's mailing address. |
city |
Optional. The city, town, or village in which the subscriber resides. |
state |
Optional. The region in which the subscriber resides. Typically a province, a state, or a prefecture. |
zip |
Optional. The postal code in which the subscriber resides, also known as zip, postcode, Eircode, etc. |
country |
Optional. The country in which the subscriber resides. |
phone |
Optional. The subscriber's primary phone number. |
user_id |
Optional. A unique identifier for the user in your database, such as a primary key. |
time_zone |
Optional. The subscriber's time zone (in Olson format). Defaults to Etc/UTC |
custom_fields |
Optional. An Object containing custom field data. E.g. { "shirt_size": "Medium" }. |
tags |
Optional. An Array containing one or more tags. E.g. ["Customer", "SEO"]. |
prospect |
Optional. A Boolean specifiying whether we should attach a lead score to the subscriber (when lead scoring is enabled). Defaults to true.
Note: This flag used to be called potential_lead, which we will continue to accept for backwards compatibility. |
eu_consent |
Optional. A String specifying whether the subscriber granted or denied GDPR consent. |
eu_consent_message |
Optional. A String containing the message the subscriber granted or denied their consent to. |
Remove a subscriber from a workflow
To remove someone from a workflow:
curl -X DELETE "https://v2/api.getdrip.com/v2/YOUR_ACCOUNT_ID/workflows/WORKFLOW_ID/subscribers/ID_OR_EMAIL" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
workflow_id = 9999999
subscriber_email = "john@acme.com"
response = client.remove_subscriber_workflow(workflow_id, subscriber_email)
if response.success?
# ...
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const workflowId = 222333;
const idOrEmail = "someone@example.com"
client.removeFromWorkflow(workflowId, idOrEmail)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
Responds with a
204 No Contentif successful.
If the subscriber is not already on the workflow, nothing will happen.
HTTP Endpoint
DELETE /v2/:account_id/workflows/:workflow_id/subscribers/:id_or_email
Arguments
None.
List all workflow triggers
To list all triggers on a workflow:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/workflows/WORKFLOW_ID/triggers" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
workflow_id = 9999999
response = client.workflow_triggers(workflow_id)
if response.success?
puts response.body["triggers"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const workflowId = 222333;
client.listTriggers(workflowId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
{
"triggers": [
{
"id": "f7gysdf7gyd7",
"type": "trigger",
"trigger_type": "submitted_landing_page",
"provider": "leadpages",
"properties": {
"landing_page": "My Landing Page"
},
"actions_required": [
{
"code": "configure_provider",
"message": "Configure your LeadPages connection"
}
]
}
]
}
HTTP Endpoint
GET /v2/:account_id/workflows/:workflow_id/triggers
Arguments
None.
Create a workflow trigger
To create a workflow trigger:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/workflows/WORKFLOW_ID/triggers" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"triggers": [
{
"provider": "leadpages",
"trigger_type": "submitted_landing_page",
"properties": {
"landing_page": "My Landing Page"
}
}
]
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
workflow_id = 9999999
options = {
provider: "leadpages",
trigger_type: "submitted_landing_page",
properties: {
landing_page: "My Landing Page"
}
}
response = client.create_workflow_trigger(workflow_id, options)
if response.success?
puts response.body["triggers"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const workflowId = 222333;
const payload = {
provider: "leadpages",
trigger_type: "submitted_landing_page",
properties: {
landing_page: "My Landing Page"
}
}
client.createTrigger(workflowId, payload)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
{
"triggers": [
{
"id": "f7gysdf7gyd7",
"type": "trigger",
"provider": "leadpages",
"trigger_type": "submitted_landing_page",
"properties": {
"landing_page": "My Landing Page"
},
"actions_required": [
{
"code": "configure_provider",
"message": "Configure your LeadPages connection"
}
]
}
]
}
HTTP Endpoint
POST /v2/:account_id/workflows/:workflow_id/triggers
Arguments
| Key | Description |
|---|---|
provider |
Required. A String indicating a provider. |
trigger_type |
Required. A String indicating the automation trigger type. |
properties |
Optional. An Object containing properties for the given trigger. |
Update a workflow trigger
To update a workflow trigger:
curl -X PUT "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/workflows/WORKFLOW_ID/triggers/TRIGGER_ID" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"triggers": [
{
"provider": "leadpages",
"trigger_type": "submitted_landing_page",
"properties": {
"landing_page": "My Landing Page"
}
}
]
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
workflow_id = 9999999
options = {
provider: "leadpages",
trigger_type: "submitted_landing_page",
properties: {
landing_page: "My Landing Page"
}
}
response = client.update_workflow_trigger(workflow_id, options)
if response.success?
puts response.body["triggers"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const workflowId = 222333;
const triggerId = "abc123";
const payload = {
provider: "leadpages",
trigger_type: "submitted_landing_page",
properties: {
landing_page: "My Landing Page"
}
}
client.updateTrigger(workflowId, triggerId, payload)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
{
"triggers": [
{
"id": "f7gysdf7gyd7",
"type": "trigger",
"provider": "leadpages",
"trigger_type": "submitted_landing_page",
"properties": {
"landing_page": "My Landing Page"
},
"actions_required": [
{
"code": "configure_provider",
"message": "Configure your LeadPages connection"
}
]
}
]
}
HTTP Endpoint
PUT /v2/:account_id/workflows/:workflow_id/triggers/:trigger_id
Arguments
| Key | Description |
|---|---|
provider |
Required. A String indicating a provider. |
trigger_type |
Required. A String indicating the automation trigger type. |
properties |
Optional. An Object containing properties for the given trigger. |
Webhooks
Webhooks are represented as follows:
{
"id": "77777",
"href": "https://api.getdrip.com/v2/9999999/webhooks/77777",
"post_url": "http://www.mysite.com/my-webhook-endpoint",
"version": "1",
"include_received_email": false,
"events": [
"subscriber.created",
"subscriber.subscribed_to_campaign"
],
"created_at": "2013-06-21T10:31:58Z",
"links": {
"account": "9999999",
}
}
All responses containing webhook data also include the following top-level link data:
{
"links": {
"webhooks.account": "https://api.getdrip.com/v2/accounts/{webhooks.account}"
}
}
Properties
| Property | Description |
|---|---|
id |
A read-only Drip generated unique id used to identify each webhook record. |
href |
The url designated for retrieving the webhook record via the REST API. |
post_url |
The url that the webhook will post to. |
version |
The webhook version. The current stable version is 2. |
include_received_email |
Returns true if a notification is sent whenever a subscriber receives an email. |
created_at |
A timestamp representing when the webhook record was first created. |
events |
An array specifying which events are enabled for webhook notifications. |
links |
An object containing the REST API URL for the account. |
List all webhooks
To list all webhooks in an account:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/webhooks" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
response = client.webhooks
if response.success?
puts response.body["webhooks"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
client.listWebhooks()
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The webhooks property is an array of webhook objects.
{
"links": { ... },
"webhooks": [ ... ]
}
HTTP Endpoint
GET /v2/:account_id/webhooks
Arguments
None.
Fetch a webhook
To fetch a specific webhook:
curl "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/webhooks/WEBHOOK_ID" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
webhook_id = 999999
response = client.webhook(webhook_id)
if response.success?
puts response.body["webhooks"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const webhookId = 111222;
client.fetchWebhook(webhookId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
The response looks like this:
# The webhooks property is an array of one webhook object.
{
"links": { ... },
"webhooks": [{ ... }]
}
HTTP Endpoint
GET /v2/:account_id/webhooks/:webhook_id
Arguments
None.
Create a new webhook
To create a webhook:
curl -X POST "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/webhooks" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"webhooks": [{
"post_url": "http://www.mysite.com/my-webhook-endpoint",
"events": [
"subscriber.created",
"subscriber.subscribed_to_campaign"
]
}]
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
pot_url = "https://www.mylistener.com/receieve"
include_received_email = false
events = [
"subscriber.created",
"subscriber.subscribed_to_campaign"
]
response = client.create_webhook(post_url, include_received_email, events)
if response.success?
puts response.body["webhooks"]
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const payload = {
webhooks: [{
post_url: "http://www.mysite.com/my-webhook-endpoint",
events: [
"subscriber.created",
"subscriber.subscribed_to_campaign"
]
}]
}
client.createWebhook(payload)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
Responds with a
201 Createdlike this:
{
"links": { ... },
"webhooks": [{
"id": "77777",
"href": "https://api.getdrip.com/v2/9999999/webhooks/77777",
"post_url": "http://www.example.com/api/v2/form",
"version": "1",
"include_received_email": false,
"events": [
"subscriber.created",
"subscriber.subscribed_to_campaign"
],
"created_at": "2013-06-21T10:31:58Z",
"links": {
"account": "9999999",
}
}]
}
HTTP Endpoint
POST /v2/:account_id/webhooks
Arguments
| Key | Description |
|---|---|
post_url |
The url that the webhook will post to. |
include_received_email |
Optional. A Boolean specifying whether we should send a notification whenever a subscriber receives an email. Defaults to false. |
events |
Optional. An Array specifiying which events we should send notifications for. Eligible events can be found in the webhooks documentation. By default, we will send notifications for all events except subscrber.received_email. |
Destroy a webhook
To destroy an existing webhook:
curl -X DELETE "https://api.getdrip.com/v2/YOUR_ACCOUNT_ID/webhooks/WEBHOOK_ID" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY:
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
webhook_id = 999999
response = client.delete_webhook(webhook_id)
if response.success?
# ...
end
// npm install drip-nodejs --save
const client = require('drip-nodejs')({ token: YOUR_API_KEY, accountId: YOUR_ACCOUNT_ID });
const webhookId = 111222;
client.destroyWebhook(webhookId)
.then((response) => {
// Handle `response.body`
})
.catch((error) => {
// Handle errors
});
Responds with a
204 No Contentif successful.
HTTP Endpoint
DELETE /v2/:account_id/webhooks/:webhook_id
Arguments
None.
Webhook Events
Webhooks allow you to receive an HTTP POST to the URL(s) of your choosing anytime certain events occur in your Drip account. All our webhook events contain data serialized as JSON. If you'd like to be notified (with data) everytime a visitor subscribes, you'll want to use webhooks.
Setting Up
Adding a webhook URL is dead simple. Head over the Webhooks settings page, enter your URL, and hit "Create Webhook". That's it!
Because of the potential for high volume, we will not send notifications for
subscriber.received_email events by default. To receive a post every time a subscriber
receives an email, enable these events using the checkbox on the webhook's settings.
Please note that some webhook endpoints may implement rate limiting, especially for entry-level or free accounts. We will attempt to re-send webhooks for up to 3 days if they are rate limited. In addition, you will be notified and your webhook will be temporarily disabled if its endpoint generates any other error for 3 days.
Resources
Subscriber
{
"id": "z1togz2hcjrkpp5treip",
"status": "active",
"email": "john@acme.com",
"custom_fields": {
"shirt_size": "Medium"
},
"tags": ["Customer", "SEO"],
"time_zone": "America/Los_Angeles",
"utc_offset": -440,
"created_at": "2013-06-21T10:31:58Z"
"ip_address": "123.123.123.123",
"user_agent": "Mozilla/5.0",
"lifetime_value": 2000,
"original_referrer": "https://google.com/search",
"landing_url": "https://www.drip.co/landing",
"prospect": true,
"base_lead_score": 30,
"lead_score": 65,
"user_id": "123"
}
An example of the fields you can expect when you see "subscriber": { ... } is on the right. You may also refer to the Subscribers docs here.
Properties
| Property | Description |
|---|---|
event |
The webhook notification's event name. For example, subscrber.received_email. |
data |
An object containing the subscriber's properties. Refer to Subscribers for what's included in this object. |
account_id |
The id for the account that sent the notification. |
occurred_at |
The String time at which the event occurred in ISO-8601 format. |
subscriber.created
{
"event": "subscriber.created",
"data": {
"account_id": "9999999",
"subscriber": { ... }
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber is created in your Drip account.
subscriber.deleted
{
"event": "subscriber.deleted",
"data": {
"account_id": "9999999",
"subscriber": { ... }
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber is deleted in your Drip account.
subscriber.marked_as_deliverable
{
"event": "subscriber.marked_as_deliverable",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"source": "drip"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber transitions from being "undeliverable" (due to a hard bounce or spam complaint) to being deliverable once again.
subscriber.marked_as_undeliverable
{
"event": "subscriber.marked_as_undeliverable",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"source": "drip"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber transitions to being "undeliverable" due to a hard bounce or spam complaint.
subscriber.subscribed_to_email_marketing
{
"event": "subscriber.subscribed_to_email_marketing",
"data": {
"account_id": "9999999",
"subscriber": { ... }
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber subscribes to email marketing.
subscriber.subscribed_to_campaign
{
"event": "subscriber.subscribed_to_campaign",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"campaign_id": "9999999",
"campaign_name": "Email course"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber subscribes to an Email Series Campaign.
subscriber.removed_from_campaign
{
"event": "subscriber.removed_from_campaign",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"campaign_id": "9999999",
"campaign_name": "Email course"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber is removed from an Email Series Campaign.
subscriber.unsubscribed_from_campaign
{
"event": "subscriber.unsubscribed_from_campaign",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"campaign_id": "9999999",
"campaign_name": "Email course"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber unsubscribes from an Email Series Campaign.
subscriber.unsubscribed_all
{
"event": "subscriber.unsubscribed_all",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber is unsubscribed from all mailings.
subscriber.reactivated
{
"event": "subscriber.reactivated",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscription is reactivated.
subscriber.completed_campaign
{
"event": "subscriber.completed_campaign",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"campaign_id": "9999999",
"campaign_name": "Email course"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber completes an Email Series Campaign.
subscriber.applied_tag
{
"event": "subscriber.applied_tag",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"tag": "Customer"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber is applied a tag.
subscriber.removed_tag
{
"event": "subscriber.removed_tag",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"tag": "Customer"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a tag is removed from a subscriber.
subscriber.updated_custom_field
{
"event": "subscriber.updated_custom_field",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"identifier": "first_name",
"value": "John",
"previous_value": "",
"source": "drip"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber's custom fields are updated.
subscriber.updated_email_address
{
"event": "subscriber.updated_email_address",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"value": "jdoe@gmail.com",
"previous_value": "johndoe@gmail.com",
"source": "drip"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber's email address is updated.
subscriber.updated_lifetime_value
{
"event": "subscriber.updated_lifetime_value",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"value": 10000,
"previous_value": 9500,
"source": "drip"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber's lifetime value is updated.
subscriber.updated_time_zone
{
"event": "subscriber.updated_time_zone",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"value": "America/Chicago",
"previous_value": "America/Los_Angeles"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber's time zone is updated.
subscriber.received_email
{
"event": "subscriber.received_email",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"delivery_id": "99999",
"email_id": "88888",
"email_subject": "Email Course: Day 1"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber receives an email.
Note that because of their potentially high volume, notifications for this event are optional. See Setting up above.
subscriber.opened_email
{
"event": "subscriber.opened_email",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"delivery_id": "99999",
"email_id": "88888",
"email_subject": "Email Course: Day 1"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber opens an email.
subscriber.clicked_email
{
"event": "subscriber.clicked_email",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"delivery_id": "99999",
"email_id": "88888",
"url": "http://www.example.com",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/44.0.2403.89 Safari/537.36",
"ip_address": "111.111.111.11",
"email_subject": "Email Course: Day 1"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber clicks a link in an email.
subscriber.bounced
{
"event": "subscriber.bounced",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"delivery_id": "99999",
"email_id": "88888",
"email_subject": "Email Course: Day 1"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when an email to a subscriber bounces.
subscriber.complained
{
"event": "subscriber.complained",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"delivery_id": "99999",
"email_id": "88888",
"email_subject": "Email Course: Day 1"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber issues a spam complaint about an email.
subscriber.clicked_trigger_link
{
"event": "subscriber.clicked_trigger_link",
"data": {
"subscriber": { ... },
"properties": {
"url": "http://example.com",
"ip_address": "128.1.1.1",
"trigger_id": 99999999,
"source": "drip"
},
"account_id": "8888888"
},
"occurred_at": "2017-03-15T13:52:25Z"
}
This event is triggered when a subscriber clicks a tracking link.
subscriber.visited_page
{
"event": "subscriber.visited_page",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"url": "/blog/1234-hello-world"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber visits a page that is configured to trigger a rule.
subscriber.became_lead
{
"event": "subscriber.became_lead",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"lead_score": 68
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber becomes a lead (i.e. when the subscriber's lead score surpasses the threshold set in your lead settings). This event only fires when lead scoring is enabled for your account.
subscriber.became_non_prospect
{
"event": "subscriber.became_non_prospect",
"data": {
"account_id": "9999999",
"subscriber": { ... }
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber becomes a non-prospect (i.e. when the subscriber is no longer subject to lead scoring). This event only fires when lead scoring is enabled for your account.
subscriber.updated_lead_score
{
"event": "subscriber.updated_lead_score",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"lead_score": 68,
"previous_lead_score": 60
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber's lead score is updated. This event only fires when lead scoring is enabled for your account.
subscriber.performed_custom_event
{
"event": "subscriber.performed_custom_event",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"action": "Signed up for a trial"
"plan": "rock-star",
"amount": 2999
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a custom event is tracked for a subscriber.
subscriber.updated_alias
{
"event": "subscriber.updated_alias",
"data": {
"account_id": "9999999",
"subscriber": { ... },
"properties": {
"identifier": "user_id",
"value": "123",
"previous_value": "",
"source": "drip"
}
},
"occurred_at": "2013-06-21T10:31:58Z"
}
This event is triggered when a subscriber's aliases are updated. user_id is currently the only natively supported alias.
Shopper Activity Section
Overview
When selling online, there are many activities your customers (and potential customers) can take. Passing the details of these activities to Drip helps us make you money. We do that by enabling deeper content personalization and providing actionable insights that bring people closer to your brand.
Cart Activity
Passing in all required fields for Cart Activity will enable Cart Abandonment Dynamic Content in your Drip account. Leverage that content in our Visual Email Builder to send Cart Abandonment emails containing item details.
Note that Cart Activity will show up on a person's activity timeline as either a "Created a cart" or "Updated a cart" event. For more information, see our guide in MyDrip here.
Create or update a cart
To record a cart event:
curl -X POST "https://api.getdrip.com/v3/YOUR_ACCOUNT_ID/shopper_activity/cart" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"provider": "my_custom_platform",
"email": "user@gmail.com",
"initial_status": "active",
"action": "created",
"cart_id": "456445746",
"occurred_at": "2019-01-17T20:50:00Z",
"cart_public_id": "#5",
"grand_total": 16.99,
"total_discounts": 5.34,
"currency": "USD",
"cart_url": "https://mysuperstore.com/cart/456445746",
"items": [
{
"product_id": "B01J4SWO1G",
"product_variant_id": "B01J4SWO1G-CW-BOTT",
"sku": "XHB-1234",
"name": "The Coolest Water Bottle",
"brand": "Drip",
"categories": [
"Accessories"
],
"price": 11.16,
"quantity": 2,
"discounts": 5.34,
"total": 16.99,
"product_url": "https://mysuperstore.com/dp/B01J4SWO1G",
"image_url": "https://www.getdrip.com/images/example_products/water_bottle.png",
"product_tag": "Best Seller"
}
]
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
response = client.create_cart_activity_event(
provider: "my_custom_platform",
email: "user@gmail.com", # or person_id
initial_status: "active",
action: "created",
cart_id: "456445746",
occurred_at: "2019-01-17T20:50:00Z",
cart_public_id: "#5",
grand_total: 16.99,
total_discounts: 5.34,
currency: "USD",
cart_url: "https://mysuperstore.example.com/cart/456445746",
items: [
{
product_id: "B01J4SWO1G",
product_variant_id: "B01J4SWO1G-CW-BOTT",
sku: "XHB-1234",
name: "The Coolest Water Bottle",
brand: "Drip",
categories: [
"Accessories"
],
price: 11.16,
quantity: 2,
discounts: 5.34,
total: 16.99,
product_url: "https://mysuperstore.com/dp/B01J4SWO1G",
image_url: "https://www.getdrip.com/images/example_products/water_bottle.png",
product_tag: "Best Seller"
}
]
)
if response.success?
puts "Request accepted"
else
puts "Error occurred"
end
Responds with a
202 Acceptedif successful. That means the server accepted the request and queued it for processing.
{
"request_id": "990c99a7-5cba-42e8-8f36-aec3419186ef"
}
HTTP Endpoint
POST /v3/:account_id/shopper_activity/cart
Arguments
| Property | Description | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
provider |
Required. The identifier for the provider from which the order data was received in lower snake cased form. For example, shopify or my_custom_platform or my_store. |
||||||||||||||||||||||||||
person_id |
Optional. The unique identifier of a person at Drip. Either person_id or email must be included. If both are included, email is ignored. |
||||||||||||||||||||||||||
email |
Optional. The person's email address. Either person_id or email must be included. If both are included, email is ignored. |
||||||||||||||||||||||||||
initial_status |
Optional. The person's status whether active or unsubscribed. If this field is not included, the person will become subscribed.
| ||||||||||||||||||||||||||
action |
Required. The event's action. For Cart Activity, this can be either created or updated. created will trigger a "Created a Cart" event on a person's timeline. updated will trigger an "Updated a Cart" event. |
||||||||||||||||||||||||||
cart_id |
Required. A unique, internal id for the cart (generally the primary key generated by the ecommerce platform). | ||||||||||||||||||||||||||
occurred_at |
Optional. The String time at which the order occurred in ISO 8601 format. Defaults to the current time. | ||||||||||||||||||||||||||
cart_public_id |
Optional. A public, customer-facing identifier for the cart. This will be displayed in the Drip UI and should correspond to the identifier a customer might see in their own cart. | ||||||||||||||||||||||||||
grand_total |
Optional. The total amount of the cart. This should include any applicable discounts. Defaults to 0. | ||||||||||||||||||||||||||
total_discounts |
Optional. The discount on the entire order. Defaults to 0. | ||||||||||||||||||||||||||
currency |
Optional. The alphabetic ISO 4217 code for the currency of the purchase. | ||||||||||||||||||||||||||
cart_url |
Required. A URL that links back to the shopper’s cart on your ecommerce platform. | ||||||||||||||||||||||||||
items |
An Array of objects containing information about specific cart items.
|
The API will also allow custom attributes to be passed in. These will be exposed within Drip just like event properties.
For example, if your platform includes the concept of product tags, you can include a product_tag attribute in the JSON that can be used in a Drip automation or email via Liquid. You can attach custom attributes either to events or their items.
Order Activity
Order Activity will show up on a person's activity timeline as an event. The event is based on the action sent with the order payload. For example, sending placed will result in a "Placed an order" event and sending updated will result in an "Updated an order" event.
Order Activity places special value on action with the placed value. This event will determine when an order is considered to have originated based on the occurred_at. If you send an Order Activity "action": "placed" event without including a valid occurred_at value, the order will be considered to have originated at the current time. If you send Order Activity events without previously sending placed, the order will be considered to have originated at the current time the first event was received.
Drip will keep a person’s Lifetime Value (LTV) up-to-date with their orders. For example, if a customer places an order with a grand_total of $100, their LTV will be incremented by $100. If the order is then updated, paid, or fulfilled with a grand_total value of $105, the customer’s LTV will increase by $5. If the order is then canceled or refunded with a refund_amount of $105, the customer’s LTV will decrease by $105.
Create or update an order
To update an existing order, include the provider and order_id for that order in the payload.
To record an order event:
curl -X POST "https://api.getdrip.com/v3/YOUR_ACCOUNT_ID/shopper_activity/order" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"provider": "my_custom_platform",
"email": "user@gmail.com",
"initial_status": "active",
"action": "placed",
"occurred_at": "2019-01-17T20:50:00Z",
"order_id": "456445746",
"order_public_id": "#5",
"grand_total": 22.99,
"total_discounts": 5.34,
"total_taxes": 1.00,
"total_fees": 2.00,
"total_shipping": 5.00,
"currency": "USD",
"order_url": "https://mysuperstore.com/order/456445746",
"items": [
{
"product_id": "B01J4SWO1G",
"product_variant_id": "B01J4SWO1G-CW-BOTT",
"sku": "XHB-1234",
"name": "The Coolest Water Bottle",
"brand": "Drip",
"categories": [
"Accessories"
],
"price": 11.16,
"sale_price": 10.16,
"quantity": 2,
"discounts": 5.34,
"taxes": 1.00,
"fees": 0.50,
"shipping": 5.00,
"total": 23.99,
"product_url": "https://mysuperstore.com/dp/B01J4SWO1G",
"image_url": "https://www.getdrip.com/images/example_products/water_bottle.png",
"product_tag": "Best Seller"
}
],
"billing_address": {
"label": "Primary Billing",
"first_name": "Bill",
"last_name": "Billington",
"company": "Bills R US",
"address_1": "123 Bill St.",
"address_2": "Apt. B",
"city": "Billtown",
"state": "CA",
"postal_code": "01234",
"country": "United States",
"phone": "555-555-5555"
},
"shipping_address": {
"label": "Downtown Office",
"first_name": "Ship",
"last_name": "Shipington",
"company": "Shipping 4 Less",
"address_1": "123 Ship St.",
"city": "Shipville",
"state": "CA",
"postal_code": "01234",
"country": "United States",
"phone": "555-555-5555"
}
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
response = client.create_order_activity_event(
provider: "my_custom_platform",
email: "user@gmail.com", # or person_id
initial_status: "active",
action: "placed",
occurred_at: "2019-01-17T20:50:00Z",
order_id: "456445746",
order_public_id: "#5",
grand_total: 22.99,
total_discounts: 5.34,
total_taxes: 1.00,
total_fees: 2.00,
total_shipping: 5.00,
currency: "USD",
order_url: "https://mysuperstore.com/order/456445746",
items: [
{
product_id: "B01J4SWO1G",
product_variant_id: "B01J4SWO1G-CW-BOTT",
sku: "XHB-1234",
name: "The Coolest Water Bottle",
brand: "Drip",
categories: [
"Accessories"
],
price: 11.16,
sale_price: 10.16,
quantity: 2,
discounts: 5.34,
taxes: 1.00,
fees: 0.50,
shipping: 5.00,
total: 23.99,
product_url: "https://mysuperstore.com/dp/B01J4SWO1G",
image_url: "https://www.getdrip.com/images/example_products/water_bottle.png",
product_tag: "Best Seller"
}
],
billing_address: {
label: "Primary Billing",
first_name: "Bill",
last_name: "Billington",
company: "Bills R US",
address_1: "123 Bill St.",
address_2: "Apt. B",
city: "Billtown",
state: "CA",
postal_code: "01234",
country: "United States",
phone: "555-555-5555"
},
shipping_address: {
label: "Downtown Office",
first_name: "Ship",
last_name: "Shipington",
company: "Shipping 4 Less",
address_1: "123 Ship St.",
city: "Shipville",
state: "CA",
postal_code: "01234",
country: "United States",
phone: "555-555-5555"
}
)
if response.success?
puts "Request accepted"
else
puts "Error occurred"
end
Responds with a
202 Acceptedif successful. That means the server accepted the request and queued it for processing
{
"request_id": "990c99a7-5cba-42e8-8f36-aec3419186ef"
}
HTTP Endpoint
POST /v3/:account_id/shopper_activity/order
Arguments
| Property | Description | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
provider |
Required. The identifier for the provider from which the order data was received in lower snake cased form. For example, shopify or my_custom_platform or my_store. |
||||||||||||||||||||||||||||||||
person_id |
Optional. The unique identifier of a person at Drip. Either person_id or email must be included. If both are included, email is ignored. |
||||||||||||||||||||||||||||||||
email |
Optional. The person's email address. Either person_id or email must be included. If both are included, email is ignored. |
||||||||||||||||||||||||||||||||
initial_status |
Optional. The person's status whether active or unsubscribed. If this field is not included, the person will become subscribed.
| ||||||||||||||||||||||||||||||||
action |
Required. The event's action. For Order Activity, this can be either placed, updated, paid, fulfilled, refunded, or canceled. These actions will result in "Placed an order", "Updated an order", "Paid an order", "Fulfilled an order", "Refunded an order", and "Canceled an order" events on the person's timeline, respectively.
| ||||||||||||||||||||||||||||||||
occurred_at |
Optional. The String time at which the order occurred in ISO 8601 format. Defaults to the current time. | ||||||||||||||||||||||||||||||||
order_id |
Required. A unique, internal id for the order (generally the primary key generated by the ecommerce platform). | ||||||||||||||||||||||||||||||||
order_public_id |
Optional. A public, customer-facing identifier for the order. This will be displayed in the Drip UI and should correspond to the identifier a customer might see in their own order. | ||||||||||||||||||||||||||||||||
grand_total |
Optional. The total amount of the order. This should include any applicable discounts. Defaults to 0. | ||||||||||||||||||||||||||||||||
total_discounts |
Optional. The discounts on the entire order. Defaults to 0. | ||||||||||||||||||||||||||||||||
total_taxes |
Optional. The taxes on the entire order. Defaults to 0. | ||||||||||||||||||||||||||||||||
total_fees |
Optional. The fees on the entire order. Defaults to 0. | ||||||||||||||||||||||||||||||||
total_shipping |
Optional. The shipping on the entire order. Defaults to 0. | ||||||||||||||||||||||||||||||||
refund_amount |
Optional. To adjust a person’s lifetime value for a refund or cancelation, set refund_amount to the amount of the refund and leave grand_total unchanged. Defaults to 0. |
||||||||||||||||||||||||||||||||
currency |
Optional. The alphabetic ISO 4217 code for the currency of the purchase. | ||||||||||||||||||||||||||||||||
order_url |
Optional. A URL that links back to the shopper’s order on your ecommerce platform. | ||||||||||||||||||||||||||||||||
items |
An Array of objects containing information about specific order items.
|
||||||||||||||||||||||||||||||||
billing_address |
An object containing billing address information.
|
||||||||||||||||||||||||||||||||
shipping_address |
An object containing shipping address information.
|
The API will also allow custom attributes to be passed in. These will be exposed within Drip just like event properties.
For example, if your platform includes the concept of product tags, you can include a product_tag attribute in the JSON that can be used in a Drip automation or email via Liquid. You can attach custom attributes either to events or their items.
Product Activity
Using the Product Activity endpoint will enable product-triggered automations in your Drip account. An example: price drop notifications. Send an email when a product in a customer’s cart drops in price, encouraging the customer to return and place an order.
Create or update a product
To update an existing product, include the provider and product_id for that order in the payload.
To record an order event:
curl -X POST "https://api.getdrip.com/v3/YOUR_ACCOUNT_ID/shopper_activity/product" \
-H "Content-Type: application/json" \
-H 'User-Agent: Your App Name (www.yourapp.com)' \
-u YOUR_API_KEY: \
-d @- << EOF
{
"provider": "my_custom_platform",
"action": "created",
"occurred_at": "2019-01-28T12:15:23Z",
"product_id": "B01J4SWO1G",
"product_variant_id": "B01J4SWO1G-CW-BOTT",
"sku": "XHB-1234",
"name": "The Coolest Water Bottle",
"brand": "Drip",
"categories": [
"Accessories"
],
"currency": "USD",
"price": 11.16,
"inventory": 42,
"product_url": "https://mysuperstore.com/dp/B01J4SWO1G",
"image_url": "https://www.getdrip.com/images/example_products/water_bottle.png"
}
EOF
require 'drip'
client = Drip::Client.new do |c|
c.api_key = "YOUR API KEY"
c.account_id = "YOUR_ACCOUNT_ID"
end
response = client.create_product_activity_event(
provider: "my_custom_platform",
action: "created",
occurred_at: "2019-01-28T12:15:23Z",
product_id: "B01J4SWO1G",
product_variant_id: "B01J4SWO1G-CW-BOTT",
sku: "XHB-1234",
name: "The Coolest Water Bottle",
brand: "Drip",
categories: [
"Accessories"
],
currency: "USD",
price: 11.16,
inventory: 42,
product_url: "https://mysuperstore.example.com/dp/B01J4SWO1G",
image_url: "https://www.getdrip.com/images/example_products/water_bottle.png"
)
if response.success?
puts "Request accepted"
else
puts "Error occurred"
end
Responds with a
202 Acceptedif successful. That means the server accepted the request and queued it for processing.
{
"request_id": "990c99a7-5cba-42e8-8f36-aec3419186ef"
}
HTTP Endpoint
POST /v3/:account_id/shopper_activity/product
Arguments
| Property | Description |
|---|---|
provider |
Required. The identifier for the provider from which the product data was received in lower snake cased form. For example, shopify or my_custom_platform or my_store. |
action |
Required. The event's action. For Product Activity, this can be either created, updated or deleted.
|
occurred_at |
Optional. The String time at which the product activity occurred in ISO 8601 format. Defaults to the current time. |
product_id |
Required. A unique, internal id for the product (generally the primary key generated by the ecommerce platform). (Note: this field is used by segmentation.) |
product_variant_id |
Required. A unique identifier for the specific product variant from the provider. For example, a t-shirt may have one product_id, but several product_variant_ids for sizes and colors. If a product does not have multiple variants and you do not have a variant identifier in your system, repeat the product_id here. (Note: this field is used by segmentation.) |
sku |
Optional. The product SKU. |
name |
Required. The product name. |
brand |
Optional. The product's brand, vendor, or manufacturer. |
categories |
Optional. An array of categories associated with the product (e.g. shoes, vitamins, books, videos). |
currency |
Optional. The currency of a single product. Defaults to USD ($). |
price |
Required. The price of a single product. |
inventory |
Optional. Integer. The currently available inventory of the product. |
product_url |
Optional. A URL to the site containing product details. |
image_url |
Optional. A direct URL to an image of the product. We recommend using an image type that is supported by modern email clients (e.g. JPEG, GIF, PNG). For best display results, image size should be consistent across all products. |
JS Section
Getting Started
The Drip client library has a number of API methods for performing tasks right from your website, such as manually subscribing users and tracking conversions. This document details everything you can do via our JavaScript API.
Installing Your JavaScript Snippet
The snippet for your site generally looks something like this:
<!-- Drip -->
<script type="text/javascript">
var _dcq = _dcq || [];
var _dcs = _dcs || {};
_dcs.account = `your account id`;
// _dcs.cookiePath = '/en'; // If you want to limit the cookie to a specific path.
(function() {
var dc = document.createElement('script');
dc.type = 'text/javascript'; dc.async = true;
dc.src = '//tag.getdrip.com/`your account id`.js';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(dc, s);
})();
</script>
<!-- end Drip -->
To interact with the JavaScript API, you'll need to have your Drip snippet installed on your website. Each Drip account has a unique snippet that can be found under Settings → Account → Site Setup.
How to Send a JS API Request
_dcq.push(["methodName", { key: "value", ... }]);
All requests follow the same conventions. If you've ever worked with the Google Analytics API, the semantics should look familiar. This is the basic structure of an API request.
API requests are executed asynchronously, so you may safely place them anywhere on the page (even above the Drip snippet).
Identifying Visitors
Attach Identifying Data to Visitors
Example identify request with a success callback
_dcq.push(["identify", {
email: "john@acme.com",
first_name: "John",
tags: ["Customer"],
success: function(response) {
// Call a method with the response object
// Success callback is optional
}
}]);
The identify method pushes subscriber data into Drip. If the subscriber is not yet in your account, we will create a new record for them; otherwise, we update their record with the information you pass in. To update a subscriber's email address, use the new_email property.
Properties
The following are treated as special properties. All other data passed in will be added to the subscriber's custom fields. Keys should be lowercase, with words separated by underscores. Keys that begin with drip_ are reserved for internal Drip usage.
| Key | Description |
|---|---|
email |
The subscriber's email address. Required when identifying new site visitors. |
new_email |
Optional. Use this to update an existing subscriber's email address |
user_id |
Optional. A unique identifier for the user in your database, such as a primary key. |
tags |
Optional. An Array of tags to apply. |
remove_tags |
Optional. An Array of tags to remove. |
prospect |
Optional. A Boolean specifying whether we should attach a lead score to the subscriber (when lead scoring is enabled). Defaults to true. Note: This flag used to be called potential_lead, which we will continue to accept for backwards compatibility. |
eu_consent |
Optional. A String specifying whether the subscriber granted or denied GDPR consent. |
eu_consent_message |
Optional. A String containing the message the subscriber granted or denied their consent to. |
success |
Optional. A callback function that is executed upon successful completion of the request. |
failure |
Optional. A callback function that is executed if the request fails. |
Response
Example response
{
success: true,
visitor_uuid: "f627ee608adb01315d1022000ab2058a",
anonymous: false,
}
The identify request will pass a response object to the success or failure callback functions (if provided) once the call completes.
| Key | Description |
|---|---|
success |
Boolean. True if the call to Drip succeeded. |
visitor_uuid |
The unique id for the visitor identified. |
anonymous |
Boolean. False if the visitor is associated with a subscriber. |
error |
String. Contains an error message if the request failed. |
Tracking Events
Tracking Events and Conversions for subscribers
Example track request
_dcq.push(
[
"track", "Signed up for a trial",
{ value: 2000 }
]
);
The track method is appropriate when you cannot trigger conversions by URL or you simply wish to record an particular action that the user has taken. The second argument is the name of the action to be recorded. If the action matches the name of a goal, then we will trigger a conversion.
Properties
The following are treated as special properties. All other data passed in will be saved as custom event properties.
| Key | Description |
|---|---|
value |
Optional. An Integer value (in cents). If the event triggers a conversion, this will be used as the conversion value. Must be within the range of 0 to 2,147,483,647. |
occurred_at |
Optional. The String time at which the event occurred in ISO-8601 format. Defaults to the current time. |
success |
Optional. A callback function that is executed upon successful completion of the request. |
failure |
Optional. A callback function that is executed if the request fails. |
Example response
{
success: true,
visitor_uuid: "f627ee608adb01315d1022000ab2058a",
anonymous: false
}
Response
The track request will return a response object that can be passed into the callback functions.
| Key | Description |
|---|---|
success |
Boolean. True if the call to Drip succeeded. |
visitor_uuid |
The unique id for the visitor identified. |
anonymous |
Boolean. False if the visitor is associated with a subscriber. |
error |
String. Contains an error message if the request failed. |
Tracking Product Views
Example product view request
_dcq.push(
[
"track", "Viewed a Product",
{
product_id: "B01J4SWO1G",
product_variant_id: "B01J4SWO1G-CW-BOTT",
sku: "XHB-1234",
name: "The Coolest Water Bottle",
categories: "Accessories,Bottles",
price: 11.16,
currency: "USD",
product_url: "https://mysuperstore.com/dp/B01J4SWO1G",
image_url: "https://www.getdrip.com/images/example_products/water_bottle.png",
brand: "Drip",
source: "my_custom_platform"
}
]
);
You can use the track method to send product views to Drip. By sending with a "Viewed a product" action and sending product data via the Shopper Activity API, you can segment on product views in Drip.
Properties
Include the following optional custom event properties to enable automation and segmentation options in Drip.
| Key | Description |
|---|---|
product_id |
A unique, internal id for the product (generally the primary key generated by the ecommerce platform). (Note: this field is used by segmentation.) |
product_variant_id |
A unique identifier for the specific product variant from the provider. For example, a t-shirt may have one product_id, but several product_variant_ids for sizes and colors. If a product does not have multiple variants and you do not have a variant identifier in your system, repeat the product_id here. |
sku |
The product SKU. |
name |
The product name. |
brand |
The product's brand, vendor, or manufacturer. |
categories |
An comma separated list of categories associated with the product (e.g. shoes, vitamins, books, videos). |
price |
The price of a single product. |
occurred_at |
The String time at which the event occurred in ISO-8601 format. Defaults to the current time. |
success |
Optional. A callback function that is executed upon successful completion of the request. |
failure |
Optional. A callback function that is executed if the request fails. |
Example response
{
success: true,
visitor_uuid: "f627ee608adb01315d1022000ab2058a",
anonymous: false
}
Response
The track request will return a response object that can be passed into the callback functions.
| Key | Description |
|---|---|
success |
Boolean. True if the call to Drip succeeded. |
visitor_uuid |
The unique id for the visitor identified. |
anonymous |
Boolean. False if the visitor is associated with a subscriber. |
error |
String. Contains an error message if the request failed. |
Tagging via Query String
You can also tag visitors by appending a dst query string parameter to the URL of a page that has the Drip JavaScript installed. For example, the following URL will tag visitors with Customer
http://www.mysite.com?dst=Customer
Email Series Campaign Subscriptions
Subscribe to an Email Series Campaign
Example request
_dcq.push(
[
"subscribe",
{
campaign_id: "9999999",
fields: {
email: "john@acme.com"
},
success: function(response) {
// Call a method with the response object
// Success callback is optional
}
}
]
);
This method will add a subscriber directly to an Email Series Campaign. If you would like to add a subscriber to your account without subscribing them to an Email Series Campaign, use an identify call instead.
Arguments
| Key | Description |
|---|---|
campaign_id |
Required. The String campaign ID, which can be found on the Email Series Campaign settings page. |
fields |
Required. An Object containing the user's data. At minimum, this object must contain an email attribute. If there are any required custom fields, these attributes must also be present. |
double_optin |
Optional. If true, the double opt-in confirmation email is sent; if false, the confirmation email is skipped. Defaults to the value set on the Email Series Campaign. |
success |
Optional. A callback function that is executed upon successful completion of the request. |
failure |
Optional. A callback function that is executed if the request fails. |
Unsubscribe a Subscriber
Example request
_dcq.push(
[
"unsubscribe",
{
campaign_id: "9999999",
email: "john@acme.com"
}
]
);
Use this method to unsubscribe a subscriber from one or all of your Email Series Campaigns.
Arguments
| Key | Description |
|---|---|
email |
Required. The String email address of the subscriber you wish to unsubscribe. |
campaign_id |
Optional. The String campaign ID, which can be found on the Email Series Campaign settings page. If not included, the subscriber will be unsubscribed from all Email Series Campaigns. |
success |
Optional. A callback function that is executed upon successful completion of the request. |
failure |
Optional. A callback function that is executed if the request fails. |
Handling Forms
Opening and closing a form
Example requests
_dcq.push(["showForm", { id: "9999999" }]);
_dcq.push(["hideForm", { id: "9999999" }]);
The native Drip form widget can be opened or closed via the JS API.
Arguments
| Key | Description |
|---|---|
id |
Required. The String form ID, which can be found on the form settings page. |
showTab |
Optional. If true, the teaser tab will show when the form is closed. Defaults to true. |
Form Submission Events
Example listener
$(document).on("submitted.drip", function(ev, data){
console.log(data);
})
Example Event Data
{
"account_id": "999999",
"fields[email]": "john@acme.com",
"fields[first_name]": "John",
"form_id": "999999",
"page_title": "Drip :: Email Marketing Automation for Visitors, Trials and Customers",
"submit": "Let's do it!",
"time_zone": "America/Los_Angeles",
"url": "https://www.getdrip.com/",
"visitor_uuid": "f627ee608adb01315d1022000ab2058a"
}
If jQuery is available on your page, the following events are triggered as the widget is submitted:
| Event | Fired when... |
|---|---|
submitting.drip |
a form submit button is clicked. |
submitFailed.drip |
a form submission fails. |
submitted.drip |
a form submission succeeds. |
By listening for these events, you can hook your own javascript onto the widget's actions. Each of the above events carries a data Object with the form's information.
CDC Section
Overview
To request this feature be enabled on your account, contact our support team.
Custom Dynamic Content allows you to pull data from your system into Drip emails. Your data is then available via Liquid, allowing you to build super-rich personalized emails augmented with fresh data from your own systems.
Example use cases:
- Is it going to rain this weekend? Offer your customer an umbrella! Or maybe it'll be sunny? Show them a hat!
- Show up-to-date prices for a flight or ticketed event for which a customer is interested! Drip can pass customer information to your endpoint, and pull in the latest prices.
How it works
- You provide a custom API endpoint
- You choose the Liquid shortcode
- When we render an email, we'll
GETa JSON document from your endpoint - You'll then have access to that document in Liquid via your
my.shortcode
See Drip Weather as an example endpoint.
API Requirements
Endpoint
- Responds to an HTTP GET request
- No additional authentication supported beyond the path and query params, e.g. you can set your base URL to something similar to one of:
https://api.example.com/?token=a7c43behttps://api.example.com/a7c43be/
Parameters
- Parameters are scoped to an entity, e.g.
subscriberorevent - You'll specify which fields of these objects you want sent to your endpoint
- Let us know the exact Custom Field names and Event property names you want us to pass to you via the query string
- This limitation (not sending all of them) exists because most HTTP servers enforce a URI length limit, and we're passing these fields to you via GET in order for them to be highly cacheable, as to optimize for delivery throughput
- Scoped parameters are then named the same as the custom field
- e.g. A subscriber custom field of
first_namewould be passed through assubscriber[first_name] - e.g. An event field of
product_idwould be passed through asevent[product_id]
- e.g. A subscriber custom field of
- The
eventobject is valid only within a Workflow - Parameters will all be passed via the URL query string (we only support
GETrequests) - There can be default parameters embedded in your endpoint URL
- We will append our parameters to yours
- This is useful for authentication, such as providing
?key=12345
- Parameters without a value will be sent through as a key with no value
- e.g. A subscriber with a custom field assigned for country, but not for zip would have a URL query string of
?subscriber[country]=US&subscriber[zip]
- e.g. A subscriber with a custom field assigned for country, but not for zip would have a URL query string of
- A parameter value should not be unique per subscriber (e.g. we won't send
email); this allows for greater cacheability of responses, as to optimize your delivery throughput
Response
- Responses must have a
Content-Typeheader ofapplication/json - A response with a
2xxstatus will be considered successful- A successful response should contain a body that is a parseable JSON document (i.e. the top level must be either an object or an array)
- The returned document must not exceed 350 KB in size
- A
3xxresponse will be followed as redirects per the HTTP specification - A client error response (those in the
4xxrange) will be considered a permanent error- Except
429; this signals to Drip that the request should be tried again later
- Except
- A server error response (those in the
5xxrange) will be considered a temporary error - No other response codes are supported
When a 2xx response is received, Drip will use whatever data is given, and will assume null values for any data not given. For example, response of {} would still be accessible in Liquid and would respond to any attribute with nil.
General
- We will retry temporary error responses for a limited amount of time
- If retries continue to fail, we will give up sending the individual email
- A permanent error response will cause the the email to not be sent
- In order to optimize your sending throughput, we will time out any response or series of redirects after 3 seconds
- If you need additional time to process Drip's request (e.g. to warm a cache), you can respond with a
429, at which point we will retry the request with exponential backoff
- If you need additional time to process Drip's request (e.g. to warm a cache), you can respond with a
Preview/Test Mode
Example request from Drip to your endpoint during Preview/Test
https://api.you.com/api?subscriber[zipcode]&preview=true
Example request from Drip to your endpoint during Preview As
https://api.you.com/api?subscriber[zipcode]=90210&preview=true
When previewing or sending a test email within Drip, we’ll make calls to your endpoint with an additional query parameter: preview=true.
When that happens, we suggest your endpoint send back mocked data. This allows preview and test emails to populate with sample content for a more accurate experience.
This is because in these contexts we won't have an Event to send to your endpoint. (And unless you're using Preview As, nor will we have a Person.)
Example
Example request from Drip to your endpoint
https://api.you.com/api?subscriber[zipcode]=90210
Example response from Drip's weather service
{
"apparentTemperature": 65.89,
"cloudCover": 0.09,
"dewPoint": 22.55,
"humidity": 0.19,
"icon": "clear-night",
"nearestStormBearing": 131,
"nearestStormDistance": 446,
"ozone": 258.97,
"precipIntensity": 0,
"precipProbability": 0,
"pressure": 1018.59,
"summary": "Clear",
"temperature": 65.89,
"time": 1541727521,
"uvIndex": 0,
"visibility": 8.27,
"windBearing": 1,
"windGust": 10.09,
"windSpeed": 4.39
}
Imagine that you've got a service that returns the weather for a given zipcode. As a canonical example, have a look at our weather service.
Now, consider some Custom Dynamic Content that looks like this:
Good morning {{ subscriber.first_name }}! Looks like it's {{ my.weather.summary | downcase }} in your neck of the woods!
At the point that we render this content, we'll make a request to your API. If you're using our weather service, the request and response will look something like what you see to the right.
In addition to having access to the subscriber object, all of your Custom Dynamic Content will be available in a my object. In this example, we're making the response above available as my.weather.
And so, when the Liquid is rendered, it might look like:
Good morning Mary! Looks like it's clear in your neck of the woods!