Guides

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 Backend API. 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.
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 ' { \
"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, \
"oldPrice":69666, \
"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, \
"oldPrice":14111, \
"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": "[email protected]", \
"phone": "+12025550142", \
"products": [ \
{ \
"cartProductID": "1", \
"discount": 0, \
"imageUrl": "http://www.omnisend.com/images/products/prod-666.png", \
"price": 66666, \
"oldPrice": 69666, \
"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.

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:
  • unfulfilled - order placed
  • 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": "[email protected]", \
"phone": "+12025550142", \
"cartID": "4557116516", \
"trackingCode": "666", \
"tags": ["vip","urgent"], \
"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, \
"tags": ["containers","metal""], \
"categoryIDs": ["cat-112","cat-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)

Example:

http://www.your-store.com/cartrestore/cart1234567/?omnisendContactID=4785497456
  • 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.
  • When user will make order - remember to POST cartID parameter 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.