Abandoned carts

Do not lose a deal:


send automated emails every time shopper adds items to the cart, but does not make a purchase.

A single visitor (with the same email address) can receive only one cart recovery email in 24 hours. If a visitor abandons two carts in 24 hours, he (or she) will not receive a 2nd email.

If you are testing your Cart Recovery yourself, consider using different email addresses on the same day. You will be able to test with the same email address the next day.

You need to make 4 steps to fully integrate abandoned cart functionality:


Our system will identify when cart is abandoned and send automated emails to user.


You can use either Backend API, Frontend API or combine both. See API reference for details.
 

Shopping process


User identification process (Backend API)


1. Send users` carts to Omnisend

To make requests to Omnisend API you'll need an API key. You can get the key by going to:

Dashboard / User profile / Integrations & API / API keys or by clicking here.


User identification:

If user is adding products to cart but isn't identified (you don't know neither user's email neither contactID) - try user identification process (see scheme above).
If you need to get user's email from contactID use API method GET contacts/{contactID}
Optional step - call to API is optional step, because in API methods you can use either user's email either contactID
.
There are several methods used to send user cart to Omnisend:
POST carts
To create new user cart
PUT carts
To update (replace) user cart - old data will be deleted and only new saved.
PATCH carts
To update cart by passing only new or updated data. Can be used for adding products.
POST carts/{cartID}/product/
To add new product to cart
DELETE carts/{cartID}/product/{cartProductID}
To remove product from cart
DELETE carts/{cartID}
Delete user cart
GET carts/{cartID}
Get user cart
Parameters used in these methods:
cartID - user's cart identificator.
You can use any unique number/string. This parameter is used to identify single users cart.
email & contactID - one of these fields is mandatory.
If user isn't identified (you don't know user's email) - you can try to get contactID from cookie (see part 3) named omnisendContactID (see part 3 - user identification).
If you'll use both of these fields - email will be used as main user identifier.
contactID
User identifier in Omnisend system. If user isn't identified - you can try to get contactID from cookie (see part 3) named "omnisendContactID"
Every contact in our system is identified by email or by contactID. Both variables are unique identifiers of contact.
attributionID
We'll add this parameter to campaign newsletter links and write to omnisendAttributionID cookie. Pass it back with cart data. It is used to link cart with campaign or automation email.
cartRecoveryUrl
If you have ability to restore cart from url - post it to our system. We'll link abandoned cart emails to it.

When user adds it's first product, make POST request to /carts endpoint and post all data.

When user adds more products - make one of:

POST carts/{cartID}/product/
Post email, cartID and added product info
PATCH carts
Post email, cartID and added product or products info
PUT carts
Post all info - old and newly added products (it's cart sync function - all old data in Omnisend will be overwritten with the posted data). This function also can be used for cart creation.
Which method to use depends on your possibilities and wishes.
For example we'll use PUT method to create and update cart when user will make changes (add or remove products).

Example request:

curl --request PUT \
--url 'https://api.omnisend.com/v3/carts/4557116516' \
--header ' content-type: application/json' \
--header ' x-api-key: X-API-KEY' \
--data ' { \
"attributionID":"59099010597ed74f6635fb14", \
"currency":"USD", \
"cartSum":78777, \
"cartRecoveryUrl":"http://omnisend.com/carts/?retoreCart=4557116516", \
"products": [ \
{ \
"cartProductID":"1", \
"productID":"prod666", \
"variantID":"prod666", \
"title":"Container for mojo", \
"quantity":1, \
"price":66666, \
"discount":0, \
"imageUrl":"http://www.omnisend.com/images/products/prod-666.png", \
"productUrl":"http://www.omnisend.com/products/prod-666"}, \
{ \
"cartProductID":"2", \
"productID":"prod999", \
"variantID":"prod999", \
"title":"Nitrous oxide", \
"quantity":10, \
"price":12111, \
"discount":0, \
"imageUrl":"http://www.omnisend.com/images/products/prod-999.png", \
"productUrl":"http://www.omnisend.com/products/prod-999" \
} \
] \
}'

You can always make GET request to get info about user cart, stored in Omnisend.

Example request:

curl --request GET \
--url 'https://api.omnisend.com/v3/carts/4557116516' \
--header 'x-api-key: X-API-KEY' \
--data '{ \
"abandonedStatus": "", \
"abandonedStatusDate": "", \
"cartID": "4557116516", \
"cartRecoveryUrl": "http://omnisend.com/carts/?retoreCart=4557116516", \
"cartStatus": "finished", \
"cartStatusDate": "2017-06-20T15:57:41.666Z", \
"cartSum": 66666, \
"contactID": "56565FRT1446466sd66", \
"currency": "USD", \
"date": "2017-06-20T15:40:12Z", \
"email": "dr.evil@omnisend.com", \
"attributionID": "59099010597ed74f6635fb14", \
"products": [ \
{ \
"cartProductID": "1", \
"discount": 0, \
"imageUrl": "http://www.omnisend.com/images/products/prod-666.png", \
"price": 66666, \
"productID": "prod666", \
"productUrl": "http://www.omnisend.com/products/prod-666", \
"quantity": 1, \
"title": "Container for mojo", \
"variantID": "prod666" \
} \
] \
}'

2. Send users` orders to Omnisend

When user makes an order or order‘s status changes - POST this information to Omnisend.
For this you can use these methods:
POST orders
to post new order or orders
PUT orders/{orderID}
to post new or update existing order/orders (this method will overwrite data)
PATCH orders/{orderID}
to update order payment, fulfillment status or tracking info.
DELETE orders/{orderID}
to delete order
Parameters used in these methods:
orderID - unique order number.
cartID - same cart identificator, that is used in the first step. If user‘s cart was restored and order was made - use same cartID.
We'll merge cart and order and will know that this order was made from the abandoned cart email.
paymentStatus
We have the list of predefined payment statuses, so you need to map them with your own order statuses. See bellow for available statuses.
fulfillmentStatus
We have the list of predefined fulfillment (shipping) statuses, so you need to map them with your own order statuses. See bellow for available statuses.
attributionID
We'll add this parameter to cartRecoveryUrl and write to omnisendAttributionID cookie. Pass it back with order data. It is used to link order with campaign or automation email.

For full description view Orders section at API our reference
 
Order payment statuses:
  • awaitingPayment - Awaiting payment
  • paid - Order paid
  • refunded - Refunded
  • canceled - Order canceled

Order fulfillment statuses:
  • inProgress - order placed/in progress
  • fulfilled - order prepared for pickup (if delivery type pickup selected) or shipped
  • delivered - order has been picked up by or delivered to customer

To post new order we'll use POST request to /orders endpoint and post all data.

Example request:

curl --request POST \
--url 'https://api.omnisend.com/v3/orders' \
--header ' x-api-key: X-API-KEY' \
--data '{ \
"orderID": "2017-05-06-14587", \
"email": "dr.evil@omnisend.com", \
"cartID": "4557116516", \
"attributionID": "59099010597ed74f6635fb14", \
"trackingCode": "666", \
"courierTitle": "Nuclear post", \
"courierUrl": "http://www.omnisend.com/?trackId=666", \
"orderUrl": "http://omnisend.com/orders/2017-05-06-14587", \
"source":"", \
"discountCode":"mojo66", \
"currency":"USD", \
"orderSum":66666, "discountSum":0, "taxSum":0, "shippingSum":0, "date":"2017-06-20T16:40:12Z", \
"paymentStatus":"paid", \
"paymentStatusDate":"2017-06-20T16:42:12Z", \
"fulfillmentStatus":"fulfiled", \
"fulfillmentStatusDate":"2017-06-22T16:42:12Z", \
"billingAddress":
{ \
"country":"United Kingdom", \
"countryCode":"GB", \
"state":"", \
"city":"London", \
"address":"Westminster", \
"postalCode":"SW1A 1AA" \
}, \
"shippingAddress": \
{ \
"country":"United Kingdom", \
"countryCode":"GB", \
"state":"", \
"city":"London", \
"address":"Westminster", \
"postalCode":"SW1A 1AA" \
}, \
"products":[ \
{ \
"cartProductID":"1", \
"productID":"prod666", \
"variantID":"", \
"title":"Container for mojo", \
"quantity":1, \
"price":66666, \
"discount":0, \
"imageUrl":"http://www.omnisend.com/images/products/prod-666.png", \
"productUrl":"http://www.omnisend.com/products/prod-666" \
} \
], \
"customFields": \
{ \
"phone":"+66 666 666 66" \
} \
}'

You have successfully completed this step for abandoned carts.

If you want to use other automation workflows (reminder to make payment, send tracking code, send thank you email, etc.) - you also need to POST order payment or fulfillment status changes.
When order status will change, use PACTH method to send orderID and updated status.
Keep in mind - if order placement and payment are proccessed at same time - send only last status.

For example when user will make payment, make PACTH request:

curl --request PATCH \
--url 'https://api.omnisend.com/v3/orders/2017-05-06-14587' \
--header ' x-api-key: X-API-KEY' \
--data '{ \
"paymentStatus":"paid", \
"paymentStatusDate":"2017-06-20T16:42:12Z" \
}'

3. Turn on automated cart recovery or cart recovery series workflows inside the Omnisend application

Login into Omnisend application. Go to Dashborad/Automation and turn on cart recovery and/or cart recovery series workflows.
Enter needed data and edit template if you want.
Done.


4. Restore abandoned user carts`

User identification process (Backend API)


Our system will send abandoned cart email with cartRecoveryUrl link and will add to it parameters:

  • omnisendContactID - contact's identifier (contactID)
  • omnisendAttributionID - abandoned cart identificator (attributionID)

Example:

http://www.your-store.com/cartrestore/cart1234567/?omnisendContactID=4785497456&omnisendAttributionID=475874693
  • Keep in mind - you need to add cart identificator to cartRecoveryUrl by your self, to be able to identify and restore user cart.
  • Our snippet will get omnisendContactID and store it to omnisendContactID cookie, and omnisendAttributionID and store it to omnisendAttributionID cookie.
  • When user will make order - remember to POST cartID and attributionID parameters in order request.
  • You can use omnisendContactIDcookie to identify user and it's cart in steps 1 and 2.

  • If you have cartID but don't have data about this cart - you can make GET carts/{cartID} request to Omnisend API and get all needed cart data.

Shopping process


User identification process (only Backend API)

1. Send users` carts to Omnisend

To make requests to Frontend API you'll need to add Javascript snippet.
If you already have connected your store or application with Omnisend - you have already added this snippet.
User identification:
If user is adding products to cart but isn't identified (you don't know neither user's email neither contactID) - try user identification process - available only in Backend API (see scheme above).
If you need to get user's email from contactID use API method GET contacts/{contactID}
There are several methods used to send user cart to Omnisend:
create
To create new user cart
replace
To update (replace) user cart - old data will be deleted and only new saved.
clear
clear cart (remove all products from cart)
addProduct
To add product to cart
removeProduct
To remove product from cart
Parameters used in these methods:
cartID - user's cart identificator.
You can use any unique number/string. This parameter is used to identify single users cart.
email & contactID - one of these fields is mandatory.
If user isn't identified (you don't know user's email) - you can try to get contactID from cookie (see part 3) named omnisendContactID (see part 3 - user identification).
If you'll use both of these fields - email will be used as main user identifier.
attributionID
We'll add this parameter to campaign newsletter links and write to omnisendAttributionID cookie. Pass it back with cart data. It is used to link cart with campaign or automation email.
cartRecoveryUrl
If you have ability to restore cart from url - post it to our system. We'll link abandoned cart emails to it.

When user adds it's first product, use carts create method.
When user adds more products - use one of:
addProduct
Post email, cartID and added product info
replace
Post all info - old and newly added products (it's cart sync function - all old data in Omnisend will be overwritten with the posted data).
Which method to use depends on your possibilities and wishes.

To create cart add carts create Javascript code:

<script type=" text/javascript">
soundest. push([ 'carts','create', {
email: 'email',
cartID : 'unique cart ID',
attributionID: 'campaign or workflow ID - optional',
currency: 'currency (ISO code)',
cartSum: 'total cart sum in cents',
cartRecoveryUrl: 'url to restore cart',
products: [
{
cartProductID: 'product identifier in current cart (can be random number)',
productID: 'product id',
variantID: 'product modification id',
title: 'product title',
quantity: 'quantity - integer',
price: 'price in cents',
discount: 'discount',
imageUrl: 'link to image',
productUrl: 'link to product page'
}, {
cartProductID: 'product identifier in current cart (can be random number)',
productID: 'product id',
variantID: 'product modification id',
title: 'product title',
quantity: 'quantity - integer',
price: 'price in cents',
discount: 'discount',
imageUrl: 'link to image',
productUrl: 'link to product page'
}
], callbacks: {
onSuccess: function() {
    console. log( "ok");
},
onError: function() {
    console. log( "error!");
}
}
}]);
</script>

To add product to cart add addProduct Javascript code:

<script type=" text/javascript">
soundest. push([ 'carts','addProduct', {
email: 'email',
cartID : 'unique cart ID',
cartProductID: 'product identifier in current cart (can be random number)',
productID: 'product id',
variantID: 'product modification id',
title: 'product title',
quantity: 'quantity - integer',
price: 'price in cents',
discount: 'discount',
imageUrl: 'link to image',
productUrl: 'link to product page',
callbacks: {
onSuccess: function() {
    console. log( "ok");
},
onError: function() {
    console. log( "error!");
}
}
}]);
</script>

2. Send users` orders to Omnisend

When user makes an order - add orders create Javascript code.
Parameters used in this method:
orderID - unique order number.
cartID - same cart identificator, that is used in the first step. If user‘s cart was restored and order was made - use same cartID.
We'll merge cart and order and will know that this order was made from the abandoned cart email.
paymentStatus
We have the list of predefined payment statuses, so you need to map them with your own order statuses. See bellow for available statuses.
fulfillmentStatus
We have the list of predefined fulfillment (shipping) statuses, so you need to map them with your own order statuses. See bellow for available statuses.
attributionID
We'll add this parameter to cartRecoveryUrl. Pass it back with order data. It is used to link order with abandoned cart email.

For full description view Orders (Javascript) section at API our reference
 
Order payment statuses:
  • awaitingPayment - Awaiting payment
  • paid - Order paid
  • refunded - Refunded
  • canceled - Order canceled

Order fulfillment statuses:
  • inProgress - order placed/in progress
  • fulfilled - order prepared for pickup (if delivery type pickup selected) or shipped
  • delivered - order has been picked up by or delivered to customer

To create new order add orders create Javascript code:

<script type=" text/javascript">
soundest. push([ 'orders','create', {
orderID: 'order ID',
email: 'email',
cartID: 'unique customer cart ID',
attributionID: 'campaign or workflow ID',
trackingCode: 'shipping tracking code',
courrierTitle: 'courrier title',
courrierUrl: 'link to courrier page to track order',
orderUrl: 'url to this order',
source: 'source',
discountCode: 'discount code',
currency: 'currency (ISO 4217)',
orderSum: 'total order in cents',
discountSum: 'total discount sum in cents',
taxSum: 'tax sum in cents',
shippingSum: 'shipping sum in cents',
date: 'if not passed, saved current date. ISO 8601 format. Example: 2017-06-30T17:00:00Z',
paymentStatus: 'payment status - see description for available statuses',
paymentStatusDate: 'payment status date. ISO 8601 format. Example: 2017-06-30T17:00:00Z',
fulfillmentStatus: 'fulfillment status - see description for available statuses',
fulfillmentStatusDate: 'fulfillment status date. ISO 8601 format. Example: 2017-06-30T17:00:00Z',
billingAddress: {
country: 'country',
countryCode: 'country ISO code',
state: 'state',
city: 'city',
address: 'address',
postCode: 'post code'
},
shippingAddress: {
country: 'country',
countryCode: 'country ISO code',
state: 'state',
city: 'city',
address: 'address',
postCode: 'post code'
},
products: {
productID: 'product id',
variantID: 'product modification id',
title: 'product title',
quantity: 'quantity - integer',
price: 'price in cents',
discount: 'discount',
imageUrl: 'link to image',
productUrl: 'link to product page'
},
callbacks: {
onSuccess: function() {
    console. log( "ok");
},
onError: function() {
    console. log( "error!");
}
}
}]);
</script>

You have successfully completed this step for abandoned carts.

If you want to use other automation workflows (reminder to make payment, send tracking code, send thank you email, etc.) - you also need to POST order payment or fulfillment status changes (available only in Backend API).


3. Turn on automated cart recovery or cart recovery series workflows inside the Omnisend application

Login into Omnisend application. Go to Dashborad/Automation and turn on cart recovery and/or cart recovery series workflows.
Enter needed data and edit template if you want.
Done.


4. Restore abandoned user carts`

User identification process (Backend API)


Our system will send abandoned cart email with cartRecoveryUrl link and will add to it parameters:

  • omnisendContactID - contact's identifier (contactID)
  • omnisendAttributionID - abandoned cart identificator (attributionID)

Example

http://www.your-store.com/cartrestore/cart1234567/?omnisendContactID=4785497456&omnisendAttributionID=475874693
  • Keep in mind - you need to add cart identificator to cartRecoveryUrl by your self, to be able to identify and restore user cart.
  • Our snippet will get omnisendContactID and store it to omnisendContactID cookie, and omnisendAttributionID and store it to omnisendAttributionID cookie.
  • When user will make order - remember to POST cartID and attributionID parameters in order request.
  • You can use omnisendContactIDcookie to identify user and it's cart in steps 1 and 2.

  • If you have cartID but don't have data about this cart - you can make GET carts/{cartID} request to Omnisend API and get all needed cart data.