> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.ordergroove.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.ordergroove.com/_mcp/server. # Object Reference 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](https://static.ordergroove.com/@ordergroove/smi-core/latest/docs/modules/Objects.html) 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 `` element — for example, ``. | 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`. ```json 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: ```json [ { "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. ```json 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. ```json 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. > **Info** > > 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. ```json 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](/api-reference/credit-card-types), 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 |