Creating and updating an order

Learn the basics of creating and updating an Order

Submitting the request

To create an Order, simply assign the identifier of the Checkout to the checkoutId attribute in the body of a create Order 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"
}'

Analyzing the response

Unique identifier

A 201 Created response returns an Order object with a unique id.

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

Ship to values

In this case, the shipTo values are inherited from the Customer associated with the Order.

...
"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 PriceItem or AggregatePriceItem object in the items array is returned with a unique id that is used when creating and cancelling Fulfillments and processing Returns and Refunds.

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

...
"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": {
"subscriptionId": "123",
"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
}
}
],
...

Shipping options

In this example Order, one of the PriceItem 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 object.

...
"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",
...

State and fraud state

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

A 201 Created response will occasionally indicate the Order state is pending_payment or in_review . For this reason, you should wait until receiving an order.acceptedwebhook before creating a Fulfillment.

...
"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 represents an array of Charge objects and typically contains only one element. Each object represents the payment source (referenced by the sourceId), the amount of the total order charged to that source, and the state of the charge. 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. Additionally, the Charge is in a capturable state but has yet to be captured.

...
"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 your customer has made a request to have his or her 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,
...
}

Full order response

The following is the complete create Order response:

{
"id": "177452480336",
"createdTime": "2020-05-21T17:26:34Z",
"customerId": "987654321",
"currency": "USD",
"email": "jdoe@digitalriver.com",
"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"
},
"shipFrom": {
"address": {
"line1": "350 S 5th St",
"city": "Minneapolis",
"postalCode": "55415",
"state": "MN",
"country": "US"
}
},
"totalAmount": 177.67,
"subtotal": 172.5,
"totalFees": 0.0,
"totalTax": 5.17,
"totalDuty": 0.0,
"totalDiscount": 7.5,
"totalShipping": 5.0,
"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": {
"subscriptionId": "123",
"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
}
}
],
"shippingChoice": {
"amount": 5.0,
"description": "USPS: Priority (1 day delivery)",
"serviceLevel": "SG",
"taxAmount": 0.36
},
"updatedTime": "2020-05-21T17:26:34Z",
"locale": "de_DE",
"customerType": "business",
"paymentSessionId": "b14e97c6-6ed6-4c19-a093-eb5830c93818",
"sellingEntity": {
"id": "DR_INC-ENTITY",
"name": "Digital River Inc."
},
"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": [
{
"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"
}
],
"requestToBeForgotten": false,
"liveMode": false
}

For an existing customer with a saved payment method, you can create an Order in a single step:

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",
"locale": "en_US",
"browserIp": "111.111.111.111",
"items": [
{
"skuId": "08141946",
"price": 100.00
}
],
"chargeType": "merchant_initiated",
"customerType": "individual",
"purchaseLocation": {
"country": "US",
"state": "MN",
"postalCode": "55364"
},
"upstreamId": "7765374748"
}'