UltraCart Objects available to Auto Responder Scripts

AutoResponder Object Reference

The Autoresponder campaigns use the same velocity engine as the UltraCart Catalogs.
Please see the online context and object documentation at
UltraCart Velocity Documentation

Logic Steps

Logic steps run velocity code. The following is a list of top level objects made available to a logic step during execution:

Variable

Description

$result

This is what you set to determine the next step. Once you're finished with your logic, at some point, you should be doing something like this: #set($result = 'NameOfNextStep')

$logger

Useful for logging during logic steps to find out why your code isn't working. Try $logger.log($customer) as an example. Log often. It's very helpful. The output will show during a text execution on a separate tab in your editor window.

$customer

The most important object. See the docs below on the $customer object and how you can use it to make a logical decision (i.e. find order history, etc.)

$coupon

Used to generate coupon codes to embed in emails. Although available to the logic step, its doubtful you'll ever use it here.

$giftCertificateManager

Used to generate gift certificates in emails. Although available to the logic step, its doubtful you'll ever use it here.

$dateManager

A utility to format and handle dates

$group

This is a catalog object, and technically out of place here since a logic step has no item groups. However the group object has many utility functions for retrieving item information. So it's included in the logic toolset. See the catalog docs above for the group object.

Email Templates

Email templates also run velocity code. The following is a list of top level objects made available to an email template during execution:

Variable

Description

$logger

Useful for logging during template creation to find out why your email isn't showing what you want. Try $logger.log($customer) as an example. Log often. It's very helpful. The output will show during a text execution on a separate tab in your editor window.

$customer

The most important object. See the docs below on the $customer object and how you can use it to personalize an email. (i.e. find order history, etc.)

$coupon

Used to generate coupon codes to embed in emails

$giftCertificateManager

Used to generate gift certificates in emails

$dateManager

A utility to format and handle dates

$group

This is a catalog object, and technically out of place here since a logic step has no item groups. However the group object has many utility functions for retrieving item information. So it's included in the logic toolset. See the catalog docs above for the group object.

Secondary Objects

The $group object provides access to many secondary objects. See the group docs for details about those objects.

Object

Description

CampaignHistory

Provides a list of steps the recipient has traveled. This might be useful to determine the path the recipient has taken.

Order

Contains order details. This object is returned from several $customer methods. More information about the Order object can be in the online docs embedded in the merchant portal.

Object Reference

$result

Discussion: $result is used by logic steps to determine which branch to take. The object begins as an empty string and is #set by you during a logic step.

$logger

Discussion: $logger is a helpful tool for creating emails and logic steps.
Methods:

Method Name

Signature

Returns

Example

log

$logger.log()

<nothing>

$logger.log($customer.getEmail())

$cart

Discussion:

The $cart object is ONLY available to campaigns enrolled via the return email hook.

Also, it is ONLY available within Email templates. Do not use the $cart object anywhere else (i.e. the Logic step).

Always check to make sure $cart is not null when you use it. It is most useful within an email template to embed a link. But it is also present in the logic steps in case you wish to direct your actions based on whether you have the return link or not. You configure how long an order remains before it is considered abandoned (Home  Configuration  Abandon Interval). The $cart object will be valid up until that time. After that time, it will be null.
Methods:

Method Name

Signature

Returns

Example

getReturnLink

#set($myReturnLink = $cart.getReturnLink())

a bitly url useful for directing a customer back to their checkout.

#if("$!{cart}" != "")

## The above line is preferred to just #if($cart)
Please complete your order! Here's a 20% off coupon that is good for the next 48 hours!
#set($cCode = $coupon.generateCode('MY_20_OFF', '48'))
$cart.addUniqueCouponCode($cCode)
#set($returnLink = $cart.getReturnLink())
<a href="${returnLink}">Your Order</a>
#end

## no indentations above if this is inside the text email, or indentations will show in final output!

getReturnLink

getReturnLink(String returnUrl, String tokenParameter)

#set($myReturnLink = $cart.getReturnLink("www.myjavascriptcheckout.com/checkout.html", "returnCode")

a bitly url useful for directing a customer back to their custom checkout.#if("$!{cart}" != "") ## <-- better way to check for nulls instead of #if($cart)
Please complete your order! Here's a 20% off coupon that is good for the next 48 hours!
 #set($cCode = $coupon.generateCode('MY_20_OFF', '48'))
 $cart.addUniqueCouponCode($cCode)
 #set($returnLink = $cart.getReturnLink("www.myjavascriptcheckout.com/checkout.html", "returnCode"))
<a href="${returnLink}">Your Order</a>
 #end

addUniqueCouponCode

$cart.addUniqueCouponCode($code)

true if successful, else false. If false, $cart.getErrors() will contain a list of errors.

see getReturnLink for example

setReturnUrl
alternative way to use custom return linkif you setReturnUrl and setTokenParameterName, then the getReturnLink() with empty parameters will also return a custom link. This is mainly going to be used with External Integrations such as Lyris. If you're not using Lyris, then getReturnLink(returnUrl, tokenName) is simpler and preferred.
setTokenParameterName
alternative way to use custom return link

The above example uses the return link, and tacks on a coupon to the url, which will automatically apply it to the customer's cart.

$customer

Discussion: The $customer object holds basic information about a customer and has the ability to retrieve order history
Methods:

Method Name

Signature

Returns

Example

getCampaignHistory

$customer.getCampaignHistory()

a list of the recipient's history in this campaign

#set($history = $customer.getCampaignHistory())

getCountOfPurchasesInLastDays

$customer.getCountOfPurchasesInLastDays(days),
$customer.getCountOfPurchasesInLastDays(itemId, days)

a count of purchases made

#set($numberOfPurchases = $customer.getCountOfPurchasesInLastDays('BLACK_SHIRT', 30))

getCountOfShipmentsInLastDays

$customer.getCountOfShipmentsInLastDays(days),
$customer.getCountOfShipmentsInLastDays(itemId, days)

a count of shipments made

#set($numberOfShipments = $customer.getCountOfShipmentsInLastDays('BLACK_SHIRT', 30))

getDisplayName

$customer.getDisplayName()

the name of the recipient, or if that wasn't collected, their email address

Welcome $customer.getDisplayName(), here's a coupon...

getDisplayFirstName$customer.getDisplayFirstName()the first name of the recipient, or if that wasn't collect an empty stringWelcome $customer.getDisplayFirstName(), here's a coupon...
getDisplayLastName$customer.getDisplayLastName()the last name of the recipient, or if that wasn't collect an empty string

getEmail

$customer.getEmail()

them email address of the recipient

This email was address to: $customer.getEmail()... blah blah blah

getEnrollmentDts#set($timestamp = $customer.getEnrollmentDts())this returns back a Java Timestamp object.
getEnrollmentOrder #set($enrollmentOrder = $customer.getEnrollmentOrder()returns the order that triggered enrollment. If enrollment was not based on a purchase, this will be a null value. 
getEnrollmentOrderId#set($orderId = $customer.getEnrollmentOrderId())

getEnrollmentSource#set($source = $customer.getEnrollmentSource())

returns a string showing what the enrollment source is. Possible values:

Abandon Cart
Auto Order - Decline
Goto Step
Mail List
Manual
Purchased Product
Return Email


getLastOrder

$customer.getLastOrder()

Retrieves the last order the customer made. You may wish to check if they've ordered anything first (hasPurchasedEver, etc)

#set($lastOrder = $customer.getLastOrder())

getOrderId #set($orderId = $customer.getOrderId())returns the order id that triggered enrollment.  If enrollment was not based on a purchase, this will be a null value.

getOrders

$customergetOrders()

Retrieves a list of orders for the customer.

#if($customer.getOrders().size() > 5)
Wow, you're a great customer!
#end

getRecurringInformation

#set($recurringInfo = $customer.getRecurringInfomation())

returns the customer's meta information related to the recurring order (also known as 'auto order' or trial order). Always call isRecurring first to ensure you're dealing with a trial order. If there is no recurring information, this method returns null. Be sure to check for a null value before using the object. This method returns a RecurringInformation object.

#if($customer.isRecurring())
#set($recurringInfo = $customer.getRecurringInfomation())
#end

getTotalForAllOrders

$customer.getTotalForAllOrders()

Total dollars the customer has ever spent. Useful to check for spending thresholds

This returns a BigDecimal object.

Note! the total is a BigDecimal object. use longValue() to get a primative number.

#if($customer.getTotalForAllOrders().longValue() > 1000)
You've spent over $1000! Here's a coupon!
#end

getTotalForAllPurchasesInLastDays

$customer.getTotalForAllPurchasesInLastDays(days)

Same as above, but filters on purchases within the last XX days.

This returns a BigDecimal object.

#if($customer.getTotalForAllPurchasesInLastDays(60) > 1000)
You've spent over $1000 in the last 2 months! Here's a coupon!
#end

getTotalForAllShipmentsInLastDays

$customer.getTotalForAllShipmentsInLastDays(days)

Same as above, but filters on shipments within the last XX days.

This returns a BigDecimal object.

#if($customer.getTotalForAllShipmentsInLastDays(60) > 1000)
We've shipped you over $1000 in the last 60 days! Here's a coupon!
#end

hasPricingTier$customer.hasPricingTier("Wholesale")returns true if the customer has an established customer profile in the UltraCart system and has the specified pricing tier.

## do not send a coupon to any customers who are wholesale dealers of ours

## if they are members of the Wholesale pricing tier, exit them from the campaign.

#if($customer.hasPricingTier("Wholesale"))

#set($result = '_ENDCAMPAIGN_')

#end

hasPurchasedEver

$customer.hasPurchasedEver(itemId)

return true if the customer has ever purchased the item.

#if($customer.hasEverPurchased('BLACK_SHIRT'))
Congratulations, you are eligible for the Green Shirt!
#end

hasPurchasedEver

$customer.hasPurchasedEver([itemId1, itemId2, itemId3])

Same as above, but with a list.

#if($customer.hasEverPurchased(['BLACK_SHIRT','BLUE_SHIRT','GREEN_SHIRT']))
Wow, you've bought at least one of our really great shirts!
#end

hasPurchasedInLastDays

$customer.hasPurchasedInLastDays(itemId, days)

Same as above, but with a days argument.

#if($customer.hasPurchasedInLastDays('BLACK_SHIRT', 90))
Congratulations, you are bought a black shirt within the last 3 months (90 days). Go for the Green Shirt with this coupon!
#end

hasPurchasedInLastDays

hasPurchasedInLastDays[itemId1, itemId2, itemId3], days)

Same as above, but with a days argument.

#if($customer.hasPurchasedInLastDays(['BLACK_SHIRT','BLUE_SHIRT','GREEN_SHIRT'], 90))
Congratulations, you are bought at least one of three shirts within the last 3 months (90 days). Here's a special coupon!
#end

hasReviewedItem

hasReviewedItem(itemId1)

returns true if the customer has already completed a review for the specified item.

#if($customer.hasReviewedItem('BLACK_SHIRT')

exit the 'please review this item campaign.

#else

send the customer to an step sending them a reminder email

#end

hasShipmentInLastDays

$customer.hasShipmentInLastDays(days)

see similar 'purchased' method. Some merchants prefer shipment dates over purchase dates.

#if($customer.hasShipmentInLastDays('BLACK_SHIRT', 90))
Congratulations, you are bought a black shirt within the last 3 months (90 days). Go for the Green Shirt with this coupon!
#end

hasShipmentInLastDays

$customer.hasShipmentInLastDays(itemId, days)

see similar 'purchased' method. Some merchants prefer shipment dates over purchase dates.

#if($customer.hasShipmentInLastDays(90))
Congratulations, you made a purchase within the last 3 months (90 days). Thanks!
#end

hasShipmentInLastDays

$customer.hasShipmentInLastDays([itemId1, itemId2, itemId3], days)

see similar 'purchased' method. Some merchants prefer shipment dates over purchase dates.

#if($customer.hasShipmentInLastDays(['BLACK_SHIRT','BLUE_SHIRT','GREEN_SHIRT'], 90))
Congratulations, you are bought at least one of three shirts within the last 3 months (90 days). Here's a special coupon!
#end

isRecurring

$customer.isRecurring()

returns true if the customer's underlying order was a recurring order (also known as 'auto order' or trial order). If this is true, then you may call getRecurringInformation for additional information

#if($customer.isRecurring())
#set($recurringInfo = $customer.getRecurringInfomation())
#end

lastOrderContains

$customer.lastOrderContains(itemId)

checks to see if the last order contained a specific item.

#if($customer.lastOrderContains('BLACK_SHIRT'))
Thanks for buying our best selling item!
#end

lastOrderContains

$customer.lastOrderContains([itemId1, itemId2, itemId3])

checks to see if the last order contains one of the items in the list

#if($customer.lastOrderContains(['BLACK_SHIRT','BLUE_SHIRT','GREEN_SHIRT']))
Congratulations, you are bought at least one of three shirts in your last order. Here's a special coupon!
#end

$coupon

Discussion: The $coupon object is only useful for email templates. It does one thing, and one thing only. It generates a unique coupon code for an email. To use, you must first set up a coupon code using the merchant portal. Login to UltraCart an navigate to Home  Marketing  Coupons to create a coupon that you may use.

Method Name

Signature

Returns

Example

generateCode

$coupon.generateCode('COUPONID', 'hoursToLive')

generates a unique coupon code based on the coupon id/code

#if($customer.getTotalForAllOrders() > 1000)
You've spent over $1000! Here's a 20% off coupon that is good for the next 48 hours!
Coupon Code: $coupon.generateCode('MY_20_OFF', '48')
#end

hoursToLive is a STRING. It has to be a valid number, but it's passed in as a string. Be sure to surround it with double or single quotes. If you don't, it will not work.

$externalAutoresponderFactory

Discussion: The $externalAutoresponderFactory allows the merchant to load a specific external autoresponder to use within their logic step. This allows the merchant to use the tremendous flexibility of the autoresponder rules engine, but cause emails to send through an external auto response.

At this time only LyrisHQ is supported.

Methods:

Method Name

Signature

Returns

Example

getExternalAutoresponder

#set($ear = $externalAutoresponderFactory.getExternalAutoresponder($name))

An implementation of that particular external autoresponder.

#set($ear = $externalAutoresponderFactory.getExternalAutoresponder("LyrisHQ"))

The above example obtains the LyrisHQ external autoresponder object.

$externalAutoresponder

Discussion: The $externalAutoresponder performs the communication with the external autoresponder system such as LyrisHQ.

Methods:

Method Name

Signature

Returns

Example

subscribeReturnEmail

#set($result = $externalAutoresponder.subscribeReturnEmail($cart, $listName, $couponCode))

true/false if subscription successful

#set($result = $externalAutoresponderFactory.getExternalAutoresponder("LyrisHQ").subscribeReturnEmail($cart, "MyList1", "MyCouponCode1"))

$giftCertificateManager

Discussion: The giftCerticateManager provides the means to create gift certificates, add/subtract balances from them, and print out the code and balance of them.
Most methods return a GiftCerticate, which is a simple object with two methods: getRemainingBalance() and getCode(). You'll see the GiftCertificate object used in the examples below.

Note: All gift certificates created are tied to the campaign recipients email address.

Method Name

Signature

Returns

Example

generate

generate(amount)

creates a gift certificate for a certain amount

Dear $customer.getDisplayName(),
Here is a gift certificate for you to thank you for your business.
#set($giftCertificate = $giftCertificateManager.generate(25.00))
Please use the following code on your next purchase: $giftCertificate.getCode()
Amount of gift certificate: $giftCertificate.getRemainingBalance()
Thanks!

generate

generate(amount, addToExisting)

same as above, but will see if the recipient already has an existing gift certificate and add to that amount, else a new certificate is created.

generate

generate(amount, addToExisting, expirationDays)

same as above, but will see if the recipient already has an existing gift certificate and add to that amount, else a new certificate is created. The certificate will expire in the given days provided.

generate

generate(amount, expirationDays)

creates a gift certificate for a certain amount that expires in a certain amount of days

CampaignHistory

Discussion: You may get a list of history objects from $customer.getCampaignHistory. From this, you may loop through the list and see what the customer has done.
There are no methods to this object, only properties.

Property

Discussion

stepName

The name of the campaign step.

stepResult

the result of the step. will almost always be 'success', else the campaign would've ended and you wouldn't be running logic against the recipient.

timeStamp

when the step happened

RecurringInformation

Discussion: You may get an object contains recurring, or auto order information by calling $customer.getRecurringInformation(). Listed below are the properties of that object.

Property

Data Type

May be Null (Empty)?

Discussion

orderId

String

NO

The Order ID

enabled

boolean

Not Possible

if false, this recurring order is dead/ended

autoOrderCode

String

NO

The unique code associated with this recurring order

creditCardAttempt

int

Not Possible

The number of attempts to charge a card. If non-zero, then billing has failed at least one time (see failure reason for why)

nextAttempt

java.sql.Timestamp

YES

The date when the next charge attempt will happen

items

Collection of RecurringItems

NO

A collection of recurring items. See RecurringItem for details.

cancelledByUser

String

YES

If cancelled, this field will contain the person who handled the cancellation.

cancelledDts

java.sql.Timestamp

YES

If cancelled, this will be the datetime when of cancellation.

cancelAfterNextXOrders

Integer

YES

If not null, this is the number of orders before cancellation.

failureReason

String

YES

If not null, provides insight into why a recurring order failed. Do not program logic based on this field. UltraCart reserves the right to change this field's contents at whim.

disabledDts

java.sql.Timestamp

YES

If disabled, this is the datetime when the order was disabled/ended.

RecurringItem

Discussion: You may get an object contains recurring, or auto order information by calling $customer.getRecurringInformation(). Listed below are the properties of that object.

Property

Data Type

May be Null (Empty)?

Discussion

nextShipment

java.sql.Timestamp

YES

datetime of the next shipment

frequency

String

NO

a string showing the order frequency. do not code logic against these values. they may change.

remainingRepeatCount

Integer

YES

the number of orders left

lifeTimeValue

BigDecimal

YES

The sales amount so far.

numberOfRebills

int

NO

The number of rebills done for this item.

rebillValue

BigDecimal

YES

The amount of rebills done for this item.

lastOrderDts

java.sql.Timestamp

YES

datetime of the last order

noOrderAfter

java.sql.Timestamp

YES

datetime of when no more orders will happen

arbitraryUnitCost

BigDecimal

YES

If merchant has done an override, this is the new unit cost.

arbitraryItemId

String

YES

If merchant has done an override, this is the new item id.

arbitraryQuantity

BigDecimal

YES

If merchant has done an override, this is the new quantity.

arbitraryUnitCostRemainingOrders

Integer

YES

If merchant has done an override, this is the new remaining orders.

originalItemId

String

YES

If merchant has done an override, this is the original item id.

originalQuantity

BigDecimal

YES

If merchant has done an override, this is the original quantity.

arbitraryScheduleDays

Integer

YES

If merchant has done an override, this is the new schedule.

arbitraryPercentageDiscount

BigDecimal

YES

If merchant has done an override, this is the new discount.