These are the types of objects that can be referenced from your theme pages.
Customer
The Customer object represents customer data such as name, email, primary and shipping addresses, and authentication credentials. This object is primarily used in the html/customer/account.html and html/customer/edit.html pages.
customer.created_at The datetime that this Customer object was created
customer.custom_data Any metadata attached to this customer
customer.email The email address associated with this Customer
customer.first_name The first name associated with this Customer
customer.last_name The last name associated with this Customer
customer.name The full name associated with this Customer
customer.logs
A list of customer log entries.
customer.calc_primary_address() Returns the primary Address object associated with this Customer
customer.calc_ship_address() Returns the shipping Address object associated with this Customer
Sub
Represents the Subscription object. This will carry data such as the renewal date (end_date), start date, and current status. If a subscription is switched to a different product, or a coupon added after checkout, this creates a new subscription_template object, so as to preserve the historical data.
sub.custom_data
Any metadata attached to this subscription
sub.status
The status of the subscription. (1=Unpaid, 2=Active, 3=Cancelled, 4=Suspended, 5=Expired, 6=Past Due, 7=Pending Renewal, 8=Renewing, 8=Unpaid Order Failed)
sub.start_date
The start date of the subscription
sub.end_date
The end (or renewal) date of the subscription
sub.orders
A list of orders for the subscription.
sub.logs
A list of subscription log entries.
sub.current_template
The current subscription template. (See below)
Subscription Template
Represents the Subscription Template object, a snapshot of a subscription's state. This will carry relations that may change, such as the associated shipping address, product(s), and coupons on a subscription. When these aspects of a subscription are modified, a new subscription template is created, so the historical data is preserved.
tpl.products
A list of subscription product objects for the subscription.
tpl.coupons
A list of subscription coupon objects on the subscription. This will not include coupons added during checkout, which are cart coupons rather than subscription coupons.
tpl.note
A note on what caused the creation of a new template. For example: "Subscription initialization", "Subscription product changed by Jane Doe", "Coupon FREEBOX added to subscription renewal #123456789 by John Smith"
tpl.created_at
When the template was created.
Subscription Product
The subscription_product is largely a mapping between subscription_template and product_instance objects, with a couple additional attributes.
subscription_product.product_instance
The product instance for this subscription product.
subscription_product.subscription_type_term
The subscription type term for this subscription product.
subscription_product.price
The price in cents.
subscription_product.quantity
The quantity. (This should always be 1 in practice.)
subscription_product.ship_weight
The weight. If you've edited your product weight since the subscription was created, this could be different from the current product weight.
Subscription Coupon
Represents the Subscription Coupon object, a mapping object between subscription_template and coupon objects. Note that this will only include recurring coupons or coupons added after checkout. Single-use coupons used on checkout only have a cart_coupon object, which is never copied over into a subscription_coupon.
subscription_coupon.coupon
The coupon object.
subscription_coupon.code_used
The specific coupon code used.
subscription_coupon.enabled
Whether the subscription coupon is enabled, and thus may apply on renewal.
num_renewals
The number of renewals it's applied to so far.
Coupon
Represents the Coupon object. These are referenced Cart Coupons and Subscription Coupons, and have sub-objects for codes, limitations, recurring settings, discount settings, and product/term filters.
coupon.id
coupon.name
coupon.description
An internal description not typically shown to customers.
coupon.created_at
coupon.num_redeemed
coupon.total_redeemed
The num redeemed across all the coupon's codes.
coupon.active
When false, the coupon cannot be added and will not apply even on subscriptions that already have it. (Contrast with expiration on Coupon Limitations.)
coupon.gift
Is a special Gifting 1.0 coupon used only for gift redemptions.
coupon.reward
Is a special coupon used only for apps.
coupon.all_sub_prod_enabled
All sub products are enabled, and the coupon is set to automatically apply to any new sub products as well if they're added to the store.
coupon.all_ecom_prod_enabled
All ecom products are enabled, and the coupon is set to automatically apply to any new ecom products as well if they're added to the store.
coupon.codes
A list of CouponCode objects. One of these will have primary=True.
coupon.primary_code
The CouponCode with primary=True.
coupon.exclusive
A shortcut to coupon.limits.exclusive. When true, you cannot use this coupon on the same order or subscription as another coupon.
coupon.once_per_customer
A shortcut to coupon.limits.once per customer. When true, a logged in user can't add this to their cart if they've used it on another order.
coupon.free_shipping
A shortcut to coupon.discount.free shipping. Whether the coupon provides free shipping.
Pay
The Pay object represents a Customer’s payment processing data.
customer_pay.exp_month
The expiration month of the card for this Pay object
customer_pay.exp_year
The expiration year of the card for this Pay object
customer_pay.last_four
The last four digits of the card for this Pay object
Address
The Address object represents a Customer’s primary and/or shipping address.
address.to
The Customer’s recipient line for this Address
address.company
The Customer’s company name for this Address
address.street
The street address of the Customer’s Address
address.unit
The secondary address unit designator of the Customer’s Address
address.city
The city field of the Customer’s Address
address.state
The state field of the Customer’s Address
address.zip_code
The zip code field of the Customer’s Address
address.country
The country name of the Customer’s Address
Store
The Store object represents your store. It contains all products, themes, and customers related to your store.
store.name
The human readable store name
store.has_gifting
Boolean, indicates at least 1 product can be bought with coupons
{% if store.has_gifting %}
<a href="/subscribe/gift/" class="btn">Give a Gift</a>
{% endif %}
PAGINATION QUERIES
store.category_products(category)
Return a query products that can be passed to paginate. Filters with taxonomy = category
{% paginate store.category_products(category='helmets') by 4, page %}
{% for product in paged_items %}
{{ my_product_macro(4, product) }}
{% endfor %}
{% endpaginate %}
store.shop_products(category=None, include_hidden=False)
Return query for e-commerce products that can be passed to paginate. You can filter by category = taxonomy, and include hidden products.
{% paginate store.shop_products(category='birds', include_hidden=True) by 4, page %}
{% for product in paged_items %}
{{ my_product_macro(4, product) }}
{% endfor %}
{% endpaginate %}
ITERABLE PRODUCT LISTS
The following store properties can all be iterated over in the same way, the key difference is what combination of ecommerce/subscription and visible/hidden filters you want to apply.
<!-- To iterate over subscription_products -->
{% for product in store.subscription_products %}
{{ my_product_macro(product) }}
{% endfor %}
store.products
A list of all Product objects attached to this store
store.ecom_products
A list of only e-commerce Product objects attached to this store
store.hidden_ecom_products
A list of only hidden e-commerce Product objects attached to this store
store.visible_ecom_products
A list of only visible e-commerce Product objects attached to this store
store.subscription_products
A list of only subscription Product objects attached to this store that are enabled for display.
store.subscription_only_products
A list of only subscription Product objects attached to this store including both enabled and disabled products.
store.visible_subscription_products
A list of only visible subscription Product objects attached to this store
store.hidden_subscription_products
A list of only hidden subscription Product objects attached to this store
store.visible_products
A list of visible Product objects attached to this store
store.hidden_products
A list of hidden Product objects attached to this store
Product
The Product object is the main representation of a product. It may have multiple variants, image data, subscription term
PROPERTIES
product.name
The human readable product name
product.description
The human readable product description
product.images
A list of images available for this product
product.instances
A list of non-gift ProductInstance objects attached to this product
product.giftinstances
A list of gift ProductInstance objects attached to this product
product.taxonomy
A list of tags on an ecommerce product
product.surveys
A list of surveys on a subscription product
product.product.has_inventory_for_purchase
Whether an ecom product has available inventory or allows out-of-stock purchases.
METHODS
product.get_term_price(term_name=None)
Returns a TermPrice object, which links a price to a product Instance and a subscription Term. The TermPrice can be found by term_rank (0-numTermsEnabled).
<span>{{ product.get_term_price(term_rank=0).price | currency }}</span>
product.get_variant_type_by_name(name)
Returns a VariantType object by name, useful for looping over all variant values by name.
{% set style_variant = product.get_variant_type_by_name('style') %}
{% for value in style_variant.values %}
<!-- display values -->
{% endfor %}
MINIMUM-MAXIMUM PRICE RANGES
Note: For convenience, you can and should use the get_price_or_price_range filter to avoid calculating ranges in your templates.
product.calc_min_price(*variant_types, **kwargs)
Returns the minimum possible subscription price for the given variant types and choices.
{% set min = product.calc_min_price(variant, values=chosen_values + [value]) %}
product.calc_max_price(*variant_types, **kwargs)
Returns the maximum possible subscription price for the given variant types and choices. Useful for displaying price ranges for different variants.
{% set max = product.calc_max_price(variant, values=chosen_values + [value]) %}
product.calc_min_ecom_price(*variant_types, **kwargs)
Returns the minimum possible ecommerce price for the given variant types and choices. Useful for displaying price ranges for different variants.
{% set min = product.calc_min_ecom_price(variant, values=chosen_values + [value]) %}
product.calc_max_ecom_price(*variant_types, **kwargs)
Returns the maximum possible subscription price for the given variant types and choices. Useful for displaying price ranges for different variants.
{% set max = product.calc_max_ecom_price(variant, values=chosen_values + [value]) %}
Variant Type
The VariantType object represents a definable type of product option. Some examples would be a product’s Size, Color, or Style.
variant_type.name
The defined name of the variant type
variant_type.description
The defined description of the variant type
variant_type.values
A list of available VariantValue objects associated with this VariantType
Variant Value
The VariantValue object represents a definable option for a VariantType. A VariantType of ‘Size’ may have VariantValue objects such as ‘Small’, ‘Medium’, and ‘Large’.
variant_value.value
The defined value
variant_value.is_default
Boolean, whether this VariantValue is the default for its VariantType
variant_value.description
The definable description
variant_value.images
Associated images for this VariantValue
Product Instance
The ProductInstance object represents a single configuration of a Product and its variant & subscription options
instance.term_prices
A list of all TermPrice objects associated with this instance
instance.calc_num_enabled_terms()
Returns the number of subscription terms enabled for this product instance
instance.calc_term_discount(term_price)
Returns the term discount of the passed in TermPrice object. This is the percentage savings of the TermPrice vs the Instance’s single term cycle price, which indicates the savings of buying a multi-cycle term vs a single cycle term.
instance.sku
The SKU associated with this product instance
instance.name
The product name, with variant values for this instance.
{% for term_price in instance.term_prices %}
<span>Discount: {{ instance.calc_term_discount(term_price) | currency }}</span>
{% endfor %}
Subscription Term
The Term object represents a subscription term, which can have 1 or more cycles, depending on your configuration.
term.name
The name of this term
term.enabled
Boolean, whether or not this term is enabled
term.description
The description of this term
term.num_cycles
The number of cycles for this term
Subscription Term Price
The TermPrice object represents the price for the intersection of an Instance and a Term
term_price.price
The defined price for this Instance/Term combination
term_price.term
The Term object associated to this TermPrice
term_price.instance
The Instance object associated to this TermPrice
Order
The order object represents a complete order on the platform and is only created after successful checkout
order.financial_status
Payment for the order. One of: "pending", "authorized", "partial", "paid", "refunded", "voided"
order.fulfillment_status
One of: "unfilled", "partial", "fulfilled". (Note: This field is immediately marked fulfilled for subscription orders. It's generally better to look at a shipment status.)
order.is_renewal
Whether the order was generated automatically from a subscription renewal
order.is_test
Whether the order was created while in Test Mode
order.note
Optional note on the order added via the merchant portal
order.placed_at
The datetime for when this order was placed
order.refund_amount
The total refund for all transactions in the Order
order.status
Order status: "open" or "closed"
order.total
Grand total cost for order
order.total_price
Total before shipping, taxes and fees. Just the cost of product.
order.transaction_fee
Fee applied by third party payment gateway
order.total_shipping
Total price of shipping
order.total_tax
Total taxes collected
order.id
Order id.
order.products
List of product_instance objects, excluding gift cards and gifting 1.0 gifts.
order.gifts
List of product_instance objects, gifting 1.0 gifts only.
order.fulfillments
List of Fulfillment objects.
order.subscriptions
List of Subscription objects.
order.gift_message
Gift message iff order is a gift order.
order.order_gift_info
_The gift info object iff order is a gift order.
Order Gift Info
The order_gift_info object contains gift information for gift purchases. This will only ever be on the first order of a subscription, not the renewal orders.
ogi.gift_recipient_name
The recipient name provided on checkout.
ogi.gift_recipient_email
The recipient email provided on checkout.
ogi.gift_message
The gift message provided on checkout.
Settings
The Settings object represents any theme specific configurable settings that you define, like default theme colors and fonts, Designer configurations, and variables to be made available to Jinja2. Available Settings properties are defined in your theme’s config/settings_data.json file. Settings values can be accessed in templates as properties of the settings object.
<span>Current Main font choice is: {{ settings.face_main }}</span>
Output:
Current Main font choice is: Lucida-Sans
The Settings object is also used in our Designer customizable fonts and colors. You can reference the settings object in your CSS files:
h2 .heading {
font-family: {{ settings.face_main }};
}
Output:
h2 .heading {
font-family: Lucida-Sans;
}
Cart
The Cart object represents a customer's cart, which may contain 0 or more products. You may access it on the checkout page simply by referencing cart, or on any other page by referencing active_cart().
cart.id
The integer id for the cart.
cart.anon_id
The string id for the cart, used in the URL. Null when customer is logged in.
cart.custom_data
Any metadata attached to this cart
cart.customer_id
Customer id, or null if not logged in.
cart.store_id
The store id associated with the cart.
cart.products
List of cart product objects, excluding Gifting 1.0 gifts.
cart.gifts
List of product instance objects. (Gifting 1.0 only.)
cart.all_products
cart.products + cart.gifts.
cart.subscription_products
List of cart products that are for subscription products.
cart.has_subscription
Does the cart contain any subscription products?
cart.has_stuff
Is cart.all_products or cart.coupons non-empty?
cart.ship_price
Shipping price. May be null before calculation on checkout page.
cart.tax_price
Tax price. May be null before calculation on checkout page.
cart.coupons
A list of coupons on the cart. Note: these are cart_coupon objects, not coupon objects. Each cart_coupon "c" will have a coupon referenced by c.coupon
cart.gift_cards
A list of cart gift cards on the cart. Note: these are cart_gift_card objects, not gift_card objects. Each cart.gift_card "c" will have a gift card referenced by c.card