Capturing and cancelling payment charges

Learn how to inform Digital River that products are fulfilled or cancelled so that we can attempt to capture or cancel payment.

Once you successfully create an order for your customer, and have received the necessary events, you can use the Fulfillments API to inform Digital River of the items that are fulfilled or cancelled. Each time you define and submit a create fulfillment request, you're telling us the quantity of items that have been fulfilled, cancelled or some combination of both.

We then use the information contained in these requests to capture or cancel the appropriate amount of the payment charge.

After an order is fulfilled, you should always use the Fulfillments API to capture or cancel payment. This is true whether Digital River coordinates your fulfillment or a third-party handles that process.

Receiving the necessary events

Before you can define and send a fulfillment request, you must first consume the appropriate events.

When a third-party fulfills your products, you only need to receive the order accepted event.

For Digital River coordinated fulfillments, you need to receive both the order accepted event and the fulfillment order shipped event.

Order accepted events

When a customer creates and submits an order from your storefront, Digital River receives the order, processes it and then, assuming the payment charge is authorized and fraud review is passed, sends an order.accepted event to your fulfillment subsystem.

The data.object of this event gives you back the order in an accepted state. More specifically, it means that the order has passed fraud review and contains a charge in a capturable state.

Your integration should always wait until it receives this order.accepted event before defining and creating a fulfillment. By doing so, you reduce the risk of fraud and the frequency of charge-backs.

Fulfillment order shipped events

Telling Digital River to capture or cancel a payment is slightly more complex when we coordinate the physical fulfillment of your order. In these cases, you must first receive the order accepted event, then create a fulfillment order, wait until you've received an order shipped event, before finally defining and creating a fulfillment.

Defining fulfillments

Once you've received the appropriate events, you'll first need to define the fulfillment before you submit a POST/fulfillments request.

You define a fulfillment by providing the identifier of the upstream order, supplying information about each fulfilled and/or cancelled item and specifying tracking data. For Digital River coordinated fulfillments, you also need to provide shipment identifiers.

Fulfilled and cancelled items

The items array allows you to specify the unique identifier of each product in the request, as well as the quantity fulfilled and/or cancelled. You don't have to specify both a quantity and cancelQuantity, but you must provide one or the other.

If your request specifies a quantity, thereby informing Digital River that these items are fulfilled, we attempt to capture the appropriate amount of the payment charge. Conversely, if you specify a cancelQuantity, we cancel the relevant charge amount.

Shipment identifiers

When Digital River coordinates an order's physical fulfillment, your integration must include shipment identifiers in the POST/fulfillments request. Specifically, you're required to provide a single shipmentId and, for each item in the shipment, a unique shipmentItemId .

These identifiers are contained in the shipment notification events we send to your application. For everyfulfillment_orders.shipped event that you receive, your integration must retrieve its relevant data and pass it in a POST/fulfillments request.

Tracking data

When defining a fulfillment, you can also provide information on the name of the trackingCompany, the trackingNumber provided by the shipping carrier, and the trackingUrl of the page to monitor the shipment.

For Digital River fulfilled orders, you can retrieve this tracking data from the shipment object you receive in a fulfillment order shipped event.

Submitting fulfillment and cancellation requests

You use the POST/fulfillments method to inform us of fulfillments and cancellations. The examples in this section are based on the following order, which contains two line items, both representing physical products:

JSON
JSON
{
"id": "182214770336",
...
"items": [
{
"id": "102640900336",
"skuId": "1bcc61cb-b269-477d-9591-b63c6c6567fa",
"amount": 600.0,
"quantity": 6,
...
},
...
},
{
"id": "102640910336",
"skuId": "c0ba2797-e816-40cb-80bc-02195b79a381",
"amount": 600.0,
"quantity": 6,
...
},
...
}
],
...
}

Partially fulfilling and cancelling an order

Let's say your fulfiller is not yet ready to completely deliver an order. But a portion has shipped and another portion was cancelled by the customer.

In this case, you can submit a POST/fulfillments request that notifies Digital River of the relevant fulfillments and cancellations. The request needs to provide the orderId and, for each item in the request, you also need to specify an itemId, a fulfilled quantity , and a cancelQuantity.

cURL
cURL
curl --location --request POST 'https://api.digitalriver.com/fulfillments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
--data-raw '{
"orderId": "182214770336",
"items": [
{
"itemId": "102640900336",
"quantity": 3,
"cancelQuantity": 2
},
{
"itemId": "102640910336",
"quantity": 2,
"cancelQuantity": 3
}
]
}'

A successful response returns a fulfillment with a unique id. Although not specified in the POST/fulfillments request, the skuId associated with each line item is also returned.

201 Created
201 Created
{
"id": "ful_2e9dc1f7-8d48-405c-abf4-0301b85dc505",
...
"items": [
{
"quantity": 3,
"cancelQuantity": 2,
"skuId": "1bcc61cb-b269-477d-9591-b63c6c6567fa",
"itemId": "102640900336"
},
{
"quantity": 2,
"cancelQuantity": 3,
"skuId": "c0ba2797-e816-40cb-80bc-02195b79a381",
"itemId": "102640910336"
}
],
"orderId": "182214770336",
...
}

Completely fulfilling the order

When your fulfiller completely fulfills this order, you can submit another POST/fulfillments request:

curl --location --request POST 'https://api.digitalriver.com/fulfillments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
--data-raw '{
"orderId": "182214770336",
"items": [
{
"itemId": "102640900336",
"quantity": 1
},
{
"itemId": "102640910336",
"quantity": 1
}
]
}'

A successful request returns a unique fulfillment (not pictured) and generates an order.fulfilled event. If you then attempt to fulfill or cancel any part of the order, you'll receive the following error:

409 Conflict
409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "order_complete",
"parameter": "orderId",
"message": "Order '182214770336' is complete."
}
]
}

Using fulfillment-related events

After you create a successful fulfillment on all or part of an order, a fulfillment.created event is generated. When your POST/fulfillments request specified a quantity, thereby informing Digital River you fulfilled items, we attempt to capture the appropriate charge amount. Conversely, if you provided a cancelQuantity, we cancel that payment.

These actions trigger a series of events related to order charge captures and cancels that you can consume when building your integration.

Retrieving fulfillments by order identifier

At any time, you can return a list of fulfillments associated with an order by sending a GET/fulfillments request and using a query parameter to filter by orderId. The data array returned in the response contains the fulfillments created in this order.

200 OK
200 OK
{
"data": [
{
"id": "ful_c6a542ce-6e76-4cb7-8d69-d890bad66c64",
"createdTime": "2020-11-30T21:35:55Z",
"items": [
{
"quantity": 1,
"cancelQuantity": 0,
"skuId": "1bcc61cb-b269-477d-9591-b63c6c6567fa",
"itemId": "102640900336"
},
{
"quantity": 1,
"cancelQuantity": 0,
"skuId": "c0ba2797-e816-40cb-80bc-02195b79a381",
"itemId": "102640910336"
}
],
"orderId": "182214770336",
"liveMode": false
},
{
"id": "ful_2e9dc1f7-8d48-405c-abf4-0301b85dc505",
"createdTime": "2020-11-30T21:31:49Z",
"items": [
{
"quantity": 3,
"cancelQuantity": 2,
"skuId": "1bcc61cb-b269-477d-9591-b63c6c6567fa",
"itemId": "102640900336"
},
{
"quantity": 2,
"cancelQuantity": 3,
"skuId": "c0ba2797-e816-40cb-80bc-02195b79a381",
"itemId": "102640910336"
}
],
"orderId": "182214770336",
"liveMode": false
}
],
"hasMore": false
}