Managing a fulfillment order
In Digital River coordinated fulfillments, learn how to use the Fulfillment Orders API and Shipments API to manage fulfillment of physical products
Last updated
In Digital River coordinated fulfillments, learn how to use the Fulfillment Orders API and Shipments API to manage fulfillment of physical products
Last updated
A manages the fulfillment of a transaction's . You only use this resource in .
If you're using the , you must send a to initiate physical fulfillment.
Digital River submits this fulfillment order request if you use the .
You should subscribe to in distributed and orchestrated models. These events notify you of (1) , (2), (3) , and (4) .
You can also use to
In the , once you either or receive an in an state, your integration should by sending a create fulfillment order request. This request initiates the fulfillment of a transaction's .
In the , we listen for an order and handle this state change event by internally submitting a create fulfillment order request.
The following describes the request's required data and optional data:
Every POST/fulfillment-orders
request must include , , , , and data.
This required data can be retrieved from an in an state:
Order in an accepted
state
POST/fulfillment-orders
currency
âž”
currency
createdTime
âž”
upstreamOrderTime
shipTo.country
âž”
shipTo.country
shippingChoice.serviceLevel
âž”
shippingChoice.id
items[].skuId
âž”
items[].inventoryItemId
items[].quantity
âž”
items[].quantity
items[].tax.amount
âž”
items[].tax.amount
items[].id
âž”
items[].upstreamId
items[].amount
âž”
items[].total
shipTo.name
or billTo.name
âž”
name
or shipTo.name
shipTo.phone
or billTo.phone
âž”
phone
or shipTo.phone
shipTo.email
or billTo.email
âž”
email
or shipTo.email
shipTo
âž”
shipTo
id
âž”
upstreamId
locale
âž”
locale
checkoutId
âž”
reservationId
You can set the customer's name
, email
, and phone
at the fulfillment order level and within shipTo
.
id
âž”
shippingChoice.serviceLevel
âž”
shippingChoice.id
For example, you can use giftMessage
to send the downstream fulfiller a message that customers want included with the package. The giftWrap
flag allows you to indicate whether the product should be wrapped.
(1) When the fulfillment order...
(2) its state
transitions to...
is created but not yet partially or fully shipped
pending
partially or fully ships
shipped
is cancelled by the customer, the client or the fulfiller
cancelled
(1) When the line item...
(2) its state
transitions to...
has not yet partially or fully shipped
pending
backordered
partially or fully ships
shipped
is cancelled by the customer, the client or the fulfiller
cancelled
In all of these events, data.object
contains the unique identifier of:
Upon receiving a back-ordered notification from your channel's designated fulfiller, Digital River sends you a fulfillment_order.backordered
event. The event's data.object
contains an array of back-ordered items
.
For each product in the items
array, we provide an estimated availableTime
(assuming the fulfiller sends us this information). We also specify the original ordered
quantity as well as the quantity of backOrdered
items that triggered the event.
The totalBackordered
is the aggregated backOrdered
quantity from all the back-ordered events. When processing duplicate back-ordered events, you can use this value as a checksum, ensuring your system does not exceed the total ordered
amount.
You can use the fulfillment_order.backordered
event as a trigger to send a delayed order notification (typically an email) to the customer. We recommend providing a link directing customers to their order management page in the email.
The following table lists the data to retrieve from the event and then pass in a POST /fulfillments
.
Event
POST /fulfillments
data.object.id
âž”
shipmentId
items[].id
âž”
items[].shipmentItemId
fulfillmentOrderUpstreamId
âž”
orderId
items[].fulfillmentOrderItemUpstreamId
âž”
items[].itemId
items[].quantity
âž”
items[].quantity
Whenever a fulfillment order is fully or partially cancelled, we send you a fulfillment_order.cancelled
event.
The following table lists the data you must retrieve from each fulfillment_order.cancelled
event and then pass in a POST/fulfillments
.
fulfillment_order.cancelled
event
POST/fulfillments
upstreamId
âž”
orderId
items[].upstreamId
âž”
items[].itemId
items[].cancelled
âž”
items[].cancelQuantity
For the entire shipment, we provide you a trackingUrl
that directs customers to a page where they can enter the trackingNumber
provided by the trackingCompany
.
At the shipment item level, we also give you a trackingUrl
that directs customers to a page where they can enter the item's trackingNumber
and monitor the delivery progress of specific products.
In addition to other optional data, a POST/fulfillment-orders
request accepts , , , upstream order identifier, and locale data. If you place a hold on products, .
This optional data can be retrieved from an in an state:
The currency
in the request should be the same as the value in the upstream . This avoids creating downstream invoicing errors, issues with customs, and incorrect tax computations.
As with all , the createdTime
of the upstream is in and adheres to the standard. You should not modify this date-time value before setting it upstreamOrderTime
in a .
The shipTo
values should be the same as the upstream .
The reservationId
should reference the used to place a hold on the products.
When , you should value to be the same as the .
If the create fulfillment order request doesn't contain a reservationId
, Digital River tries to allocate the specified inventory items. If we determine inventory levels are too low, what happens at that point depends on whether you and whether your channel is set up to accept backorders.
When setting the shippingChoice.id
, you should use the . This value maps to the selected by the customer.
If you want to set the signatureRequiredType
, you'll need to persist with the selected by the customer. You can then retrieve the and use that value to set the fulfillment order's signatureRequiredType
.
If the upstream triggers the , then set the fulfillment order's dutiesPaid
to true
. This notifies the shipping carrier that the customer has already paid the full landed cost, and they should invoice you for any duties paid.
Use the items
array to specify product information. The must be retrieved from the upstream . The same applies to most of a fulfillment order's optional product data.
Once you successfully submit a POST/fulfillment-orders
request, a contains needed for downstream processing. Additionally, we return attributes that inform you of a and .
Once a is created, we assign it a unique identifier and assign unique identifiers to each of . You should persist all of these values.
You'll need the fulfillment order identifier to .
When submitting and , you must provide the fulfillment order identifier and the relevant line item identifiers.
In the , you can retrieve these identifiers from the 201 Created
response to a request.
In the , you can retrieve these identifiers by listening for the event.
You should be aware of both the and the. In both, each stage of the lifecycle is represented by a state
.
The state
attribute at the fulfillment order level indicates where a is in its lifecycle. The values for successful fulfillment (i.e., the happy path) are pending
> shipped
.
The line item state
attribute indicates where a 's line item is in its lifecycle. The values for a successfully fulfilled line item (i.e., the happy path) are pending
> shipped
.
is configured to and is awaiting restocking
Each element of items
array indicates how many items are pending
, backordered
, shipped
, cancelled
, and returned
. In aggregate, these values equal the total quantity
of that line item, representing the amount originally purchased by the customer.
You can determine a by either or .
There are two methods you can use in the to retrieve fulfillment orders. You can filtered by optional query parameters. You can also by including its unique identifier as a path parameter in the request.
We recommend you respond to a changes by listening for the , , , and events.
The
The and each of
Each line item's .
When Digital River queues a fulfillment order for creation, we create a fulfillment_order.pending
event. The event's data.object
is a in a state.
In the , use this event to retrieve and save the fulfillment order's and each line item's identifiers.
A fulfillment order doesn't necessarily mean that all of its line items are also . A line item can be pending
, shipped
, backordered
or cancelled
while the fulfillment order is still pending
.
On this page, you should allow customers to cancel the order fully or partially. If they select either option, make sure you respond to this event by submitting a .
Once Digital River receives a shipped notification from your channel's designated fulfiller, we create an with a of fulfillment_order.shipped
. Its data.object
consists of a . To , persist data.object.id
, which represents the shipment's identifier.
In the event's payload, fulfillmentOrderUpstreamId
represents the id
and each items[].fulfillmentOrderItemUpstreamId
maps to an items[].id
in that .
In the , respond to this event by sending a request, which captures the appropriate amount of an payment .
The source of these events is requests that your system submits or cancellation notifications sent by the product's fulfiller. The event's data.object
is a in a cancelled
state.
The event's payload, upstreamId
represents the and items[].upstreamId
represents a in an .
In the , every time you receive fulfillment_order.cancelled
, retrieve data from the event and send it in a request. This request instructs Digital River to the appropriate amount of an payment .
In the , we listen for the cancelled event and respond by submitting an internal payment cancel request.
A products can be delivered to the end customer in one or more shipments, each represented by the .
You can use the unique shipment identifier you receive in a event to that return a and provide .
There are two methods for querying the . You can retrieve an individual shipment by sending its unique identifier as a path parameter in a request. You can also submit a request to retrieve a list of shipments and use optional query parameters to filter the results.
A items
array returns each shipment item's unique identifier, and the item's shipped quantity
. All the relevant upstream identifiers of the item are also included.
Additionally, when the shipped item is a smartphone or cellphone, the downstream fulfiller may pass back to you unitAttributes
that help identify and track the device. These attributes consist of a serial, , or card number
A provides numerous data points that you can use to track a delivery's progress.