Digital River coordinated fulfillments

Understand Digital River's fulfillment solutions

This section provides an overview of two Digital River coordinated fulfillment models.

Both models allow you to build checkouts with physical and digital products, check inventory levels, process shipping quotes, reserve inventory, use our supported payment methods, combine payment sources, initiate fulfillments, track shipments, cancel fulfillments, capture and cancel payments, and handle reversals.

In both models, you also use SKU-inventory item pairs.

The major differences between the distributed model and the orchestrated model revolve around (1) how you build and maintain your catalog of products whose fulfillment Digital River coordinates and (2) who is responsible for handling order accepted, product shipment, and product cancellation events.

Distributed model

In the distributed model, as with all Digital River coordinated fulfillments, your SKU-inventory item pairs represent products whose fulfillment Digital River coordinates. You create these pairs and are responsible for keeping their data synchronized.

After converting the checkout to an order, you wait for the order to be accepted and then handle this state change event by creating a fulfillment order. You then listen for product shipment and product cancellations events, and handle them by sending payment capture and cancellation requests.

The following provides a high-level overview of how you might structure a distributed model workflow:

Creating and maintaining your product catalog

Prior to deployment, you should build a catalog of physical products whose fulfillment Digital River coordinates. For each product in this catalog, use the SKUs API and Inventory Items API to create SKU-inventory item pairs with shared attributes and then ensure those attribute values remain synchronized.

It's important that you keep these pairs synchronized. In every create checkout request you must reference the SKU when describing line items. Later, after you convert the checkout to an order, and the order is accepted, you need to reference the paired inventory item in a create fulfillment order request.

If the shared attribute values of these SKU-inventory item pairs are not synchronized, you risk encountering problems with customs, generating incorrect duty amounts or having errors displayed on invoices.

When building checkouts using the distributed model, you can add physical SKUs from the catalog of products whose fulfillment Digital River coordinates as well as digital SKUs from other catalogs.

Building checkouts and submitting orders

In both this model and the orchestrated model, you can use the same basic approach to process your checkouts and submit your orders.

Initiating physical product fulfillment

In the distributed model, once you build the checkout and submit the order, and then either synchronously or asynchronously receive an order in an accepted state, you retrieve data from that order and use it to create a fulfillment order. This request instructs Digital River's fulfillment services to initiate fulfillment of the order's physical products.

For more information, refer to handling accepted orders on the Processing orders page.

Responding to product pending and backordered events

If you give customers the option to cancel orders, then the fulfillment_order.pending event contains the fulfillment order identifier and fulfillment order line item identifiers that you need to create a fulfillment order cancellation.

You can also subscribe to the fulfillment_order.backordered event. It notifies you when a product is out of stock. You can handle this event by notifying customers of the delay and providing them the option to cancel the backordered products. If they select this option, submit a POST/fulfillment-cancellations.

For more information, refer to the Cancelling physical fulfillments page.

Responding to product shipment events

In this model, you need to handle fulfillment_order.shipped events. The source of these events are shipment notifications sent by the product's fulfiller.

The event's payload informs you which items, and in what quantity, have been shipped to the customer. These shipped events also contain a unique shipment identifier that allows you to share tracking information with the customer.

Each time you receive a fulfillment_order.shipped event, retrieve its order, product, and shipment data and use it to define and submit a POST/fulfillments request. This request instructs Digital River's payment services to capture the appropriate amount of an order's payment charges.

Responding to product cancellation events

In this model, you also need handle fulfillment_order.cancelled events. The source of these events are either POST/fulfillment-cancellations requests that your system makes or cancellation notifications sent by the product's fulfiller.

The payload of each fulfillment_order.cancelled event informs you which items, and in what quantity, have been cancelled. Each time you receive a cancelled event, retrieve its order and product data, and use it to define and submit a POST/fulfillments request. This request instructs Digital River's payment services to cancel the appropriate amount of an order's payment charges.

Completing an order

Continue listening for and responding to fulfillment related events. After receiving each event, update the status of the order in your system.

For more information refer to the following sections on the Capturing and cancelling payment charges page:

• Handling charge capture complete and failed events

• Handling the charge cancel success event

• Handling the order complete event

Orchestrated model

In the orchestrated model, as with all Digital River coordinated fulfillments, your SKU-inventory item pairs represent products whose fulfillment Digital River coordinates. In this model, Digital River is responsible for keeping these objects synchronized.

Digital River also handles order accepted, product shipment, and product cancellation events.

The following provides a high-level overview of how you might structure an orchestrated model workflow:

Creating and maintaining your product catalog

Prior to deployment, you should build a catalog of physical products whose fulfillment Digital River coordinates. For each product in this catalog, configure the SKU for Digital River managed fulfillments. This configuration results in SKU-inventory item pairs whose shared attribute values are synchronized by Digital River.

When building a checkout, you can add physical products from your Digital River managed fulfillment catalog or digital products from other catalogs.

If your site supports the necessary selling entities, then checkouts can also contain third-party fulfilled physical products.

Building checkouts and submitting orders

In both this model and the distributed model, you can use the same basic approach to build your checkouts and submit your orders.

How fulfillment of physical products is initiated

In the orchestrated model, once you build the checkout and submit the order, Digital River handles the order.accepted event by retrieving data from the order and other upstream resources and using it to submit a POST/fulfillment-orders. This request instructs our fulfillment services to initiate delivery of the order's physical products.

You should handle the order.accepted event by updating the status of the order in your commerce platform and by thanking customers for their purchase on an order confirmation page.

Responding to product pending and backordered events

If you give customers the option to cancel orders, then the fulfillment_order.pending event contains the fulfillment order identifier and fulfillment order line item identifiers that you need to create a fulfillment order cancellation.

You can also subscribe to the fulfillment_order.backordered event. It notifies you when a product is out of stock. You can handle this event by notifying customers of the delay and providing them the option to cancel the backordered products. If they select this option, submit a POST/fulfillment-cancellations.

For more information, refer to the Cancelling physical fulfillments page.

How product shipment events are handled

Digital River handles fulfillment_order.shipped events emitted by our fulfillment services. The ultimate source of these events are shipment notifications sent by the product's fulfiller.

The payload of each fulfillment_order.shipped contains data on which items, and in what quantity, the fulfiller has shipped to the customer. From each shipped event, Digital River retrieves the order identifier, shipment identifiers, as well as each line item's identifier and quantity and uses this data to submit an internal request that instructs our payment services to capture the appropriate amount of an order's payment charges.

You can listen for fulfillment.created events generated by this request. These events provide you access to tracking information. Alternatively, you can access this tracking information by subscribing to fulfillment_order.shipped.

How product cancellation events are handled

Digital River handles fulfillment_cancellation.accepted events. The source of these events are either POST/fulfillment-cancellations that your system submits or cancellations created by the product's fulfiller.

The payload of each fulfillment_cancellation.accepted event contains data on which items, and in what quantity, have been cancelled.

From each event, Digital River retrieves the order identifier, the line item identifier(s), and each items' cancelled quantity and uses this data to submit a request that instructs our payment services to cancel the appropriate amount of an order's payment charges.

To be notified when this request is submitted, you can subscribe to the fulfillment.created event.

Completing an order

Continue listening for and responding to fulfillment related events. After receiving each event, update the status of the order in your system.

For more information, refer to the following sections on the Capturing and cancelling payment charges page:

• Handling charge capture complete and failed events

• Handling the charge cancel success event

• Handling the order complete event

Building checkouts and submitting orders

In Digital River coordinated fulfillments, both the distributed model and the orchestrated model allow you to build checkouts and submit orders using the same basic approach.

For more information, refer to sequencing the checkout process on the Building checkouts page.

Building a checkout

As customers add items to their carts, you can use the Inventory Levels API to display product availability information on your storefront.

Once customers have finalized their cart and initiated checkout, send a create checkout request.

You can then use the checkout's shipping and product data to request shipping quotes through the Shipping Quotes API. Use the response to present shipping options to customers, and then, based on their selection, update the checkout with a shipping choice.

Later in the checkout process, you can retrieve the checkout's shipTo, shippingChoice and physical items[] and use this data to make a reservation request through the Reservations API. If successful, this request places a hold on the product's for the period of time you designate.

As with every checkout, you must also create a new payment source or authenticate an existing payment source and then ensure one or more sources are attached to the checkout.

You can then use the payment session to determine when to convert the checkout to an order.

Submitting an order

You convert the checkout to an order using the Orders API. This prompts Digital River to conduct a fraud review and, depending on the results of the payment authorization request, create a charge on each payment source.

For next steps:

• If you're using the distributed model, refer to Initiating physical product fulfillment.

• If you're using the orchestrated model, refer to How fulfillment of physical products is initiated