We know that there are endless benefits to having a custom order management system (ease, flexibility, customization), and our API was built for developers just like you. In this guide, we’ll go through everything you need to know to integrate your order management system with Drip via API.
Before we dive in, there are four major data sets you need to sync:
-
People
-
Products
-
Orders
-
Carts
We recommend doing a historical sync for your people, products, and orders. People are the foundation for all of your marketing strategies, and performing a historical sync unlocks the full power of Drip’s ecommerce marketing engine such as product recommendations, behavior-based segmentation, and more. Including your product catalog allows you to personalize and tailor all of your communication via in-email product blocks as well as powerful order and product segmentation. Order history is a crucial piece for segmentation and product recommendations.
Want to jump right into the API documentation? Check out our Developer Docs.
General Implementation Notes
Here are a few common troubleshooting tips to note before you get started.
-
Make sure you support getting a 429 rate-limiting response. We use this response to provide back pressure when we’re getting more data than we can handle. You will almost always encounter this in the form of the defined rate limits we describe in the API documentation.
-
Confirm that you can handle resending the payload. Another common implementation problem is to not support 429 responses and instead try to never exceed the rate limits through the use of timers. Your system will likely break at some point if it doesn’t support these responses. A common solution for this is to delegate the Drip API sending to background jobs which can retry with a backoff.
-
Send the occurred_at field for all order, cart, and product events set to the date in your database. This provides the highest level of accuracy and also allows you to easily do resyncs. If the occurred_at field isn’t sent to us, we’ll set it to the time we received the event.
-
Don’t forget about other events, such as refunds, returns, and cancellations.
Historical Sync
Use Drip’s Batch API when you perform a historical sync. The Batch API allows you to send large piles of data in the same request, and we can process it more efficiently. (Which is why the API rate limits are higher!)
In the event that something breaks or gets disconnected, don’t fear. You can resync your store and the existing data will be overwritten with what you send (this is the same as a normal historical sync).
Live Sync
Send events to Drip as changes come through your system so Workflows and Segments can react to these events. You can send events to Drip on an individual basis or by batching them up and sending them through the batch API. If your system can handle the batch API we recommend using it, but if not, you can send events on an individual basis. Deciding which one to use depends on the throughput of events and the load on your system from these requests.
Subscriber Status
Drip supports engaging with all people, which means that you’re able to send marketing and transactional email to your customers. Marketing emails are the emails that your customers explicitly subscribed to or opted-in to receive, and transactional emails are emails sent to facilitate an agreed-upon transaction between the sender and the recipient (such as making a purchase).
We track people’s email preferences with the status field. When you send the status field to Drip, we will update that person’s subscribed status accordingly. We require defaulting to unsubscribed unless you have explicitly obtained their consent for marketing emails. This is required by GDPR and other privacy regulations.
In order to not depend on a two-way sync, we also have the initial_status field. This allows you to provide a hint to Drip when you think you know the subscription status, but Drip might have more up-to-date information. There are two common causes, which we’ll discuss next.
OMS Has a Built-In Subscription Status
Magento is an example of an OMS that has a built-in subscription status. Drip defaults to Magento’s subscription status unless told otherwise. For example, to handle Magento’s built-in subscription status, we sent the initial_status field set to whatever the Magento subscriber’s status was unless we knew that they had just changed their status. So if they added something to their cart, we would send a cart updated event, with initial_status set to whatever Magento already had. But if they placed an order and checked the “Subscribe to Newsletter” box, we would send the “status” field set to “active”. Drip only cares about Magento’s subscription status if we’re creating the record in Drip for the first time, or if the status just changed.
This presumes that Drip is the source of truth for subscription status. Since the individual would normally unsubscribe by clicking the unsubscribe link at the bottom of a Drip email, Drip is best suited to be the source of truth on this.
OMS Doesn’t Have a Built-In Subscription Status
WooCommerce is an example of an OMS which doesn’t track subscription status internally. In this case, we send all events with initial_status set to unsubscribed. When the customer checks the “Subscribe to Newsletter” checkbox on checkout, we would send the status field set to ”active”.
You will want to set status or initial_status on all events, including order and cart events. When we receive an order for an individual not previously in Drip, we’ll create a new person record for them automatically. For historical reasons, we default to subscribed, unless you set initial_status to unsubscribed.