Ordergroove Developer Documentation

Below is a list of all objects available for use in your Subscription Manager templates.

Security

Field keys marked with a 🔒 icon should not be used in your templates for the purpose of being rendered to the page. They should be treated as private information.

The Subscription Manager Objects reference is generated directly from the source code, so it always reflects the current release. This page adds the descriptions, sample payloads, and context the generated reference doesn’t have. Start here, then check the generated reference if you need to confirm exact field names and types.

locale

This value represents the current locale set on the website. The value is pulled from the lang attribute of the <html> element — for example, <html lang='en'>.

Key	Sample Value	Type
`locale`	`'en'`	string

customer

This object represents the current customer who is logged into your site and viewing the Subscription Manager.

Key	Sample Value	Description	Type
`sig_field`	`'customer123'`	Your customer’s ID, used to map the customer between Ordergroove and your ecommerce system.	string
`ts`	`1619545753`	Timestamp used to generate the authentication signature.	integer
🔒 `sig`	`'abc123zky=='`	HMAC signature used to authenticate the customer’s current session.	string
`authorized`	`true`	Indicates whether the user viewing the Subscription Manager is successfully authenticated.	boolean
`public_id`	`'abc1234556zyx'`	The ID used to identify you as the merchant.	string

merchant_id

This value is used to identify you as the merchant and is the same value found under the customer.public_id key above.

Key	Sample Value	Type
`merchant_id`	`'abc1234556zyx'`	string

environment

This object represents the environment that the application is currently running in. You typically will not need to interact with this object unless instructed to by an Ordergroove representative.

Key	Sample Value	Description	Type
`name`	`'prod'`	The name of the Ordergroove environment where the Subscription Manager is running.	string
`api_url`	`'https://api.ordergroove.com'`	URL of the legacy Ordergroove API cluster the Subscription Manager uses to retrieve data.	string
`lego_url`	`'https://restapi.ordergroove.com'`	URL of the Ordergroove REST API cluster the Subscription Manager uses to retrieve data.	string

orders

This array represents the list of all the customer’s upcoming orders. Each item is an order object with the following fields:

Key	Sample Value	Description	Type
`merchant`	`'abc1234556zyx'`	The ID used to identify you as the merchant.	string
`customer`	`'customer123'`	Your customer’s ID, used to map the customer between Ordergroove and your ecommerce system.	string
`payment`	`'pay123abc'`	The ID of the payment record associated with the order.	string
`shipping_address`	`'ship123abc'`	The ID of the shipping address record associated with the order.	string
`public_id`	`'order123abc'`	The order ID.	string
`sub_total`	`'0.00'`	The order subtotal. Inclusive of discounts but does not include tax or shipping costs.	string
`tax_total`	`'0.00'`	Any tax already applied to the order. Ordergroove typically does not calculate tax, so this value is usually `'0.00'`.	string
`shipping_total`	`'0.00'`	Any shipping cost already applied to the order.	string
`discount_total`	`'0.00'`	The total discount amount being applied to the order.	string
`total`	`'0.00'`	The total cost of the order, inclusive of any applicable discounts, taxes, and shipping costs.	string
`created`	`'2021-04-04 09:19:52'`	The date and time the order was created in Ordergroove.	string
`place`	`'2021-05-10'`	The date the order will be placed into the ecommerce system for fulfillment.	string
`cancelled`	`null`	The date the order was cancelled.	string
`tries`	`0`	The number of times Ordergroove attempted to place this order into the ecommerce system.	integer
`generic_error_count`	`0`	An internal counter for how many times an order failed to place due to an unknown error.	integer
`type`	`1`	Order type. In most cases this will be `1` to indicate a subscription order.	integer
`order_merchant_id`	`null`	Updated after the order is successfully placed with the ID of the resulting order in the ecommerce system.	string
`rejected_message`	`null`	The reason an order failed to place into the ecommerce system.	string
`extra_data`	`null`	Reserved to hold any metadata tied to the order.	object
`locked`	`false`	Set to `true` if the order has been locked and is no longer editable.	boolean
`oos_free_shipping`	`false`	Used for internal purposes — can be ignored.	boolean
`status`	`'UNSENT'`	The current status of the order. `'UNSENT'` — order will place in the future. `'SEND_NOW'` — order is currently processing and will be sent as soon as possible.	string

items_by_order

This object represents the mapping of all items making up the customer’s current orders, arranged by order.public_id to make it easier to link items back to their order. Each value is an array of item objects.

items_by_order: {
  'order123abc': [
    {
      order: 'order123abc',
      offer: null,
      subscription: 'sub123abc',
      product: 'prod123abc',
      components: [],
      quantity: 1,
      public_id: 'item123abc',
      product_attribute: null,
      extra_cost: '0',
      one_time: false,
      frozen: true,
      first_placed: '..',
      price: '0.00',
      total_price: '0.00',
      show_original_price: false
    },
    {
      order: 'order123abc',
      offer: null,
      subscription: 'sub456def',
      product: 'prod456def',
      components: [],
      quantity: 1,
      public_id: 'item456def',
      product_attribute: null,
      extra_cost: '0',
      one_time: false,
      frozen: true,
      first_placed: '..',
      price: '0.00',
      total_price: '0.00',
      show_original_price: false
    }
  ]
}

Each line item contains the following keys:

Key	Sample Value	Description	Type
`order`	`'order123abc'`	The order ID.	string
`offer`	`'offer123abc'`	The ID of an offer tied to this line item. Blank unless the item was added via the Instant Upsell feature.	string
`subscription`	`'sub123abc'`	The ID of the subscription associated with this line item. May be blank if the item was added via Instant Upsell.	string
`product`	`'prod123abc'`	The product ID associated with this item. Typically the same ID used in your ecommerce system.	string
`components`	`[]`	A list of product IDs making up this line item, if it is a legacy bundle product.	array
`quantity`	`1`	The quantity of this product the customer will receive as part of their order.	integer
`public_id`	`'item123abc'`	The item ID.	string
`product_attribute` (DEPRECATED)	`null`	This field is no longer in use.	—
`extra_cost` (DEPRECATED)	`null`	This field is no longer in use.	—
`one_time`	`false`	`false` if the item is tied to a subscription. `true` if the item was added as a one-time item via Instant Upsell.	boolean
`frozen`	`false`	Internal to Ordergroove.	boolean
`first_placed`	`null`	Internal to Ordergroove.	string
`price`	`'0.00'`	Individual price of the item.	string
`total_price`	`'0.00'`	Price of the item after any discount has been applied.	string
`show_original_price`	`true`	Determines whether a pre-discount item price should be displayed in the Subscription Manager.	boolean

subscriptions

This array represents the list of all the customer’s subscriptions. Each item is a subscription object with the following fields:

Key	Sample Value	Description	Type
`customer`	`'customer123'`	Your customer’s ID, used to map the customer between Ordergroove and your ecommerce system.	string
`merchant`	`'abc1234556zyx'`	The ID used to identify you as the merchant.	string
`product`	`'prod123abc'`	The product ID associated with this subscription. Typically the same ID used in your ecommerce system.	string
`payment`	`'pay123abc'`	The ID of the payment record associated with the subscription.	string
`shipping_address`	`'ship123abc'`	The ID of the shipping address record associated with the subscription.	string
`offer`	`'offer123abc'`	The ID of an offer tied to this subscription. Blank unless the item was added via Instant Upsell.	string
`subscription_type`	`'replenishment'`	A simplified subscription type, derived from `raw_subscription_type`. Returns `'replenishment'` for types: `replenishment`, `IU replenishment`, and `CSA replenishment`.	string
`raw_subscription_type`	`'replenishment'`	The full subscription type. `'replenishment'` — created via checkout. `'IU replenishment'` — created via Instant Upsell. `'CSA replenishment'` — created via the customer service tool in RC3.	string
`components`	`[]`	Legacy bundle components — a list of product IDs making up this line item, if it is a legacy bundle product.	array
`components`	see sample below	New bundle components — a list of objects, each with `public_id` (string), `quantity` (integer), and `product` (string).	array of objects
`extra_data`	`{}`	Reserved to hold any metadata tied to the subscription.	object
`public_id`	`'sub123abc'`	The subscription ID.	string
`product_attribute` (DEPRECATED)	`null`	This field is no longer in use.	—
`quantity`	`1`	The quantity of this product the customer will receive.	integer
`price`	`null`	Indicates a subscription price only in cases where a customer is locked into a specific price. In most cases this will be `null`.	string
`frequency_days`	`28`	The number of days before the customer’s next shipment is placed.	integer
`reminder_days`	`10`	How many days before the order is placed that a reminder email is sent.	integer
`every`	`4`	How frequently the subscription places, used together with `every_period`. E.g., `every: 4` with `every_period: 2` means every 4 weeks.	integer
`every_period`	`2`	The time period unit: `1` = Days, `2` = Weeks, `3` = Months.	integer
`start_date`	`'2021-04-04'`	The date the subscription was first started.	string
`cancelled`	`null`	The date the subscription was cancelled.	string
`cancel_reason`	`'Feeling overstocked'`	The reason the customer gave for cancelling their subscription.	string
`cancel_reason_code`	`1`	Code for the cancel reason. Can be ignored.	integer
`iteration` (DEPRECATED)	`null`	This field is no longer in use.	—
`sequence` (DEPRECATED)	`null`	This field is no longer in use.	—
`session_id`	`'session123abc'`	The session ID assigned to the customer during their checkout.	string
`merchant_order_id`	`'mid123abc'`	The ID of the order in your ecommerce system that resulted in the creation of this subscription.	string
`customer_rep` (DEPRECATED)	`null`	This field is no longer in use.	—
`club` (DEPRECATED)	`null`	This field is no longer in use.	—
`created`	`'2021-04-04 10:13:26'`	The timestamp when this subscription record was created.	string
`updated`	`'2021-05-10 16:50:17'`	The timestamp when this subscription record was last updated.	string
`live`	`true`	Determines if this subscription is still active. Set to `false` when the customer cancels.	boolean

For a new bundle subscription, components looks like this:

[
  {
    "public_id": "79d2dc76245111eeb185acde48001122",
    "quantity": 1,
    "product": "0070067690"
  },
  {
    "public_id": "7eeaa504245111eeb185acde48001122",
    "quantity": 3,
    "product": "0070067691"
  }
]

localized_product_by_id

This object represents the mapping of all products the customer is currently subscribed to, arranged by product.id. It contains product details translated to the current website locale.

localized_product_by_id: {
  'prod123abc': {
    merchant: 'abc1234556zyx',
    groups: [
      { group_type: 'sku_swap', name: 'swap-size' },
      { group_type: 'eligibility', name: 'subscription' }
    ],
    name: 'B6 Vitamin',
    price: '1.99',
    image_url: 'https://mystore.com/images/b6vitamin.png',
    detail_url: 'http://mystore.com/vitamins/b6vitamin',
    external_product_id: 'prod123abc',
    sku: '1',
    autoship_enabled: true,
    premier_enabled: 1,
    created: '2014-05-19 18:13:43',
    last_update: '2020-08-11 12:58:43',
    live: true,
    discontinued: false,
    offer_profile: null,
    extra_data: {
      i18n_display: {
        'fr-CA': {
          name: 'B6 Vitamine',
          image_url: 'https://mystore.com/fr/images/b6vitamin-fr.png',
          detail_url: 'http://mystore.com/fr/vitamins/b6vitamin'
        }
      }
    },
    incentive_group: null,
    product_type: 'standard',
    autoship_by_default: false,
    every: null,
    every_period: null
  }
}

Each product contains the following keys:

Key	Sample Value	Description	Type
`merchant`	`'abc1234556zyx'`	The ID used to identify you as the merchant.	string
`groups`	`[]`	All groups this product belongs to. Used for features like SKU swap.	array
`name`	`'B6 Vitamins'`	The product name. Localized — the value may differ based on the active website locale.	string
`price`	`'0.00'`	The base price of the item as it appears in your ecommerce system.	string
`image_url`	`'https://...'`	The product image URL. Localized — the value may differ based on the active website locale.	string
`detail_url`	`'https://...'`	The product detail page URL. Localized — the value may differ based on the active website locale.	string
`external_product_id`	`'prod123abc'`	The product ID. Should match the ID used to identify products in your ecommerce system.	string
`sku`	`'prod_sku123abc'`	The SKU ID of the product.	string
`autoship_enabled`	`true`	Determines if the product is eligible for subscription. If `false`, customers cannot create new subscriptions for this product.	boolean
`premier_enabled` (DEPRECATED)	`null`	This field is no longer in use.	—
`created`	`'2014-05-19 18:13:43'`	The timestamp when the product was first created in Ordergroove.	string
`last_update`	`'2020-08-11 12:58:43'`	The timestamp when the product was last updated in Ordergroove.	string
`live`	`true`	Determines if the product is currently in stock in your ecommerce system.	boolean
`discontinued`	`false`	Determines if the product has been discontinued.	boolean
`offer_profile` (DEPRECATED)	`null`	This field is no longer in use.	—
`extra_data`	`{}`	Reserved to hold any metadata tied to the product. Commonly includes localized product name, image, and URL.	object
`incentive_group`	`null`	Any custom incentive group this product may belong to.	—
`product_type`	`'standard'`	`'standard'` for regular products, `'bundle'` for legacy bundle products. New bundles use `'dynamic price bundle'` or `'static price bundle'`.	string
`autoship_by_default`	`false`	If `true`, the default selection on the product detail page will be to subscribe.	boolean
`every` (DEPRECATED)	`null`	This field is no longer in use.	—
`every_period` (DEPRECATED)	`null`	This field is no longer in use.	—

address_by_id

This object represents the mapping of all customer address records, keyed to the address ID.

address_by_id: {
  'address123abc': {
    customer: 'customer123',
    public_id: 'address123abc',
    label: null,
    first_name: 'Harry',
    last_name: 'Potter',
    company_name: 'Hogwarts',
    address: 'Platform 9¾',
    address2: 'Kings Cross Station',
    city: 'London',
    state_province_code: null,
    zip_postal_code: 'N1 9AP',
    phone: '555-555-5555',
    fax: null,
    country_code: 'GB',
    live: true,
    created: '2021-04-26 16:40:00',
    token_id: null,
    store_public_id: null
  }
}

Each address contains the following keys:

Key	Sample Value	Description	Type
`customer`	`'customer123'`	Your customer’s ID, used to map the customer between Ordergroove and your ecommerce system.	string
`public_id`	`'address123abc'`	The address record ID.	string
`label`	`'home'`	A custom label for the address, if one exists.	string
`first_name`	`'Harry'`	The first name of the person the shipment is addressed to.	string
`last_name`	`'Potter'`	The last name of the person the shipment is addressed to.	string
`company_name`	`'Hogwarts'`	The company name tied to the address.	string
`address`	`'Platform 9¾'`	The first line of the address, typically including a street name and number.	string
`address2`	`'Kings Cross Station'`	The second line of the address, typically used for apartment or suite details.	string
`city`	`'London'`	The city of the address.	string
`state_province_code`	`null`	The state, province, or region of the address.	string
`zip_postal_code`	`'N1 9AP'`	The zip or postal code of the address.	string
`phone`	`'555-555-5555'`	The phone number tied to the address.	string
`fax`	`null`	The fax number tied to the address.	string
`country_code`	`'GB'`	The two-letter country code tied to the address.	string
`live`	`true`	Determines if this address is currently tied to an upcoming order or subscription.	boolean
`created`	`'2021-04-04 16:40:00'`	The timestamp when the address record was created.	string
`token_id` (DEPRECATED)	`null`	This field is no longer in use.	—
`store_public_id`	`'store123'`	The ID of the physical store tied to this address.	string

payment_by_id

This object represents the mapping of the payment records tied to the subscriptions and orders currently loaded in the Subscription Manager, keyed to the payment ID.

The Subscription Manager only fetches the data it needs to render the page, so payment_by_id contains the payment records tied to the subscriptions and orders being displayed — not every payment record on the customer’s account.

payment_by_id: {
  'payment123abc': {
    customer: 'customer123',
    billing_address: 'address123abc',
    cc_number_ending: '1111',
    public_id: 'payment123abc',
    label: null,
    token_id: 'token123',
    cc_holder: 'Harry Potter',
    cc_type: 'Visa',
    cc_exp_date: '12/2023',
    payment_method: 'credit card',
    live: true,
    created: '2021-04-04 09:46:38',
    last_updated: '2021-05-10 14:29:38'
  }
}

Each payment record contains the following keys:

Key	Sample Value	Description	Type
`customer`	`'customer123'`	The ID of the customer tied to this payment record.	string
`billing_address`	`'address123abc'`	The ID of the billing address tied to this payment record.	string
`cc_number_ending`	`'1111'`	The last four digits of the credit card number.	string
`public_id`	`'payment123abc'`	The payment record ID.	string
`label`	`null`	A custom label for the payment record, if one exists.	string
`token_id`	`'token123'`	The payment token ID stored in the ecommerce system.	string
`cc_holder`	`'Harry Potter'`	The name of the account holder.	string
`cc_type`	`'Visa'`	The card brand: `'Visa'`, `'Mastercard'`, `'American Express'`, `'Discover'`, `'Diners'`, or `'JCB'`. The API returns a numeric credit card type, which the Subscription Manager converts to the brand name. Empty for payment methods without a card, such as PayPal.	string
`cc_exp_date`	`'12/2023'`	The month and year the credit card expires.	string
`payment_method`	`'credit card'`	The payment method, in lowercase: `'credit card'`, `'paypal'`, `'applepay'`, `'shoppay'`, or `'googlepay'`.	string
`live`	`true`	Determines if this payment record is currently tied to an upcoming order or subscription.	boolean
`created`	`'2021-04-04 09:46:38'`	The timestamp when the payment record was created.	string
`last_updated`	`'2021-05-10 14:29:38'`	The timestamp when the payment record was last updated.	string