> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ordergroove.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ordergroove.com/_mcp/server.

# Data model at a glance

Ordergroove's data model provides flexibility for end users with a structure that supports full
automation or client-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

## Merchant

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

## Customer

Customers are created in Ordergroove via 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
* `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
* `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 data**

* `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; common values include:
  * `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 data**

* `id` — Ordergroove item ID
* `public_id` — public item ID
* `order_id` — Ordergroove order ID
* `subscription_id` — Ordergroove subscription ID (null for one-time IU)
* `product_id` — Ordergroove product ID (null for upcoming items, populated after placement)
* `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
* `one_time` — indicates the item was added via the Item Create In Order endpoint

**Key relationships**

* Items → Subscriptions
* Items → Orders
* Items → Offer (incentive)

## Product

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 data**

* `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