Guides
Start typing to search…

Object Reference

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

❗️

IMPORTANT

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 SMI

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 SMI 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 SMI is currently running.

string

api_url

'https://api.ordergroove.com'

URL of the legacy Ordergroove API cluster that the SMI is using to retrieve data.

string

lego_url

'https://restapi.ordergroove.com'

URL of the Ordergroove REST API cluster that the SMI 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 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 SMI

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

[ ]

This is a list of product ids which make up this line item, if the line item happens to be a bundle product.

array

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 price only in 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.

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 7 days ago