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'>
| Key | Sample Value | Type |
|---|---|---|
| locale | 'en' | String |
customer
This object represents the current customer who is logged into your site that is viewing the Subscription Manager.
| Key | Sample Value | Description | Type |
|---|---|---|---|
| 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 |
| 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 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.
| 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 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 |
Updated 2 months ago