Skip to navigation
Developer FundamentalsPlatform Overview

Data model at a glance

The four core objects that power Ordergroove.
View as Markdown

Ordergroove’s data model provides flexibility for merchants with a structure that supports full automation or merchant-specific processes via REST APIs. Data is stored in a relational database, with one-to-one and one-to-many relationships depending on how you look at the data.

There are four main data objects:

Customer
Subscription
Items
Order
Diagram titled Subscriptions vs Items vs Orders, with four columns: Customer (customer_customer), Subscriptions (subscription_subscription), Items (order_item), and Orders (order_order). The customer John Smith has two subscriptions, both created September 1: Subscription 1 for Extra Caffeine Coffee every 1 month, and Subscription 2 for Decaf Coffee every 2 months. Subscription 1 has an item in the October 1 order and another in the November 1 order. Subscription 2 has an item in the November 1 order, alongside a one-time Hot Chocolate item that isn't tied to any subscription. A footnote says that, except for some Instant Upsell subscriptions, the subscription's product ID isn't associated with the item on the back end until the order is placed.

API ERD

This entity relationship diagram (ERD) shows the fields on each API object and the keys that link them.

Entity relationship diagram of 12 API objects, listing each object's fields and marking primary keys (PK) and foreign keys (FK). Subscription links to Customer, Product, Payment, a shipping Address, and CancellationReason. Item links to Subscription, Order, and Product. Order links to Customer, Payment, and a shipping Address. OneTimeIncentive links to Customer, Order, and Item. Payment links to Customer and a billing Address. Address links to Customer. Product links to ProductGroup and OfferProfile, and ProductRelationship links one Product to another. Customer is keyed by merchant_user_id, Product by external_product_id, and CancellationReason by cancel_reason. Every other object is keyed by public_id.

Merchant

Every business and unique integration on Ordergroove has its own merchant record. Businesses with multiple sites (separate brands, locales, and so on) typically have one merchant per site. A merchant is usually represented by a Merchant Public ID when interacting with Ordergroove API endpoints.

Customer

Customers are created in Ordergroove via the Purchase POST or 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 your 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, 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 the 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 associated with this subscription
  • shipping_address_id — Ordergroove address ID associated with this subscription
  • frequency_days — days between each subscription order’s place date
  • offer_id — the Ordergroove offer ID tied to the subscription, which links incentive logic for recurring orders to the subscription
  • merchant_order_id — the eCommerce order number that created the subscription
  • live — 0 = customer has no active subscriptions; 1 = at least one active subscription
  • every — numeric value of frequency
  • every_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 with your eCommerce platform. Orders contain one or more items, and their place date is previous order date + subscription frequency. Subscriptions only have one upcoming order; a subsequent order is created once the current order is placed.

Important order information

  • id — Ordergroove order ID
  • public_id — public order ID
  • customer_id — Ordergroove customer ID
  • place — placement date (future for unsent orders, past for attempted orders)
  • status — current state of the order. Order Status Codes has the full list; these are the most common:
    • 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 — ID returned by eCommerce platform on successful 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 added to a single order.

Important item information

  • id — Ordergroove item ID
  • public_id — public item ID
  • order_id — Ordergroove order ID
  • subscription_id — Ordergroove subscription ID (null for one-time Instant Upsell items)
  • product_id — Ordergroove product ID (may be null for upcoming subscription items; populated after the order places)
  • quantity — item quantity
  • price — unit price
  • total_price — line item price accounting for quantity and discount
  • offer_id — Ordergroove offer ID tied to the item, which links incentive logic for recurring orders to the subscription. It may be null for subscriptions created with the Subscription Create in Order endpoint.
  • one_time — indicates the item was added via 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, plus subscription-specific attributes that control an individual product’s eligibility for recurring purchase.

Important product information

  • id — Ordergroove product ID
  • price — product price from the product feed; the base price Ordergroove uses
  • external_product_id — the product’s unique identifier in your eCommerce platform
  • autoship_enabled — 0 = not subscribable; 1 = available for subscription