Fulfillments
Learn how to manage fulfillments orchestrated by both Digital River and third-parties.
When building your fulfillment solution, the specific APIs that you should use, and the sequence that you use them in, depends on whether Digital River coordinates an order's fulfillment or whether you've delegated that responsibility to a third party.

Digital River coordinated fulfillments

This section provides an overview of the two Digital River coordinated fulfillment models that we support. Both models allow you to build checkouts with physical and digital products, display product availability information, 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 construct SKU-inventory item pairs with common attributes whose values must remain synchronized.
The major differences between the client fulfillment model and the Digital River fulfillment 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 payment processing, product shipment, and product cancellation events.

Client fulfillment model

In this 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 then manage their relationship. You also must listen for the order.accepted event and then send a downstream request to initiate a physical fulfilment. When you receive product shipment and product cancellations events, you then send the appropriate payment capture and payment cancellation requests.
The following provides a high-level overview of how you might structure a client fulfillment workflow.

Creating and maintaining your product catalog

Prior to accepting orders, we recommend that you build a catalog of physical products whose fulfillment Digital River coordinates. For each product in the catalog, you'll need to use the SKUs API and Inventory Items API to create SKU-inventory item pairs with common attribute values and then ensure those values remain synchronized.
This coupled relationship needs to be maintained because your workflow must attach at least one SKU to every create checkout request. Then, later in the fulfillment process, you also need to attach an inventory item with an identical identifier to a create fulfillment order request.
If the common attributes of each SKU-inventory item pair are not synchronized, you risk encountering problems with customs, generating incorrect duty amounts or having errors displayed on the invoice.
POST/skus
POST/inventory-items
POST/checkouts
POST/fulfillment-orders
id
id
items[].skuId
items[].inventoryItemId
When using the Checkouts API to build a checkout, you can add physical SKUs from the catalog of products whose fulfillment Digital River coordinates or digital SKUs from other catalogs.

Building checkouts and submitting orders

In both this model and the Digital River fulfillment model, you can use the same basic approach to structure your checkout processing and order submission workflows.

Responding to payment processing events

In the client model, your integration needs to synchronously or asynchronously receive an Order in an accepted state. You can then retrieve data from its payload and send that data in a POST/fulfillment-orders. This request instructs Digital River to initiate the physical fulfillment of an order's products.

Responding to product backordered events

You should listen for fulfillment_order.backordered events so you know when to notify customers that a product is out of stock.

Responding to product shipment events

In this model, your integration needs to subscribe to fulfillment_order.shippedevents. The source of these events are shipment notifications that we receive from the product's fulfiller.
The payload of each shipped event informs you which items, and in what quantity, have been shipped to the customer. For each shipped event that you receive, retrieve the required data and use it to define and then submit a POST/fulfillments request. This instructs Digital River to capture the appropriate amount from the order's payment charges.
These shipped events also contain a unique identifier that allow you to track each shipment through the Shipments API.

Responding to product cancellation events

You also need to listen for fulfillment_order.cancelledevents emitted by our fulfillment system. The source of these events are either POST/fulfillment-cancellations that your system submits or cancellation notifications that we receive from the product fulfiller.
The payload of each fulfillment_order.cancelled event informs you which items, and in what quantity have been cancelled. For each cancelled event that you receive, retrieve the required data, and use it to define and then submit a POST/fulfillments request. This instructs Digital River to cancel the appropriate amount of the order's payment charges.

Completing an order

Listen for order.fulfilled and order.complete events. After receiving each event, update the status of the order in your system.

Digital River fulfillment model

In this model, as with all Digital River coordinated fulfillments, your SKU-Inventory Item pairs represent products whose fulfillment Digital River coordinates. The relationship between these objects is managed by Digital River. We also listen for and handle payment processing, product shipment, and product cancellation events.
The following provides a high-level overview of how you might structure this workflow.

Creating and maintaining your product catalog

Prior to accepting orders, you should build a catalog of physical products whose fulfillment Digital River coordinates. For each product in the catalog, you must configure a SKU for Digital River managed fulfillments. This configuration process creates SKU-inventory pairs whose common attribute values remain synchronized.
When using the Checkouts API to build a checkout, you can add products from your Digital River managed fulfillment catalog or digital products from other catalogs.
If your site supports the necessary selling entities, then your checkout can also contain third-party fulfilled products.

Building checkouts and submitting orders

In both this model and the client fulfillment model, you can use the same basic approach to structure your checkout processing and order submission workflows.

Payment processing events

Digital River listens for the order.accepted event coming from our payment processing system. You should also listen for this event so that you can update the status of the order in your own system.
Upon arrival, we retrieve specific data from the event and other upstream resources, translate it, and then use that translated data to automatically submit an internal request that mimics a POST/fulfillment-orders. This internal request instructs our fulfillment system to initiate the physical delivery of an order's products.

Responding to product pending and backordered events

In this model, we recommend you subscribe to fulfillment_order.pending events so that you have the data you need to cancel products. You should also listen for fulfillment_order.backordered events so you know when to notify customers that a product is out of stock.

Product shipment events

Digital River listens for fulfillment_order.shippedevents emitted by our fulfillment system. The source of these events are shipment notifications that we receive from the product's fulfiller.
The payload of each fulfillment_order.shipped event informs us which items, and in what quantity the fulfiller has shipped to the customer. For each shipped event that we receive, we retrieve the appropriate data, translate it, and then use that translated data to automatically submit an internal request that mimics a POST/fulfillments with the appropriate orderId, shipmentId, items[].itemId, items[].shipmentItemId, and items[].quantity in the payload. This internal request instructs our payment processing system to capture the appropriate amount from the order's payment charges. To be notified of when this request is submitted, you can listen for fulfillment.created events.
We recommend that you also subscribe to fulfillment_order.shippedevents. This is because these events contain a unique identifier that you can use to track each shipment through the Shipments API.

Product cancellation events

Digital River listens for fulfillment_order.cancelledevents emitted by our fulfillment system. The source of these events are either POST/fulfillment-cancellations that your system submits or cancellation notifications that we receive from the product fulfiller.
The payload of each fulfillment_order.cancelled event informs us which items, and in what quantity have been cancelled. For each cancelled event that we receive, we retrieve the appropriate data, translate it, and then use that translated data to automatically submit an internal request that mimics a POST/fulfillments with the appropriate orderId, items[].itemId, and items[].cancelQuantity in the payload. This internal request instructs our payment processing system to cancel the appropriate amount from the order's payment charges. To be notified of when this request is submitted, you can listen for fulfillment.created events.

Completing an order

You should listen for order.fulfilled and order.complete events. After receiving each event, update the status of the order in your system.

Structuring checkout processing and order submission

Once you've created product catalogs, both the client model and the Digital River model allow you to build checkouts and submit orders using the same fundamental process.

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 provided a ship to address, send this information in a create or update checkout request.
You can retrieve ship to and product data returned by the Checkouts API and then use it to request shipping quotes through the Shipping Quotes API. The response allows you to present shipping options to the customer, and then, based on the customer's selection, use the selected shipping quote to update the checkout.
Later in the checkout process, you can once again retrieve data returned by the Checkouts API and then use it to make a reservation request through the Reservations API. Once successfully submitted, this request places a hold on the product's for a designated period of time.
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 either attached to the checkout, or, in the case of of a registered checkout, saved to the customer's account. You'll also need to validate that all address requirements are met.

Submitting an order

Once the payment session is in the correct state, you can convert the checkout to an order using the Orders API. This prompts Digital River to conduct a fraud review and, depending on the authorization request, create a charge from each payment source.
After submitting an order, if you're using the client model, you need to handle the primary payment processing event. If you're using the Digital River model, you should listen for this payment processing event.

Third-party coordinated fulfillments

If you have a third-party fulfillment system in place, meaning Digital River does not orchestrate the delivery of your goods, then the Fulfillments API is what you'll primarily use to handle an order's fulfillment.
For every order, by submitting one or more POST/fulfillments requests, you're informing Digital River which products, and in what quantity, have been fulfilled or cancelled. Depending on the data you provide, we then attempt to capture or cancel the appropriate payment charge.
For third-party coordinated fulfillments, the following diagram outlines the major steps in creating, processing, and delivering orders to customers that contain physical and digital goods.
Last modified 26d ago