Object Reference

Below is a list of all objects which are available for you to use to help you modify your Subscription Manager experience.

❗️

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 will represent the current locale being set on the website. The value is pulled form the lang attribute of the html node. For example <html lang='en'>

KeySample ValueType
locale'en'String

customer

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

KeySample ValueDescriptionType
sig_field'customer123'This field represents your customer's id. This id is used to map the customer between Ordergroove and your ecommerce system.string
ts1619545753Timestamp used to generate the authentication signature.integer
🔒sig'abc123zky=='HMAC Signature used to authenticate the customer's current session.string
authorizedtrueIndicates whether a user who is viewing the Subscription Manager is successfully authenticated.boolean
public_id'abc1234556zyx'This id is 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 that you would find under the customer.public_id key above.

KeySample Valuetype
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 you're instructed to by an Ordergroove representative.

key sample value description type
name 'prod' The name of the Ordergroove environment where the Subscription Manager is currently running. string
api_url 'https://api.ordergroove.com' URL of the legacy Ordergroove API cluster that the Subscription Manager is using to retrieve data. string
lego_url 'https://restapi.ordergroove.com' URL of the Ordergroove REST API cluster that the Subscription Manager is using to retrieve data. string

orders

This array represents the list of all of the customer's upcoming orders. Each item in this list is an order object and contains the following fields:

key sample value description type
merchant 'abc1234556zyx' This id is used to identify you as the merchant. string
customer 'customer123' This field represents your customer's id. This id is used to map the customer between Ordergroove and your ecommerce system. string
payment 'pay123abc' This is the id of the payment record associated with the order. string
shipping_address 'ship123abc' This is the id of the shipping address record associated with the order. string
public_id 'order123abc' This is the order id. string
sub_total '0.00' This is the order sub total. Inclusive of discounts but does not include tax and shipping costs. string
tax_total '0.00' Any tax which was already applied to the order. (Please note that Ordergroove typically does not calculate tax so this value will most likely be '0.00') string
shipping_total '0.00' Any shipping cost which was 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 that the order was created by the Ordergroove system. string
place '2021-05-10' The date that the order will be placed into the ecommerce system for fulfillment. string
cancelled null The date that the order was cancelled. string
tries 0 The amount of times that the Ordergroove system attempted to place this order into the ecommerce system. integer
generic_error_count 0 An internal counter to determine how many times an order failed to place due to a unknown error. integer
type 1 A order type. In most cases this value will be set to 1 to indicate that this is a subscription order. integer
order_merchant_id null This field is updated after the order is successfully placed with the id of the resulting order in the ecommerce system. string
rejected_message null The reason that an order failed to place into the ecommerce system. string
extra_data null This field is reserved to hold any meta data tied to the order. object
locked false This field will be set to true if the order has been locked and is no longer in an editable state. boolean
oos_free_shipping false This field is used for internal purposes and can be ignored. boolean
status 'UNSENT' This field is used to determine the current status of the order. List of possible order status which are important to note:


'UNSENT'- Order will be placing some time 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 of the items which make up the customer's current set of orders. This list is arranged by the order.public_id to make it easier for you to link items back to the order that they belong to. Each value in this list contains an array of item objects. In order to help visualize this, we have provided a sample json object in addition to the description of each item object key representation below:

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 in the map above contains the following keys

key sample value description type
order 'order123abc' This is the order id. string
offer 'offer123abc' This is the id of an offer which is tied to this line item. Please note that this field is blank unless the item was added via the Instant Upsell feature. string
subscription 'sub123abc' This is the id of the subscription that this line item is associated with. Please note that this field might be blank if the item was added via the Instant Upsell feature. string
product 'prod123abc' This is the product id which is associated with this item. This is typically the same product id which you can use to find the product in your ecommerce system. string
components [ ] This is a list of product ids which make up this line item, if the line item happens to be a legacy bundle product. array
quantity 1 This is the quantity of this product that the customer will be receiving as part of their order. integer
public_id 'item123abc' This is the id of the item 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 This field is set to false if an item is tied to a subscription. If the item was added as a one-time item via Instant Upsell, then the value will be true. boolean
frozen false Internal to Ordergroove boolean
first_placed null Internal to Ordergroove string
price '0.00' Individual price of an item string
total_price '0.00' Price of an item after a discount has been applied to it. string
show_original_price true This value is there to help determine if a pre-discount item price should be displayed in the Subscription Manager boolean

subscriptions

This array represents the list of all of the customer's subscriptions. Each item in this list is a subscription object and contains the following fields:

key sample value description type
customer 'customer123' This field represents your customer's id. This id is used to map the customer between Ordergroove and your ecommerce system. string
merchant 'abc1234556zyx' This id is used to identify you as the merchant. string
product 'prod123abc' This is the product id which is associated with this item. This is typically the same product id which you can use to find the product in your ecommerce system. string
payment 'pay123abc' This is the id of the payment record associated with the order. string
shipping_address 'ship123abc' This is the id of the shipping address record associated with the order. string
offer 'offer123abc' This is the id of an offer which is tied to this line item. Please note that this field is blank unless the item was added via the Instant Upsell feature. string
subscription_type 'replenishment' This field identifies the subscription based on a specific type. This is a subset of the raw_subscription_type field below. This field will return 'replenishment' for the following raw types:


- replenishment
- IU replenishment
- CSA replenishment
string
raw_subscription_type 'replenishment' This field identifies the subscription based on a specific type. List of possible subscription types which are important to note:


replenishment'- Subscription created via a customer's checkout


'IU replenishment'- Subscription created via the Instant Upsell feature


CSA replenishment- Subscriptions created via the customer service tool in RC3.
string
components [ ] Legacy Bundle Components. This is a list of product ids which make up this line item, if the line item happens to be a bundle product. array
components [ { "public_id": "79d2dc76245111eeb185acde48001122", "quantity": 1, "product": "0070067690" }, { "public_id": "7eeaa504245111eeb185acde48001122", "quantity": 3, "product": "0070067691" } ] New Bundle components list of objects array of objects: { public_id:string quantity:integer product:string }
extra_data { } This field is reserved to hold any meta data tied to the subscription. object
public_id 'sub123abc' This is the id of the subscription. string
product_attribute
DEPRECATED
null This field is no longer in use.  
quantity 1 This is the quantity of this product that the customer will be receiving. integer
price null This will indicate a subscription priceonlyin cases where a customer is locked into a specific price. In most cases this value will be null and can be ignored. string
frequency_days 28 The amount of days that a customer will go before their next shipment is placed integer
reminder_days 10 This number will indicate how far ahead do we want to send the order reminder to the customer. For example a value of 10 means that we will send the order reminder email 10 days before this order is actually placed. integer
every 4 This indicates how frequently this subscription will be placed. It is used together with the every_period field to determine the cadence. For example:


every: 4
every_period: 2

Means that the subscription will place every 4 weeks.
integer
every_period 2 This indicates a time period.


1 = Days
2 = Weeks
3 = Months
integer
start_date '2021-04-04' This is the date when the subscription was first started. string
cancelled null This is the date when the subscription was cancelled. string
cancel_reason 'Feeling overstocked' This is the reason that the consumer gave for why they decided to cancel their subscription. string
cancel_reason_code 1 Code for the cancel reason. You can ignore this field 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 which was assigned to the customer during their checkout. string
merchant_order_id 'mid123abc' This is the id of the order in your ecommerce system which 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 time stamp of when this subscription record was created. string
updated '2021-05-10 16:50:17' The time stamp of when this subscription record was last updated string
live true Determines if this subscription is still active. Once a customer decides to cancel their subscription, this flag will be set to false. boolean

localized_product_by_id

This object represents the mapping of all of the products which the customer is currently subscribed to. This list is arranged by product.id and it contains the product details, translated to the current website locale. In order to help visualize this, we have provided a sample json object in addition to the description of each item object key representation below:

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 in the object above contains the following keys

key sample value description type
merchant 'abc1234556zyx' This id is used to identify you as the merchant. string
groups [ ] This will contain all of the groups that a product currently belongs to. There are some complex use-cases within the Ordergroove system like sku swap that make use of this field array
name 'B6 Vitamins' The name of the product. Please note that this field is localized so the value may be different, depending on the currently 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 url of the product image. Please note that this field is localized so the value may be different, depending on the currently active website locale. string
detail_url 'https://...' The url of the product detail page. Please note that this field is localized so the value may be different, depending on the currently active website locale. string
external_product_id 'prod123abc' The id of the product. This should be the same id that you use to identify products in your ecommerce system. string
sku 'prod_sku123abc' The sku id of the product. string
autoship_enabled true This field determines if a product is currently marked as eligible for subscription. If this field is marked is false then visitors on your website will not be able to create new subscriptions tied to this product. boolean
premier_enabled
DEPRECATED
null This field is no longer in use.  
created '2014-05-19 18:13:43' The time stamp of when the product was first created in our system. string
last_update '2020-08-11 12:58:43' The time stamp of when the product was lasted updated in our system. 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 { } This field is reserved to hold any meta data tied to the product. A common data element which can be found here would be the localization of product name, image and url. object
incentive_group null Any custom incentive group that this product may belong to.  
product_type 'standard' This field will return 'standard' for regular products and 'bundle' for products that contain other product components for legacy bundles. New bundles integration uses 'dynamic price bundle' and 'static price bundle' string
autoship_by_default false If this field is set to true, then the default choice for a customer when they are browsing the product on a product detail page will be to subscribe to this product. 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 of the customer addresses records, keyd to the address id. In order to help visualize this, we have provided a sample json object in addition to the description of each item object key representation below:

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 in the object above contains the following keys

key sample value description type
customer 'customer123' This field represents your customer's id. This id is used to map the customer between Ordergroove and your ecommerce system. string
public_id 'address123abc' The id of this address record. string
label 'home' A custom label for the address if one exists. string
first_name 'Harry' The first name of person for whom the shipment is meant for. string
last_name 'Potter' The last name of person for whom the shipment is meant for. string
company_name 'Hogwarts' The name of the company tied to the address. string
address 'Platform 9¾' The first line of the address which typically includes a street names and house number. string
address2 'Kings Cross Station' The second line of the address which is typically used to specify additional address details such as apartment number. 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 an address is currently actively tied to an upcoming order or subscription. boolean
created '2021-04-04 16:40:00' The time stamp of 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 that is tied to this address. string

payment_by_id

This object represents the mapping of all of the customer payment records, keyd to the payment id. In order to help visualize this, we have provided a sample json object in addition to the description of each item object key representation below:

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 in the object above 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 billing record. string
cc_number_ending '1111' The last four digits of the credit card number. string
public_id 'payment123abc' The id of the payment record. string
label null A custom label for the address if one exists. string
token_id 'token123' The payment token id that is stored in the ecommerce system. string
cc_holder 'Harry Potter' The name of the account holder. string
cc_type 1 The credit cart issuer that this payment record is associated with. You can find the full list below:

1- Visa
2- Mastercard
3- American Express
4- Discover
5- Diners
6- JCB
integer
cc_exp_date '12/2023' The month and year of that the credit card expires. string
payment_method 1 The payment method tied to this payment record. You can find the fully list below:

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 time stamp of when the payment record was created. string
last_updated '2021-05-10 14:29:38' The time stamp of when the payment record was last updated. string