Guides

Data model at a glance

Suggest Edits

Overview

Ordergroove’s data model is designed to provide flexibility to end users with a structure that allows for full automation or client-specific processes via rest APIs. All data is stored in a Relational Database, with both one-to-one and one-to-many relationships depending on how you look at the data.

There are four main data objects:

  1. Customer
  2. Subscription
  3. Items
  4. Order

API ERD


Merchant

Every Ordergroove client and unique integration has a merchant record in Ordergroove. Some clients may have multiple sites (separate brands, locales, etc); these are usually separate Merchants in Ordergroove. A merchant is usually represented by a Merchant Public ID when interacting with Ordergroove API endpoints.

Customer

Customers are created in Ordergroove via purchase post, or via customer migrations from other platforms. Customers have Subscriptions, which are tied to active customer Address and Payment information.

Important Customer Data

  • id (Ordergroove customer ID)
  • merchant_id (Ordergroove Merchant ID)
  • merchant_user_id (customer ID in eCommerce platform)
  • first_name (encrypted)
  • last_name (encrypted)
  • email (encrypted)

Key Relationships

  • Customer > Subscription
  • Customer > Order
  • Customer > Address
  • Customer > Payment

Subscription

Customers have subscriptions. Each product a customer is subscribed to is its own subscription, and is referenceable via a subscription public ID. A subscription creates a recurring order based on the subscription’s frequency, and the discounts applied to the item or order subtotal are determined by the Offer ID associated with the subscription.

Important Subscription Data

  • id (Ordergroove subscription ID)
  • public_id (public Subscription ID)
  • customer_id (Ordergroove customer ID of customer associated with this subscription)
  • product_id (Ordergroove product ID, the product subscribed to)
  • quantity (quantity of product subscribed to)
  • payment_id (Ordergroove payment ID, the payment object associated with this subscription)
  • shipping _address_id (Ordergroove payment ID, the shipping address object associated with this subscription)
  • frequency_days (number of days between each subscription order’s place date)
  • offer_id (the Ordergroove offer ID tied to the subscription, this links incentive logic for recurring orders to the subscription)
  • merchant_order_id (the ecommerce order number that created the subscription)
    live (Boolean value, live=0 customer has no active subscriptions, live=1 customer has at least one active subscription)
  • every (numeric value of frequency)
  • Every_period (numeric value of the frequency period, 1=days, 2=weeks, 3=months, 4=years)

Key Relationships

  • Subscription > Item
  • Subscription > Offer (incentive)

Order

Orders are created by subscriptions, and contain items and all relevant information used to place orders to your eCommerce platform. Orders contain one or more items, and their place date is determined by previous order date + subscription frequency. Subscriptions only have one upcoming order, a subsequent order will be created when the current order is placed.

Important Order Information

  • id (Ordergroove order ID)
  • public_id (public order ID)
  • customer_id (Ordergroove customer ID of customer associated with this subscription)
  • place (the date the order placement date, either a future date for unsent orders or a past date for orders that have been attempted)
  • Status (current state of the order in the Ordergroove system) - We have a full list in Order Status Codes, but here are some of the most common statuses:
    • 1 - unsent
    • 3 - rejected
    • 5 - success
    • 6 - send now
    • 11 - pending placement
    • 15 - generic error
    • 18 - credit card retry
  • sub_total (order subtotal after subscription discounts)
  • shipping_total (shipping fee applied by Ordergroove)
  • total (sub_total + shipping_total)
  • order_merchant_id (order ID returned by eCommerce platform upon successful order placement)
  • payment_id (ID of the payment record used for the order)
  • shipping_address_id (ID of the shipping address record used for the order)

Key Relationships

  • Order > item
  • Order > One Time Incentive

Items

Items are the individual products within an order. They may be associated with a subscription, or can be a one-time product that was added to a single order.

Important Item Information

  • Id (Ordergroove item ID)
  • Public_id (public item ID)
  • Order_id (Ordergroove order ID associated with the item)
  • Subscription_id (Ordergroove subscription ID associated with the item - will be NULL for one-time IU)
  • Product_id (Ordergroove product ID for the item - may be NULL for upcoming subscription items and will be populated after the order places)
  • Quantity (item quantity)
  • Price (unit price)
  • Total_price (line item price accounting for quantity and discount
  • Offer_id (the Ordergroove offer ID tied to the item, this links incentive logic for recurring orders to the subscription - this may be NULL for subscriptions created using the Subscription Create In Order endpoint)
  • One_time (Boolean indicator of the item being added using the Item Create In Order endpoint)

Key Relationships

  • Items > Subscriptions
  • Items > Orders
  • Items > Offer (Incentive)

Product Information

Products is a replication of relevant product data from your eCommerce site, along with subscription-specific attributes to control an individual product’s eligibility for recurring purchase.

Important Product Information

  • Id (OG product ID)
  • Price (product price received from product feed, the base price Ordergroove uses)
  • External_product_id (the product’s unique identifier in your eCommerce platform)
  • Autoship_enabled (Boolean value, autoship_enabled=0 the product is not available to be subscribed to on your website, autoship_enabled=1 the product is available to be subscribed to on your website

Updated 6 months ago