Order Create Details

Order Create

After you import the product catalog into the client’s e-commerce system, you can enable the order create business process. For this business process, the client will process the following items implemented via their e-commerce solution: 

  • The transaction performing payment authorization
  • The fraud check
  • Other client-specific transaction processing functions 

After processing these items, the client knows the customer and order are acceptable. The client then uses the Order Create API to submit the order to Digital River for fulfillment. For a digital product, this fulfillment information consists of a Digital River-hosted download URL that the client delivers to the customer who placed the order. The customer uses this URL to download the product they purchased. Sometimes products require a serial number or unlock code in addition to the download URL so the customer can install the product properly. In this case, the Order Create business process returns this information to the client and the client displays the information to the client on the customer service interface and also sends the information in an email notification to the customer.

The business process uses XML and HTTPS since the APIs are real-time in nature. Clients should consider coding in a timing feature so that, in the very rare case where the call to the Digital River servers takes over 10 seconds or so, they return a page to the customer that says they will send the information the customer requires to get the product they purchased later.

Business Process Specifics

Characteristic
Specification
Business Process Type
Real-Time
Communication Protocols
HTTPS
Data Formats Available
XML


Models

The following diagram shows an overview of the Order Create business process.

Multiple Order Processing

Multiple orders per request are not supported at this time.

Submitting Identical Order Twice

If the Client inadvertently submits the same order twice (that is, the same external order ID and line items), Digital River will accept the request and return the same information via the OrderCreate Response that it did in the previous order submission(s). If one or more of the line items has pending digital rights, Digital River will try to obtain the digital rights before sending the response.

Inactive Items

Occasionally products on the Digital River side are deactivated as part of the normal course of business activities with respect to product catalog maintenance. If a product in a Client's catalog is deactivated on the Digital River side, the return response will contain an error code.

Order Create Request XML Schema and XML Example

See the Order Create Schemas section for schema and XML examples.

Order Create Response XML Schema and Example

When Digital River receives a fulfillment request, Digital River provides an immediate response to this call. This response's XML format follows a specific XML schema provided in the Order Create Schemas section.

The following table shows the values for status return codes. There are two types of return codes:

  • Return code for the order fulfillment itself
  • Return code for each line item quantity unit in the order

For unsuccessful orders with multiple products, the line item order status allows the client to pinpoint the product in the order that caused the failure. Line items in pending status will be resubmitted every hour for up to 30 days.

Note:

The client is responsible for resubmitting any 202/503 status code combinations to verify order fulfillment status.

Order Status Codes
201 - Success: all line item units completely fulfilled
202 - Partial success: order was valid, but some line items could not currently be fulfilled
400 - Bad request: the server could not understand the request due to malformed syntax
401 - Unauthorized: see Error! Reference source not found.
409 - Unfulfillable: one or more the line items cannot be fulfilled. Details are provided in corresponding line item status codes (404)
500 - Temporary service outage: retry later (we could set a Retry-After header)
Line Item Status Codes
201 - Success: the unit will contain licenses, actualPrice, and downloadUrl
404 - Not Found: the requested product is permanently unavailable.
503 - Unavailable: not all of the licenses could be generated at this time, but some will become available in future. The fulfillment/status/code will be 202.

The following example shows a return response to the example order request provided earlier in the document. The earlier request contained two copies of the same product. This fulfillment response shows a license and unlock code for the first product and a pending digital rights response for the second product. 

Note:

Each line item quantity has its own fulfillment unit.

<rws:fulfillment
  uri="http://integration.digitalriver.com/integration/job/request/DRRWS/fulfillment/123/"
  orderUri="http://dealer.acme.com/order/12345A6/"
  xmlns:rws="http://integration.digitalriver.com/2005/10/RetailWebService"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://integration.digitalriver.com/2005/10/RetailWebService C:\projects\x-stream\resources\ws\xsd\integration\rws\fulfill.xsd ">
  <status>
    <code>202</code>
    <message/>
  </status>
  <units>
    <unit uri="http://digitalriver.com/drws/fu/452455" lineItemUri="http://dealer.acme.com/lineItem/1">
      <status>
        <code>200</code>
        <message>OK</message>
      </status>
      <actualPrice>
        <amount>23.56</amount>
        <currencyCode>USD</currencyCode>
      </actualPrice>
      <downloadUrl>ftp://foo/baz/bar.exe</downloadUrl>
      <licenses>
        <license uri="http://digitalriver.com/drws/lic/42">
          <type>serialNo</type>
          <value>1120348MB67198749756</value>
        </license>
        <license uri="http://digitalriver.com/drws/lic/523">
          <type>unlockCode</type>
          <value>1120348MB67198749756</value>
        </license>
      </licenses>
    </unit>
    <unit uri="http://digitalriver.com/drws/fu/45246" lineItemUri="http://dealer.acme.com/lineItem/1">
      <status>
        <code>503</code>
        <message>pending fulfillment </message>
      </status>
      <actualPrice/>
      <downloadUrl/>
      <licenses/>
    </unit>
  </units>
</rws:fulfillment>