Orders

Learn more about the orders resource

Orders handle customers' purchases. When you create an order, you instruct Digital River, the authorized reseller, to send an authorization request to start the collection process.

The data of an order persist, acting as a permanent record of the sale, which Digital River is required to maintain for auditing purposes.

An order maintains an enduring record of when it was placed, a charge is created and captured, a refund is processed, and other key events in the order lifecycle occur. More specifically, an order persists:

• The total refunded, cancelled, and captured payment amounts

• A charge containing a payment source, an amount charged to that source, and the state of the charge

The following diagram depicts the relationship between an order and other resources in the Digital River APIs.

To ensure that your integration is functioning properly, you can create test orders using the information contained in the Testing Scenarios page.

The orders resource

In the following section, you'll find information on some of an order's attributes and how you might use them in downstream requests. For a complete list, refer to the Orders API reference documentation.

Unique identifier

An order contains a unique id. You can use this identifier when initiating physical fulfillments, cancelling shipments, capturing and cancelling payments, creating physical returns, handling third-party returns, and issuing refunds.

Order

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

Ship to values

An order's shipTo values are displayed on 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": "[e-mail]",
        "organization": "Digital River"
    },

Amounts, fees, and taxes

The total amount, fees, taxes, and other costs of the order are the same as those presented to customers when they confirm the purchase. You can retrieve these values and display them on the customer's order confirmation page.

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

Line items

Digital River assigns each of an order's items[] a unique id. You need this identifier when capturing and cancelling payments, handling third-party returns, and issuing refunds.

Depending on how you send product data in checkouts, each of an order's items[] also contains either a skuId or a productDetails object.

In addition, these items[] store detailed price, tax, and quantity information that you can display to customers on order confirmation and order detail pages.

For more information on subscriptionInfo, refer to the Subscription information page.

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

Tax invoices and credit memos

In most cases, Digital River populates an order's invoicePDFs and creditMemoPDFs with information that you can use to access and share tax invoices and credit memo files.

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

State and fraud state

For more information about an order's state and fraudState, refer to the Order lifecycle page.

Tax identifiers

Orders with applied tax identifiers contain an array of tax identifier objects.

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

Charges

An order's charges[] contains one or more elements, each representing a charge created from a primary or secondary payment source. Each charge contains a unique identifier, an amount, a state, and the identifier of the payment source used to create the charge.

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

An order's requestToBeForgotten indicates whether an order's data is scheduled for deletion. This is the only attribute (other than metadata) that can be modified in an update order request.

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