Processing orders

Learn the basics of creating and updating an Order and how to use the response from the Orders API.

The preferred approach to creating an Order is to simply provide the checkout identifier in a POST/orders request. When updating an Order, you are primarily limited to updating a customer's right to have the order forgotten.

Creating an order with the checkout identifier

To create an Order, assign the identifier of a Checkout to the checkoutId parameter in the body of a POST/orders request:

cURL
cURL
curl --location --request POST 'https://api.digitalriver.com/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
--header 'Content-Type: text/plain' \
--data-raw '{
"checkoutId": "177452470336"
}'

Using the order response

The following looks at some of the key attributes returned in a typical POST/orders response and how they can be used.

Unique identifier

A 201 Created response returns an Order object with a unique id. You'll use this identifier when handling webhook events, fulfilling items, and issuing refunds.

JSON
JSON
{
"id": "177452480336",
...

Ship to values

In this case, the shipTo values are inherited from the Customer associated with the Order during the checkout process. These are the values that are displayed on any invoices and credit memos.

...
"customerId": "987654321",
...
"shipTo": {
"address": {
"line1": "10380 Bren Rd W",
"line2": "string",
"city": "Minnetonka",
"postalCode": "55129",
"state": "MN",
"country": "US"
},
"name": "Jane Doe",
"phone": "952-111-1111",
"email": "jdoe@digitalriver.com",
"organization": "Digital River"
},

Amounts, fees, and taxes

The total amount, fees, taxes, and other costs are the same as those presented to the customer prior to placing the order.

...
"totalAmount": 177.67,
"subtotal": 172.5,
"totalFees": 0.0,
"totalTax": 5.17,
"totalDuty": 0.0,
"totalDiscount": 7.5,
"totalShipping": 5.0,
...

Line items

Each element in the items array is returned with a unique id . You'll use this identifier when fulfilling and cancelling items, processing returns, and issuing refunds.

If the item is a subscription purchase, then the subscriptionInfo hash table may include the subscriptionId that you optionally provided Digital River at the time of acquisition. Subscriptions can also return the billingAgreeementId that we generate. You should persist these values and include them when renewing the subscription.

The response also contains a state value that indicates where each line item is in its lifecycle.

...
"items": [
{
"id": "96415480336",
"skuId": "08141946",
"amount": 100.0,
"quantity": 1,
"state": "created",
"stateTransitions": {
"created": "2020-05-21T17:26:34Z"
},
"tax": {
"rate": 0.0,
"amount": 0.0
},
"subscriptionInfo": {
"billingAgreementId": "cfeba2ac-d532-49e4-99f4-7a433507facf",
"terms": "Insert terms here",
"autoRenewal": true,
"freeTrial": false
}
},
{
"id": "96415490336",
"skuId": "05081978",
"amount": 67.5,
"quantity": 1,
"discount": {
"percentOff": 10.0,
"quantity": 1
},
"state": "created",
"stateTransitions": {
"created": "2020-05-21T17:26:34Z"
},
"tax": {
"rate": 0.07125,
"amount": 4.81
}
}
],
...

For some orders, Digital River automatically generates invoice and credit memo PDF files. In an order response, each element of the invoicePDFs and the creditMemoPDFs array contains the id and url of that file. If an order's invoice or credit memo is not yet generated, neither invoicePDFs or creditMemoPDFs is returned by the Orders API response.

The file url can only be accessed with your confidential (secret) API key. You should not share this link with customers since they won't be able to access its content.

...
"invoicePDFs": [
{
"url": "https://api.digitalriver.com/files/23c7e1a5-25e4-41a9-b935-eda98dfa238b/content",
"id": "23c7e1a5-25e4-41a9-b935-eda98dfa238b"
}
],
"creditMemoPDFs": [
{
"url": "https://api.digitalriver.com/files/5cec4a32-853f-485a-90a0-15ea0a614355/content",
"id": "5cec4a32-853f-485a-90a0-15ea0a614355"
}
],
...

You can be notified when these files are created by subscribing to order.credit_memo.created and order.invoice.created events. The data.object of these events is the Order that contains the file(s).

Upon receipt of the event, retrieve the id of the invoice or credit memo pdf that you want to share. You should then use that value to set the fileId parameter in a create file link request. The response returns a publicly accessible url that can be used to download the file. You can share that url with your customers by email, through their account management portal, or another method of your choice.

Shipping options

In this example Order, one of the objects in the items array represents a physical product. As a result, the customer was required to specify shipping options at the time of checkout. These values, including the computed taxAmount, are returned in the shippingChoice hash table.

...
"shippingChoice": {
"amount": 5.0,
"description": "USPS: Priority (1 day delivery)",
"serviceLevel": "SG",
"taxAmount": 0.36
},
...

Localization

The locale value is used to localize customer invoices and credit memos.

...
"locale": "de_DE",
...

Tax identifiers

For orders with applied tax identifiers, an array of tax identifier objects is returned in the response.

JSON
JSON
...
"taxIdentifiers": [{
"id": "a6809a63-e6a9-4016-abbc-f33d19fccb5b",
"customerId": "5774321009",
"type": "uk",
"value": "GB000283536",
"state": "verified",
"stateTransitions":
{"pending": "2020-05-13T11:00:00.000Z", "verified": "2020-05-15T16:00:00.000Z"},
"verified_name": "Descon Ltd",
"verified_address": "Design House, 18b Tromode, Isle of Man",
"createdTime": "2020-08-01T02:25:53Z",
"updatedTime": "2020-08-01T05:47:21Z"
}],
...

State and fraud state

The response also contains state and fraudState values that indicate where the Order object is in its lifecycle.

A 201 Created response occasionally indicates the Order state is pending_payment or in_review. For this reason, you should wait until receiving an order.acceptedwebhook before fulfilling items in the order.

...
"state": "accepted",
"stateTransitions": {
"submitted": "2020-05-21T17:26:37Z",
"created": "2020-05-21T17:26:34Z",
"accepted": "2020-05-21T17:26:37Z"
},
"fraudState": "passed",
"fraudStateTransitions": {
"passed": "2020-05-21T17:26:37Z"
},
...

Charges

The charges attribute contains an array of Charge objects. The array typically contains only one element, representing the charge created on the order's primary source. Each Charge object contains a payment source (referenced by the source identifier), the amount of the total order charged to that source, and the state of the charge. As the charge transitions from one state to another, we emit events that your integration can respond to.

In this example, since there is only one Charge object in the array, the totalAmount of the Order and the amount of the Charge are the same.

...
"charges": [
{
"id": "d3a02b03-1378-431e-81a5-9cb6dd54d90b",
"createdTime": "2020-05-21T17:26:37Z",
"currency": "USD",
"amount": 177.67,
"state": "capturable",
"captured": false,
"refunded": false,
"sourceId": "deabb3a4-14e4-4702-a13b-ddaac23277d3"
}
],
...

Request to be forgotten

Whether or not customers have made a request to have the order data deleted is reflected in the requestToBeForgotten attribute. This is the only attribute (other than metadata) that can be modified in an update Order request.

...
"requestToBeForgotten": false,
...
}

Reusing the checkout identifier

If you attempt to pass a checkoutId in a POST/orders request, and that Checkout has already been consumed by a different POST/orders request, you'll get back a response with a 404 Not Found status:

JSON
JSON
{
"type": "not_found",
"errors": [
{
"code": "not_found",
"parameter": "orderId",
"message": "Order 180139250336 not found"
}
]
}

Using the customer identifier

Although not the preferred approach, you can also create an Order for an existing customer who has an attached payment source:

cURL
cURL
curl --location --request POST 'https://api.digitalriver.com/orders' \
--header 'Authorization: Bearer <API_key>' \
--header 'Content-Type: text/plain' \
--data-raw '{
"customerId": "03091796",
"currency": "USD",
...
"items": [
{
"skuId": "08141946",
"price": 100.00
}
],
...
}'

Updating a request to be forgotten

In an update Order request, you can only update the requestToBeForgotten attribute as well as any metadata associated with the order.

To update an order, submit a POST/orders/{id} request and pass in the order identifier as a path parameter. If the customer has requested that the order be forgotten, then set the requestToBeForgotten parameter to true.