Customer notifications

Gain a better understanding of what notifications to send to customers and what information to include in them

You'll need to send messages (typically emails) to your customers throughout an eCommerce transaction. These notifications provide customers with information on their purchases and inform them of important events. They also help keep your customers engaged throughout the entire process, leading to a more positive shopping experience and potentially increasing brand loyalty.

You must send certain notifications to customers to access to Digital River's MOR/SOR business model.

In many cases, you can configure webhook(s) to listen for events created by Digital River and use the data in these events to populate the emails before they get pushed to customers.

On this page, you'll find information on order notifications and subscription notifications, as well as the events in the Digital River APIs (when available) that can be used to trigger them.

Order notifications

In this section, you'll find basic information on what notifications to send to customers throughout an order's lifecycle:

Order confirmation

This notification informs your customers that their order has been approved and is currently being processed. It provides customers with a record of their purchase and assures them that the transaction is authentic.

In Required Purchase Notifications (refer to Learning tools for access information), you'll find a comprehensive list of what to include in this notification.

Recommended type of triggering event: order.accepted

This same event type can also be used for subscription acquisition notifications.

Use the following table to learn which attributes in the event's data.object contain values that can be used to populate the notification.

Notification informationRelevant attribute

The identifier of the order

id

A description of each product

name, (and optionally description, image, and url) in items[].productDetails

The cost of each product

items[].amount

Assessed taxes

totalTax

Applied discounts

totalDiscount

Shipping costs

totalShipping

Total amount of order

totalAmount

Shipment notification

Send this notification to customers when some or all of an order's goods have shipped. The message must indicate which items are in the shipment and should ideally include delivery tracking information.

In Required Purchase Notifications (refer to Learning tools for access information), you'll find a comprehensive list of what to include in this notification.

Recommended type of triggering event: fulfillment.created

Use the following table to learn which attributes in the event's data.object contain values that can be used to populate the notification.

Notification informationRelevant attribute

The identifier of the order

orderId or orderDetails.id

A description of each shipped product

name, (and optionally description, image, and url) in orderDetails.items[].productDetails

The quantity of each shipped product

items[].quantity

The name of the designated carrier

trackingCompany

The designated carrier's tracking number

trackingNumber

A url that allows customers to access tracking details

trackingUrl

Successful cancellation

This notification informs customers that their order has been partially or fully cancelled. Regardless of the reason for the cancellation or who initiated the request, purchasers need to be notified which items will not be fulfilled.

In Required Purchase Notifications (refer to Learning tools for access information), you'll find a comprehensive list of what to include in this notification.

Recommended type of triggering event: fulfillment.created or order.cancelled

If your application supports partial order cancellations, then we recommend listening for fulfillment.created and using it to trigger this message.

This is because the state of each items[] in an order must be cancelled before Digital River creates an event with a type of order.cancelled.

For example, if an order contains multiple items[], each with a quantity of 2, and a customer uses your site’s UI to request that only one of those line items be fully cancelled, and, after approving that request, your system sends a POST /fulfillments with an items[].cancelQuantity of 2, then Digital River generates fulfillment.created but not order.cancelled.

Use the following tables to learn which attributes in the event's data.object contain values that can be used to populate the notification.

Notification informationRelevant attribute

The identifier of the order

id

A description of each cancelled product

name, (and optionally description, image, and url) in items[].productDetails

The quantity of each cancelled product

items.quantity

Failed cancellation

If customers request to have an order partially or fully cancelled but you can't honor their request for whatever reason, send a notification informing them that their goods are still scheduled for fulfillment.

In Required Purchase Notifications (refer to Learning tools for access information), you'll find a comprehensive list of what to include in this notification.

Unless Digital River coordinates a fulfillment, there are no events in the Digital River APIs that can be used to trigger this failed cancellation message.

Delayed shipment, right to cancel (1st and 2nd notices)

If a shipment is delayed, send a notification to customers that provides a revised date of when the goods are scheduled for delivery. If additional delays occur that cause that date to be pushed out even further, send customers a second notice. In both of these messages, you must give customers the option to cancel their purchase.

In Physical Goods Required Purchase Notifications (refer to Learning tools for access information), you'll find a comprehensive list of what to include in this notification.

Currently, no events in the Digital River APIs can trigger these delayed shipment notifications.

Refund confirmation

This notification confirms that a customer's refund request has been successfully processed.

In Required Purchase Notifications (refer to Learning tools for access information), you'll find a comprehensive list of what to include in this message.

Recommended type of triggering event: order.refunded

Use the following table to learn which attributes in the event's data.object contain values that can be used to populate the notification.

Notification informationRelevant attribute

The order identifier

id

Total amount refunded on order

refundedAmount

The amount of each individual refund on the order (optional)

payment.charges[].refunds[].amount

Product return instructions

This message provides instructions to customers on how to return physical products they've purchased.

In Recommended Purchase Notifications (refer to Learning tools for access information), you'll find a comprehensive list of what to include in this notification.

Unless Digital River coordinates a fulfillment, no events currently exist in the Digital River APIs that can be used to trigger this message.

Subscription notifications

This section provides basic information on what notifications to send customers throughout a subscription's lifecycle and provides guidance on each notification's potential triggering event.

Refer to Subscription Purchase Notifications (see Learning tools for access information) to be provided with a comprehensive list of what's required and what's recommended in these messages.

Triggering events

If you're using Digital River's subscription service, we indicate which type of event can be used to trigger each subscription notification. However, if you engage a third-party subscription service (except for acquisition confirmation notifications), you'll need to listen for relevant triggering events emanating from that service.

Acquisition confirmation

This notification informs customers that they have successfully acquired one or more subscription-based products.

Recommended type of triggering event: order.accepted

Use the following table to learn which attributes in the event's data.object contain values that can be used to populate the notification.

Notification informationRelevant attribute

The identifier of the acquisition order

id

A description of each subscription product

For each items[] with subscriptionInfo, the

name, (and optionally description, image, and url) in productDetails

The cost of each subscription product

For each items[] with subscriptionInfo, the amount

Assessed taxes

totalTax

Applied discounts

totalDiscount

Shipping costs

totalShipping

Total amount of order

totalAmount

Trial conversion notification

This notification informs customers that their promotional trial period has ended, and they will be billed on a recurring basis for the subscription's products in the future.

Recommended type of triggering event: subscription.extended

Use the following table to learn which attributes in the event's data.object contain values that can be used to populate the notification.

Notification informationRelevant attribute

Description of subscription

invoice.description

For details, refer to name in Plans.

The date the free trial was activated

subscription.stateTransitions.activatedFree

The first scheduled billing date

subscription.nextInvoiceDate

A description of each product in the subscription

name, (and optionally description, image, and url) in invoice.items[].productDetails

The cost and quantity of each product in the subscription

amount and quantity in invoice.items[]

The payment method to be charged

invoice.payment.sources[]

Taxes to be assessed

invoice.totalTax

A subtotal of the amount that the customer is to be charged

invoice.subtotal

The total amount that the customer is to be charged

invoice.totalAmount

Renewal reminder

This notification reminds customers that their recurring products are scheduled to renew soon. It should include the subscription's name and a description of its goods, the amount the customer will be charged, and the upcoming billing date.

Recommended type of triggering event: subscription.reminder

Use the following table to learn which attributes in the event's data.object contain values that can be used to populate the notification.

Notification informationRelevant attribute

Description of subscription

invoice.description For details, refer to name in Plans.

Start date of subscription

subscription.stateTransitions.activated

The next scheduled billing date

subscription.nextInvoiceDate

A description of each product in the subscription

name, (and optionally description, image, and url) in invoice.items[].productDetails

The cost and quantity of each product in the subscription

amount and quantity in invoice.items[]

Payment method to be charged

invoice.payment.sources[]

Taxes to be assessed

invoice.totalTax

A subtotal of the amount that the customer is to be charged

invoice.subtotal

The total amount that the customer is to be charged

invoice.totalAmount

Renewal confirmation

This notification informs customers that their subscription has been renewed and their designated payment method was successfully charged.

Recommended type of triggering event: subscription.extended

Use the following table to learn which attributes in the event's data.object contain values that can be used to populate the notification.

Notification informationRelevant attribute

The order identifier

invoice.orderId

Description of subscription

invoice.description For details, refer to name in Plans.

Start date of subscription

subscription.stateTransitions.activated

A description of each product in the subscription

name, (and optionally description, image, and url) in invoice.items[].productDetails

The cost and quantity of each product in the subscription

amount and quantity in invoice.items[]

The payment method that was charged

invoice.payment.sources[]

Assessed taxes

invoice.totalTax

Applied discounts

invoice.totalDiscount

A subtotal of the amount charged

invoice.subtotal

The total amount charged

invoice.totalAmount

Next scheduled billing date

subscription.nextInvoiceDate

Subscription cancelled notification

This notification informs customers that their request to cancel a subscription has been successfully processed. It should ideally contain details on the cancelled products.

Recommended type of triggering event: subscription.updated

Use the following table to learn which attributes in the event's data.object contain values that can be used to populate the notification.

Notification informationRelevant attribute

The effective cancellation date

stateTransitions.cancelled

A description of each cancelled subscription product

items[].skuId To access product details, use this identifier to retrieve the SKU.

Updated terms

This notification informs customers of an update to their subscription's terms and conditions. It should describe the upcoming changes and provide a way for customers to cancel the subscription if they don't agree with them.

Recommended type of triggering event: subscription.updated

Use the following table to learn which attributes in the event's data.object contain values that can be used to populate the notification.

Notification informationRelevant attribute

The updated terms

planId To access the updated terms and conditions, use this identifier to retrieve the plan.

A description of each product in the description

items[].skuId To access product details, use this identifier to retrieve the SKU.

Billing failed notification

This notification informs customers that an unsuccessful attempt was made to charge the payment method funding their subscription. To avoid losing access to their recurring products, the message should contain instructions on how customers can update or replace this payment method.

Recommended type of triggering event: subscription.payment_failed

Use the following table to learn which attributes in the event's data.object contain values that can be used to populate the notification.

Notification informationRelevant attribute

Description of subscription

invoice.description For details, refer to name in Plans.

Payment method that could not be charged

invoice.payment.sources[]

The number of unsuccessful billing attempts that have been made so far

invoice.attemptCount

A description of the products that customers will lose access to unless they take action

name, (and optionally description, image, and url) in invoice.items[].productDetails

Subscription failed notification

This message informs customers that their subscription has been deactivated because payment couldn't be collected during the designated billing period. It's recommended that you include instructions on how customers can reactivate their subscriptions.

Recommended type of triggering event: subscription.failed

Use the following table to learn which attributes in the event's data.object contain values that can be used to populate the notification.

Notification informationRelevant attribute

Description of failed subscription

planId Use this identifier to retrieve the plan and access description information. For details, refer to name in Plans.

Description of products in failed subscription

items[].skuId To access product details, use this identifier to retrieve the SKU.

The date that the subscription failed

stateTransitions.failed

Payment method expiration

Prior to a subscription's renewal, this message informs customers that the designated payment method has either expired or will expire before the scheduled renewal date. The notification should provide customers with a way to either update the subscription's current payment method or replace it with a new one.

In the Digital River APIs, no events currently exist that can be used to trigger this notification.

Last updated