> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.ordergroove.com/lifecycle/sm/object-reference/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. --- ## 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* | 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 | --- ## 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 all customer payment records, keyed to the payment ID. ```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: 1, cc_exp_date: '12/2023', payment_method: 1, 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` | `1` | The credit card issuer: `1` = Visa, `2` = Mastercard, `3` = American Express, `4` = Discover, `5` = Diners, `6` = JCB. | integer | | `cc_exp_date` | `'12/2023'` | The month and year the credit card expires. | string | | `payment_method` | `1` | The payment method: `1` = Credit Card, `2` = PayPal. | integer | | `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 | > APIs, SDKs, and guides for building subscription commerce with Ordergroove.