Commerce email notifications

Posted 25 Sep 2008 12:00 AM by SeanWinstead

When your users place orders through your community, you typically want the user to receive a receipt. If you're shipping physical product, you may also want to notify the customer once their order has been packaged and dispatched via a carrier. Out of the box, Four Roads Commerce provides support for those scenarios and others. This blog post describes the available email features and how you may configure them.

If you require something slightly different than what is available, you can implement it using the Commerce events system.

Compatibility

The technical details in this blog post are geared toward Four Roads Commerce for Community Server 2008.

Email Templates

Commerce follows the same email pattern as Community Server. All email templates are stored in an XML file named ShopEmails.xml. After you install Commerce, you can find that file in directory Web\Languages\en-US\emails.

Emails can be enabled and disabled. We'll go over that in the following sections.

Payment Emails

When a user pays for an order, you can elect to send them an email if the payment is successful or an email if the payment has failed. Additionally, you can send an email to internal stakeholders when a successful payment occurs.

To enable or disable payment-related emails, look for the OrderEmailNotification module in communityserver_override.config. It is located within the ShopModules element. Following is an example:

The OrderEmailNotificationModule provides you with a number of attributes controlling email functionality. To enable payment notifications, set processPaymentActions="true". To disable those emails, set processPaymentActions="false". You can also override this setting via the Control Panel using the following steps:

Log in as a shop administrator or system administrator.
Go to the Control Panel.
Click on the My Shops link.
In the left hand navigation, go to Global Settings -> Shop Options. This opens the Shop Options page.
Click on the General Settings tab.
Set the Enable Receipt Emails option to either Yes or No.

Send Emails to Internal Users

If you want one or more of your employees to receive an email when a purchase has occurred, Commerce gives you three ways to send an email. In each case, the email is sent only if processPaymentActions="true" and the AdminOrderPaymentReceived email template is used.

First, you can specify one or more owners for your shop (i.e., online store). In the same way that a blog has owners, a shop can also have owners because a shop is really a special kind of section. To set one or more owners on a shop, do the following:

Log in as a shop administrator or system administrator.
Go to the Control Panel.
Click on the Administration link.
In the left hand navigation, go to Shops -> Shops. You'll see a list of the online stores you've created. Click the Edit button of the one for which you want to specify owners.

Second, if no owners are specified then the email is sent to the administrator's email address specified in the site settings.

Third, if you don't want emails to go to the shop owner(s) and you don't want emails going to the admin email address then enter one or more email addresses into the Override Email Notification setting for the shop in question. To set a value for that field, do the following:

Log in as a shop administrator or system administrator.
Go to the Control Panel.
Click on the My Shops link.
In the left hand navigation, go to Global Settings -> Shop Options. This opens the Shop Options page.
Click on the General Settings tab.
Enter one or more email addresses into the Override Email Notification field. Separate multiple addresses with semi-colons.

Following is a screenshot of the tab containing the field:

Override Email Notifications field

Payment Email Templates

Following are the templates in ShopEmails.xml for payment-related templates:

AdminOrderPaymentReceived - Sent to internal users based upon the rules listed in the previous section.
OrderPaymentReceived - Sent when payment has been received for an order.
OrderPaymentFailed - Sent when the user tried to pay for an order but the payment was unsuccessful.

Order Emails

You may also send emails to customers when their order has been created, it has changed in some way, or it has been shipped to them. Order email settings are also controlled via the OrderEmailNotification module in the communityserver_override.config file. Following is an example:

If processCreated="true" then an email is sent to the user when their order is first created. The template for this email is named OrderCreated. This value defaults to false.

If processUpdate="true" then Commerce uses the OrderUpdated template to send an email to the user when the status of the order changes. This value defaults to false.

If processComplete="true" then the OrderComplete email template is instantiated and sent to the user when the order status is set to Complete. An order is set to Complete when the payment is successful and the items on the order have been dispatched. For a physical shipment, the shop staff must shop the products and manually mark the line items as dispatched. For subscriptions the orders are auto-completed. This value defaults to true.

Note that ShopEmails.xml does contain two other order-related templates: OrderItemDispatched and OrderUserNote. The OrderItemDispatched template is not currently used. The OrderUserNote template is used to send an email to your customer when a note has been added to an order. Notes are added to an order under the following conditions:

The payment was declined and the user is retrying the order.
A shop staff member enters a note for the order.

Subscription Emails

Commerce also sends email for subscription-related activity (e.g., subscription expired). Subscription emails are sent automatically. At this time, there is now way for you to disable them. The following sections explain the conditions that lead Commerce to send a subscription email.

Subscription Expired

If a subscription is not renewable or it is configured for manual renewals only and the user did not manually renew, Commerce uses the SubscriptionExpired email template to send the member an email.

Automatic Renewal Warning

If a subscription is about to expire and it is configured for automatic renewal, an email is generated and sent using the SubscriptionAutomaticRenewal template. The email notifies the member of the forthcoming renewal.

Manual Renewal Required

If a subscription is about to expire and it is configured for manual renewal, a warning email is sent to the customer. Commerce uses the SubscriptionManualRenewal template to create the email. The email contains a link to a page where the member can renew their subscription.

Renewal Failed

If a subscription is about to expire and it is configured for automatic renewal, Commerce will attempt to renew the subscription via the payment gateway. If the renewal fails (e.g., the credit card number stored by payment gateway is no longer valid) then Commerce sends an email to the customer notifying them of the problem. The SubscriptionRenewalFailed email template is used for this case.

Summary

In this post, you learned there are several types of emails: payment, order, and subscription. You can choose whether to send payment-related emails to your customers and internal system users. You can enable and disable order-related emails on an individual basis. But when it comes to subscription emails, Commerce handles those automatically. In call cases, you can customize the email template for each kind of email sent by Commerce.

If you have any questions about this topic, feel free to post them in the comments here or in the Commerce discussion forum.

Filed under: Commerce, Commerce 2008, CS2008, payment, email template, order, email, subscription

Rate:

Commerce

Home

Commerce email notifications

Commerce

Syndication

Recent Posts

Tags

Archives