Fulfilling and cancelling an order

Learn how to create and cancel fulfillments.

A Fulfillment represents the full or partial fulfillment of a physical or digital order. Each time you submit a create Fulfillment request, you're telling us the quantity of items you have fulfilled, cancelled or some combination of both. In addition, the Fulfillment object also contains attributes that allow you to store tracking data.

Before creating a Fulfillment, we recommended you wait until the state of the Order is accepted and you've received an order.accepted event. This is because an accepted Order has passed fraud review and contains a Charge in a capturable state. If you hold back on creating a Fulfillment until the Order has transitioned to this state, you reduce the risk of fraud and the frequency of charge-backs.

We also recommend that you use webhooks to be notified when a fulfillment is successfully created, and to listen for capture and cancel events.

Setting fulfillment parameters

When you create a Fulfillment request, you'll need to provide the required parameters listed in the following table. The remaining parameters are optional.

Parameter

Required/Optional

Description

orderId

Required

The identifier of the Order associated with this Fulfillment.

items

Required

Refer to Setting item parameters

trackingCompany

Optional

The name of the tracking company.

trackingNumber

Optional

The tracking number provided by the shipping company.

trackingUrl

Optional

The URL of the fulfillment tracking page

Setting item parameters

These parameters allow you to fulfill or cancel all or part of an individual line item in an Order.

Parameter

Description

itemId

The unique identifier a line item in the Order. You are required to provide this value.

quantity

The quantity of the items fulfilled. You must provide either this value and/or a value for the cancelQuantity parameter.

cancelQuantity

The quantity of the items cancelled. You must provide either this value and/or a value for the quantity parameter.

Sample fulfillments and cancellations

The example in this section is based on an Order that contains the following line items:

JSON
JSON
{
"id": "177759770336",
"createdTime": "2020-06-04T17:52:00Z",
"customerId": "517796760336",
...
"items": [
{
"id": "96791310336",
"skuId": "f4f06b2b-f091-41b4-b18f-5c59a7414659",
"amount": 17.97,
"quantity": 3,
...
},
{
"id": "96791320336",
"skuId": "94a3f3d0-676e-49ea-b07b-4ba32f7bfdd5",
"amount": 31.98,
"quantity": 2,
...
}
],
...
}

Partially fulfilling an order

Let's say you're not ready to completely fulfill the Order but a portion of it is ready to be shipped. You can use a create Fulfillment request to fulfill the relevant items. The request needs to provide the orderId and, for each item in the fulfillment request, you'll also need to specify an itemId and a fulfilled quantity .

cURL
cURL
curl --location --request POST 'https://api.digitalriver.com/fulfillments' \
--header 'Authorization: Bearer <API_key>' \
--header 'Content-Type: text/plain' \
--data-raw '{
"orderId": "177759770336",
"items": [
{
"itemId": "96791310336",
"quantity": 1
},
{
"itemId": "96791320336",
"quantity": 1
}
]
}'

The 201 Created response returns a unique id for the Fulfillment. Although not specified in the request, the skuId associated with each item is also returned.

JSON
JSON
{
"id": "ful_3d55b951-c6ff-4973-b0c9-c1ca91da768c",
"createdTime": "2020-06-04T17:55:19Z",
"items": [
{
"quantity": 1,
"cancelQuantity": 0,
"skuId": "f4f06b2b-f091-41b4-b18f-5c59a7414659",
"itemId": "96791310336"
},
{
"quantity": 1,
"cancelQuantity": 0,
"skuId": "94a3f3d0-676e-49ea-b07b-4ba32f7bfdd5",
"itemId": "96791320336"
}
],
"orderId": "177759770336",
"liveMode": false
}

Partially cancelling an order

If you're unable to fulfill part of the order, send a POST/fulfillments request that specifies the itemId and cancelQuantity for the items that you are cancelling:

cURL
cURL
curl --location --request POST 'https://api.digitalriver.com/fulfillments' \
--header 'Authorization: Bearer <API_key>' \
--header 'Content-Type: text/plain' \
--data-raw '{
"orderId": "177759770336",
"items": [
{
"itemId": "96791310336",
"cancelQuantity": 1
}
]
}'

A 201 Created response returns the cancelled quantity for the item:

{
"id": "ful_5b32ce12-2d42-494f-8e2a-ddcd12d1de10",
"createdTime": "2020-06-04T18:13:01Z",
"items": [
{
"quantity": 0,
"cancelQuantity": 1,
"skuId": "f4f06b2b-f091-41b4-b18f-5c59a7414659",
"itemId": "96791310336"
}
],
"orderId": "177759770336",
"liveMode": false
}

Completely fulfilling an order

When you're ready to completely fulfill the Order, you can submit the following request:

curl --location --request POST 'https://api.digitalriver.com/fulfillments' \
--header 'Authorization: <API_key>' \
--header 'Content-Type: text/plain' \
--data-raw '{
"orderId": "177759770336",
"items": [
{
"itemId": "96791310336",
"quantity": 1
},
{
"itemId": "96791320336",
"quantity": 1
}
]
}'

A successful request will generate an order.fulfilled event. If you again attempt to fulfill or cancel any part of the order, you'll receive the following 409 Conflict response:

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

Retrieving fulfillments by order identifier

At any time, you can return a list of Fulfillments associated with this Order by sending a GET /fulfillments request and using a query parameter to filter by orderId.

cURL
cURL
curl --location --request GET 'https://api.digitalriver.com/fulfillments?orderId=177759770336' \
--header 'Authorization: Bearer <API_key>
' \

Using fulfillment-related events

After you create a successful Fulfillment on all or part of an order, a fulfillment.created event is generated. If you specified a quantity, thereby informing Digital River you fulfilled items, we then create a Capture on all or part of the Charge. Conversely, if you told us that you cancelled items by specifying a cancelQuantity, we create a Cancel on all or part of the Charge.

More generally, Fulfillments trigger a series of events related to order charge captures and cancels that you can use when building your integration.