Sync Ordergroove Data into Internal Systems
Syncing Ordergroove data into your data warehouse or external systems enables deeper analysis and more seamless integration of subscription data with the rest of your business data.
This guide is designed for data engineers and analysts who want to build a reliable pipeline to extract Ordergroove data and upsert it into your data warehouse for analytics and operational use. It provides an overview of the Ordergroove data model, along with best practices for incremental data fetching, pagination, and handling edge cases. The goal is to ensure your data integration is efficient, resilient, and aligned with how Ordergroove’s APIs are designed.
Ordergroove’s Data Model
Ordergroove’s platform centers around subscriptions and recurring orders. For a more detailed look, see Data Model at a Glance.
ERD Flowchart (click to view full size)
Objects and Events
Objects represent the current state of entities in your Ordergroove program—such as subscriptions, customers, or orders. You can access this data by polling the Ordergroove API, which returns a snapshot of an object at the time of the request. However, this method doesn't show how that state came to be. For example, if a customer cancels a subscription and later reactivates it, the API response will simply show the current live status as true.
Events, on the other hand, capture each meaningful change that occurs. Ordergroove emits events when key actions happen—like when a subscription is created, canceled, or reactivated—and delivers them to your server via webhooks in near real time. By subscribing to these webhooks, you gain visibility into the sequence of actions that led to the current state, such as receiving both subscription.change_live and subscription.reactivate events for the scenario above.
Syncing Data across Ordergroove and an Internal Systems
There are several ways to sync data between the two systems, depending on the type of data you want to receive.
| Use Case | Recommended Method | Alternative Method |
|---|---|---|
| Sync entities | • Build your own Data Pipelines using APIs • Use pre built Ordergroove Connectors | • SFTP file drops Note: Available only for ongoing deltas, no full historic backfill |
| Sync events | • Webhooks | • Reach out to a solutions team member via [email protected] if the webhook option does not work for your team |
FAQ
Q: Why is a Subscription not directly linked to an Order, but instead through Items?
An Order in Ordergroove represents a shipment, a “box”, which can include items from multiple subscriptions, as long as they're shipping to the same customer, at the same address, and using the same payment method. Because of this, the Item is the direct link between a Subscription and an Order. A single order can include items from multiple subscriptions, but each item belongs to only one subscription.
Q: Why does the Item object not have its own updated timestamp?
When an Item is changed, Ordergroove automatically recalculates the associated Order, and the Order’s updated timestamp is updated to reflect that change. This means the updated field on the Order represents the last change to any of its associated Items.
Q: When are future Items and Orders created?
Ordergroove maintains a single upcoming Item and Order for each subscription. A new future item/order is created just before the current scheduled order is processed.
Q: Why do I see a large number of Orders updated during overnight or early morning hours?
Order placement is a background system process, not triggered by user activity. Based on your configuration, Ordergroove will process scheduled orders in bulk, often during middle of the night, resulting in many Orders receiving updated timestamps even if there was no customer interaction at that time.
Q: How often should I schedule an incremental refresh?
We recommend syncing data once per day. If your business requires fresher data, you can schedule a second incremental sync twice a day. Refer to the ETL Scheduling section for more details.
Q: What time of day should I schedule my sync?
We recommend scheduling your main daily sync between 12PM CST and 8PM CST, after most order processing is complete. This helps ensure you capture a full day of updates. Be sure to adjust for your local time zone, as Ordergroove data is timestamped in EST.
Q: Why should I start from the start time of the last job, not the end time?
To avoid missing records, always begin your next incremental sync using the start time of the previous job. This ensures you don’t skip any objects created or updated just after the previous sync began but before it completed.
Q: Can I make concurrent API requests to speed up syncing?
Do not parallelize API requests for the same object type. Ordergroove’s API uses cursor-based pagination, which must be consumed sequentially. You can fetch different object types (e.g., Subscriptions and Customers) in parallel, but each individual resource should be synced with a single threaded process. If performance is a concern, please contact the Ordergroove support team.
Q: Are deleted Orders and Items available through the API?
No, deleted Orders and Items are not accessible via the API. Once removed, they won’t appear in list endpoints and there's no flag to indicate deletion. To handle deletions, we recommend subscribing to webhook events like order.delete and item.remove. See the Deleted Records section for full details.
References
Updated 1 day ago