LogoLogo
System Status
  • Digital River API
  • Getting started
  • Using our services
    • Local pricing
    • Item classification
    • Subscriptions
    • e-Invoicing
  • Integration options
    • Low-code checkouts
      • Implementing a Prebuilt Checkout
      • Implementing a Components checkout
      • Offering local pricing
      • Using a shipping endpoint
      • Processing subscription acquisitions
      • Adding custom fields
      • Offering store credit
      • Displaying policies and getting consent
      • Collecting e-invoice information
      • Handling completed checkout-sessions
    • Direct integrations
      • Standard flow
      • Building checkouts
        • Checking out guest and registered customers
        • Describing line items
          • Setting the price of an item
          • Managing items with shared SKU identifiers
        • Providing address information
        • Handling shipping choice
        • Tax identifiers
        • Applying a discount
        • Setting the customer type
        • Providing the IP address
        • Selecting a currency
        • Initiating a charge
        • Setting the purchase location
        • Configuring taxes
        • Accessing regulatory fee information
        • Localizing invoices and credit memos
        • Providing an upstream identifier
        • Applying store credit
        • Handling e-invoicing requirements
        • Landed cost
        • Tax calculation inputs
        • Selling entities
        • Payment sessions
        • Applying store credit (legacy)
        • Country specs
      • Building payment workflows
        • Handling redirect payment methods
        • Handling delayed payment methods
      • Subscription acquisitions
        • Handling subscription acquisitions
        • Handling external subscription acquisitions
        • Subscription information
      • Digital River coordinated fulfillments
        • Checking inventory levels
        • Using shipping quotes
        • Reserving inventory items
        • Managing a fulfillment order
        • Cancelling a fulfillment order
    • Connectors
  • Order management
    • Processing orders
    • Handling a rejected order
    • Accessing invoices and credit memos
    • Fulfilling goods and services
    • Capturing and cancelling charges
    • Payment reauthorizations
    • Handling reversals
      • Return basics
        • Digital River coordinated returns
        • Third party coordinated returns
      • Refund basics
        • Issuing refunds
        • Refunding asynchronous payment methods
      • Disputes and chargebacks
    • Customer notifications
    • Responding to events
      • Events
        • Key event types
        • All event types
      • Webhooks
        • Creating a webhook
        • Digital River API safelist
        • Digital River signature
      • Expanding events
      • Preventing webhooks from getting disabled
    • Distributor model
  • Subscription Management
    • Managing a subscription
    • Managing an external subscription
  • Payments
    • Payment solutions
      • Drop-in payments
        • How Drop-in payments work
        • Drop-in payments integration guide
      • DigitalRiver.js with Elements
        • Elements integration guide
        • Configuring payment methods
          • Configuring Afterpay
          • Configuring Alipay+ (cross-border)
          • Configuring Alipay (domestic)
          • Configuring Amazon Pay
          • Configuring Apple Pay
          • Configuring Bancontact
          • Configuring BNP Paribas
          • Configuring BLIK
          • Configuring CCAvenue
          • Configuring Clearpay
          • Configuring Credit Cards
          • Configuring FPX Online Banking
          • Configuring Google Pay
          • Configuring iDEAL
          • Configuring Klarna
          • Configuring Konbini
          • Configuring Online Banking (IBP)
          • Configuring Online Banking (Korea Bank Transfer)
          • Configuring PayCo
          • Configuring PayPal
          • Configuring SEPA Direct Debit
          • Configuring Trustly
          • Configuring Wire Transfer
          • Common payment sources
          • Common payment objects
    • Supported payment methods
      • Afterpay
      • Alipay (domestic)
      • Alipay+ (cross-border)
      • Amazon Pay
      • Apple Pay
      • Bancontact
      • BNP Paribas
      • BLIK
      • CCAvenue
      • Clearpay
      • Credit Cards
      • FPX Online Banking
      • Google Pay
      • iDEAL
      • Klarna
      • Konbini
      • Korea Bank Transfer (Online Banking)
      • Online Banking (IBP)
      • Pay with Installments France
      • PayCo
      • PayPal
      • PayPal Billing Agreement
      • PayPal Credit
      • PayPal Pay in 3
      • PayPal Pay in 4
      • PayPal RatenZahlung (Installment Payment)
      • SEPA Direct Debit
      • Trustly
      • Wire Transfer
    • Source basics
      • Managing sources
      • Handling credit card sources
      • Retrieving sources
    • Authorization declines
    • PSD2 and SCA
      • How to ensure SCA compliance
    • Payment testing scenarios
  • Product management
    • Product basics
    • Managing SKUs
    • Using product details
    • Grouping SKUs
    • SKU-inventory item pairs
    • Managing inventory items
    • Regulatory fees
      • What are regulatory fees?
        • Fees terminology
        • Regulatory fee management
        • European regulatory fees
        • Compliance obligations
        • WEEE directive requirements
        • Copyright directive requirements
        • Compliance challenges
      • Managing regulatory fees
  • Customer management
    • Customer basics
    • Creating and updating customers
    • Setting up tax exemptions
    • Recording a customer's request to be forgotten
  • Financial reporting
    • Financials basics
    • Sales transactions
      • Returning a list of sales transactions
      • Getting a sales transaction by ID
    • Sales summaries
      • Returning a list of sales summaries
      • Getting a sales summary by ID
    • Payouts
      • Returning a list of payouts
      • Getting a payout by ID
      • Get a list of transactions included in payout by ID
  • Developer resources
    • Digital River API reference
    • DigitalRiver.js reference
      • Including DigitalRiver.js
      • Initializing DigitalRiver.js
      • DigitalRiver object
      • Elements
        • Amazon Pay element
        • Apple Pay elements
        • Google Pay elements
        • IBAN element
        • iDEAL element
        • Konbini elements
        • Compliance element
        • Offline Refund elements
        • Online Banking elements
        • Tax Identifier element
        • Invoice attribute element
        • Delayed Payment Instructions element
        • PayPal elements
      • Guidelines for capturing payment details
      • Security
      • Digital River payment objects
      • Error types, codes, and objects
    • DigitalRiverCheckout.js reference
      • Including DigitalRiverCheckout.js
      • Initializing DigitalRiverCheckout.js
        • DigitalRiverCheckout configuration object
      • DigitalRiverCheckout object
        • Configuring Prebuilt Checkout
          • Performing actions
          • Defining experience
        • Components
          • Configuring components
          • Address component
          • Shipping component
          • Tax identifier component
          • Invoice component
          • Wallet component
          • Payment component
          • Compliance component
          • Order summary component
          • Thank you component
        • Rendering a checkout button
          • Performing actions on the checkout button
        • Determining the checkout's status
      • Accessing country and currency
    • DynamicPricing.js reference
    • Postman collection
  • administration
    • Sign in
    • Digital River Dashboard
      • Digital River Dashboard quick start guide
      • Key features
      • Reset your password
      • Test and production environments
      • Account
        • Adding an account
        • Switching accounts
        • Account access
      • Profile settings
        • Viewing your personal information
        • Changing your password
        • Updating your phone number
        • Enabling multi-factor authentication
      • Finance
        • Payouts
          • Viewing your payout details
          • Filtering your payouts
          • Exporting your payouts
        • Sales summaries
          • Viewing your sales summaries details
          • Filtering your sales summaries
          • Exporting your sales summaries
          • Exporting your sales summary details
        • Transactions
          • Viewing your transaction details
          • Filtering your transactions
          • Exporting your transactions
      • Order management
        • Orders
          • Searching for orders
          • Filtering your orders
          • Viewing the order details
          • Cancelling items
          • Fulfilling items
          • Downloading an invoice
          • Downloading a credit memo
          • Creating shipping labels
          • Recording a customer's request to be forgotten
          • Viewing returns and refunds
          • Creating a return
          • Accepting a return
          • Creating a refund
          • Viewing the order's timeline
        • Checkouts
          • Searching for checkouts
          • Filtering your checkouts
          • Viewing the checkout details
        • Prebuilt Checkout links
          • Generate Prebuilt Checkout links
          • View and work with Prebuilt Checkout link details
          • Add a customer during Prebuilt Checkout
          • Add a product during Prebuilt Checkout
      • Customers
        • Viewing customer details
        • Searching for customers
        • Filtering your customers
        • Editing account information
        • Adding a customer
        • Tax IDs and certificates
          • Adding a tax certificate
          • Adding a tax ID
          • Deleting a tax ID
        • Metadata
          • Adding metadata
          • Editing metadata
        • Manage subscriptions from the Customer Details page
        • Disabling a customer
        • Recording a customer's request to be forgotten
        • Deleting a customer
      • Catalog
        • SKUs
          • Viewing the SKU details
          • Searching for SKUs
          • Filtering your SKUs
          • Adding a SKU
          • Editing a SKU
          • Deleting a SKU
          • Adding a fee to a SKU
          • Editing a fee
          • Deleting a fee
          • Viewing product tariff codes
        • Managing customer subscriptions from Digital River Dashboard
      • Developers
        • API keys
          • Updating your API version
          • Getting your API keys
          • Changing the API version for your key
          • Creating a restricted key
          • Editing a restricted key
          • Deleting a restricted key
          • Rotating keys
        • Webhooks
          • Creating a webhook
          • Editing a webhook
          • Deleting a webhook
          • Rotating a webhook's secret
        • API logs
          • Filtering the API log
          • Viewing the API log details
        • Event logs
          • Filtering the events log
          • Viewing the event details
      • Settings
        • Users and roles
          • Roles
          • Searching for a user by name or email
          • Filtering your users and roles
          • Adding a user
          • Editing a user
          • Deleting a user
        • Prebuilt Checkout
        • Payment methods
          • Viewing your payment methods
          • Viewing payment method details
            • Enabling currencies
            • Managing countries
          • Enabling or disabling a payment method
  • General Resources
    • eCompass
    • eCompass documentation
    • Release notes
      • 2024
      • 2023
      • 2022
      • 2021
      • 2020
      • 2019
    • Standards and certifications
      • Certification process
      • Compliance requirements
      • Documentation requirements
      • Integration checklists
        • Admin portal
        • Products and SKUs
        • Customers and tax exemptions
        • Checkouts, payment sources, and orders
        • Disclosures, compliance statements, and emails
        • Fulfillments and cancellations
        • Customer portal
        • Order refund synchronization
        • Reversals
        • Error handling
      • Test and use cases
    • Commerce infrastructure
    • Versioning
    • Glossary
Powered by GitBook
On this page
  • Creating a fulfillment order
  • Currency
  • Upstream order time
  • Customer information
  • Ship to address
  • Attaching a reservation
  • Shipping choices
  • Product information
  • A fulfillment order
  • Unique identifiers
  • The fulfillment order life cycle
  • Product status by category
  • Monitoring and responding to a fulfillment order
  • Retrieving a fulfillment order
  • Listening and responding to fulfillment order events
  • Tracking a shipment
  • Querying the Shipments API
  • Determining the contents of a shipment
  • Monitoring the progress of a shipment
  1. Integration options
  2. Direct integrations
  3. Digital River coordinated fulfillments

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

PreviousReserving inventory itemsNextCancelling a fulfillment order

Last updated 2 months ago

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

Creating a fulfillment order

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:

For a full list of specifications, refer to the reference documentation.

Required 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

Optional data

items[].id

âž”

items[].upstreamId

items[].amount

âž”

items[].total

shipTo.nameor billTo.name

âž”

name or shipTo.name

shipTo.phoneor billTo.phone

âž”

phone or shipTo.phone

shipTo.emailor billTo.email

âž”

email or shipTo.email

shipTo

âž”

shipTo

id

âž”

upstreamId

locale

âž”

locale

checkoutId

âž”

reservationId

Currency

Upstream order time

{
    "id": "186962110336",
    "createdTime": "2021-04-02T18:46:45Z",
    ...
}

Customer information

You can set the customer's name, email, and phone at the fulfillment order level and within shipTo.

Ship to address

Attaching a reservation

Shipping choices

Shipping quote
Order
Fulfillment Order

id

âž”

shippingChoice.serviceLevel

âž”

shippingChoice.id

Product information

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.

A fulfillment order

Unique identifiers

The fulfillment order life cycle

Fulfillment order level

(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

Line item level

(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

Product status by category

Monitoring and responding to a fulfillment order

Retrieving a fulfillment order

Listening and responding to fulfillment order events

In all of these events, data.object contains the unique identifier of:

Fulfillment order pending events

Fulfillment order back-ordered events

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.

{
    "id": "evt_e381g2ff-7d42-3b05-91d5-e711443r3521",
    ...
    "data": {
        "object": {
            ...
            "items": [
                {
                    ...
                    "ordered": 6,
                    "backordered": 2,
                    "totalBackordered": 3,
                    "availableTime": 2020-11-25T20:36:00Z,
                    ...
                }
            ],
            ...
        },
        "previousAttributes": {}
    },
    ...
    "type": "fulfillment_order.backordered"
}

Fulfillment order shipped events

{
    "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
    ...
    "data": {
        "object": {
            "id": "29016544906",
            ...
            "fulfillmentOrderId": "5774321009",
            "fulfillmentOrderUpstreamId": "9292981838",
            ...
            "items": [
                {
                    "id": "8760948870",
                    "fulfillmentOrderItemId": "650398674428",
                    "fulfillmentOrderItemUpstreamId": "650398674428",
                    ...
                    "quantity": 1,
                    ...
                }
            ],
            ...
        },
        "previousAttributes": {}
    },
    ...
    "type": "fulfillment_order.shipped"
}

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

Fulfillment order cancelled events

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

Tracking a shipment

Querying the Shipments API

Determining the contents of a shipment

Monitoring the progress of a shipment

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.

product cancellation
return requests
create fulfillment cancellation request
IMEI
SIM
product
customer
ship to
attach the reservation identifier
retrieve the object
fulfillment order's lifecycle
fulfillment order's line item's lifecycle
fulfillment order
fulfillment order
fulfillment order's
state
pending
backordered
shipped
cancelled
fulfillment order and each of its line items
fulfillment order
pending
pending
pending
shipment resource
fulfillment order's
fulfillment_order.shipped
submit queries
shipment's contents
tracking information
SKU-inventory item pairs
Digital River coordinated fulfillments
SKU-inventory item pairs
order
fulfillment order
create fulfillment order request
events that occur during a fulfillment order's lifecycle
pending shipments
back-ordered products
shipped products
product cancellations
track the progress of a delivery.
currency
created time
shipping address
shipping method
product
UTC
ISO-8601
fulfillment order
order's
reservation
order
order
order's
order
unique identifiers
fulfillment order's state
categorize the status of its line items
its line items
fulfillment_order.pending
state
calling the API
listening for webhook events
track a shipment's progress
order's
fulfillment order
orchestrated model
orchestrated model
orchestrated model
upstream order
its line items
unique identifier
line item's identifier
distributed model
orchestrated model
distributed model
orchestrated model
synchronously
asynchronously
accepted
handle the order state change event
distributed model
distributed model
distributed model
line items
creating a reservation
set the reservation's identifier
shipTo
type
checkout's identifier
landed cost feature
allow oversell
allow overselling of an item
SKU-inventory item pair
shipments
order
POST /fulfillment-orders
accepted
Fulfillment Orders APIs
accepted
order
accepted
order
fulfillment order's
fulfillment order's
fulfillment order's
fulfillment order
fulfillment order
POST /fulfillment-orders
fulfillment order's
fulfillment order's
Fulfillment Orders API
get a list of fulfillment orders
get an individual fulfillment order
event
shipment
order
POST /fulfillments
order's
charges
POST /fulfillment-cancellations
POST /fulfillments
cancel
order's
charges
shipments API
GET /shipments/{id}
GET /shipments
shipment's
shipment
shippingChoice.serviceLevel
fulfillment order's
order's
order
fulfillment order's
identifier of the shipping quote
shipping quote
shipping quote's signatureRequiredType
dates and times in the Digital River APIs