Common use cases

Create a customer

This topic describes how to create a customer account record. Creating a customer account is necessary for an anonymous customer that does not yet have an account created for a site, and a site does not provide a guest checkout. In this instance, the site requires a customer to have an account to purchase a product. Creating a customer is not necessary for an anonymous customer who is only browsing products.

You can make this request without an access token by passing in your API key as a query parameter. You can also send this request with either a valid anonymous or authenticated customer token.

Send a POST shoppers request with the customer's information in the request payload.

The following example shows a request with an access token:

Request sample with an access token
Request sample with an access token
POST https://api.digitalriver.com/v1/shoppers

The following example shows a request without an access token, passing in your API key:

Request sample without an access token
Request sample without an access token
POST https://api.digitalriver.com/v1/shoppers?apiKey=your_api_key

The contents required for the payload depends on who maintains the master record for the customer's username and password information. The base customer account information includes the customer's name and email address. The following list displays the minimum Shoppers resource fields required to create a customer record:

  • username

  • password (base64 encoded)

  • emailAddress

  • externalReferenceId

  • firstName

  • lastName

If Digital River maintains the master record for the customer login credentials, the request body must contain the username and password. The customer's password must be base64 encoded.

Best Practices: Explicitly set the locale and currency for a customer at the start of a session.

Request body sample for Digital River-maintained master record
Request body sample for Digital River-maintained master record
{
"shopper": {
"username": "myShopper@myCompany.com",
"password": "cFGzc3dvcmQ=",
"firstName": "John",
"lastName": "Johnson",
"emailAddress": "jjohnson@myCompany.com",
"locale": "en_US",
"currency": "USD"
}
}

If the client (that is, customer) maintains the master record for the customer login credentials, the request body must contain the externalReferenceId.

Request body sample for the client-maintained master record
Request body sample for the client-maintained master record
{
"shopper": {
"username": "myShopper@myCompany.com",
"password": "cFGzc3dvcmQ=",
"firstName": "John",
"lastName": "Johnson",
"emailAddress": "jjohnson@myCompany.com",
"locale": "en_US",
"currency": "USD"
}
}

The response returned from the server is an HTTP Status 201 Created.

Now that the base customer record has been created, you can get an authenticated customer token and call the GET shoppers/me/account method to allow the customer to log in and configure his or her account information. The account information associated with a customer includes shipping address, billing address, and payment options.

Apply a coupon code

You can apply a coupon code to an active shopping cart to encourage sales in your stores by providing discounts on products or shipping costs.

During the checkout process, a customer manually enters a coupon code in your storefront and clicks the Apply button. The API applies the discount associated with the POP (Point-of-Promotion) offer to the cart. The call returns the contents of the cart with the adjusted pricing information.

How to apply a promo code

Send a POST shoppers/me/carts/active request to the Carts resource with the required promoCode query parameter. The request must include a valid anonymous or authenticated customer token. There is no payload associated with this request; the request body is empty.

The request in the following example applies a promotional code value of wb32xjtam. The ID of the cart is 1234567890.

Note: A successful request returns a status code of 200 in the response header. An unsuccessful request returns an error code in the response.

Request sample
Response sample
Request sample
POST https://api.digitalriver.com/v1/shoppers/me/carts/active?promoCode=wb32xjtam
Response sample
{
"cart": {
"id": "1234567890",
"lineitems": {
"lineitem": {
"id": "12765711619",
"quantity": "1",
"product": {
"displayname": "Displayable Product Name",
"thumbnailimage": "http://drh1.img.digitalriver.com/DRHM/Storefront/images\n/product/thumbnail/small-product-image.jpg",
"_uri": "https://api.digitalriver.com/v1/shoppers/me/products/232054400"
},
"pricing": {
"listprice": {
"_currency": "USD",
"__text": "24.95"
},
"listpricewithquantity": {
"_currency": "USD",
"__text": "24.95"
},
"salepricewithquantity": {
"_currency": "USD",
"__text": "14.95"
},
"formattedlistprice": "$24.95",
"formattedlistpricewithquantity": "$24.95",
"formattedsalepricewithquantity": "$14.95"
},
"_uri": "https://api.digitalriver.com/v1/shoppers/me/carts/active /line-items/12765711619"
},
"_uri": "https://api.digitalriver.com/v1/shoppers/me/carts/active /line-items"
},
"billingaddress": {
"shippingaddress": {
"payment": {
"name": "Visa",
"displayablenumber": "************1111",
"expirationyear": "2017"
},
"shippingmethod": {
"code": "142400",
"description": "USPS - Priority Mail"
},
"shippingoptions": {
"pricing": {
"subtotal": {
"_currency": "USD",
"__text": "24.95"
},
"discount": {
"_currency": "USD",
"__text": "10.00"
},
"shippingandhandling": {
"_currency": "USD",
"__text": "0.00"
},
"tax": {
"_currency": "USD",
"__text": "0.00"
},
"ordertotal": {
"_currency": "USD",
"__text": "14.95"
},
"formattedsubtotal": "$24.95",
"formatteddiscount": "$10.00",
"formattedshippingandhandling": "$0.00",
"formattedtax": "$0.00",
"formattedordertotal": "$14.95"
},
"_uri": "https://api.digitalriver.com/v1/shoppers/me/shipping-options"
},
"_uri": "https://api.digitalriver.com/v1/shoppers/me/carts/active/shipping-address"
},
"_uri": "https://api.digitalriver.com/v1/shoppers/me/carts/active/billing-address"
},
"_uri": "https://api.digitalriver.com/v1/shoppers/me/carts/active"
}
}
{
"cart": {
"id": "1234567890",
"lineitems": {
"lineitem": {
"id": "12765711619",
"quantity": "1",
"product": {
"displayname": "Displayable Product Name",
"thumbnailimage": "http://drh1.img.digitalriver.com/DRHM/Storefront/images\n/product/thumbnail/small-product-image.jpg",
"_uri": "https://api.digitalriver.com/v1/shoppers/me/products/232054400"
},
"pricing": {
"listprice": {
"_currency": "USD",
"__text": "24.95"
},
"listpricewithquantity": {
"_currency": "USD",
"__text": "24.95"
},
"salepricewithquantity": {
"_currency": "USD",
"__text": "14.95"
},
"formattedlistprice": "$24.95",
"formattedlistpricewithquantity": "$24.95",
"formattedsalepricewithquantity": "$14.95"
},
"_uri": "https://api.digitalriver.com/v1/shoppers/me/carts/active /line-items/12765711619"
},
"_uri": "https://api.digitalriver.com/v1/shoppers/me/carts/active /line-items"
},
"billingaddress": {
"shippingaddress": {
"payment": {
"name": "Visa",
"displayablenumber": "************1111",
"expirationyear": "2017"
},
"shippingmethod": {
"code": "142400",
"description": "USPS - Priority Mail"
},
"shippingoptions": {
"pricing": {
"subtotal": {
"_currency": "USD",
"__text": "24.95"
},
"discount": {
"_currency": "USD",
"__text": "10.00"
},
"shippingandhandling": {
"_currency": "USD",
"__text": "0.00"
},
"tax": {
"_currency": "USD",
"__text": "0.00"
},
"ordertotal": {
"_currency": "USD",
"__text": "14.95"
},
"formattedsubtotal": "$24.95",
"formatteddiscount": "$10.00",
"formattedshippingandhandling": "$0.00",
"formattedtax": "$0.00",
"formattedordertotal": "$14.95"
},
"_uri": "https://api.digitalriver.com/v1/shoppers/me/shipping-options"
},
"_uri": "https://api.digitalriver.com/v1/shoppers/me/carts/active/shipping-address"
},
"_uri": "https://api.digitalriver.com/v1/shoppers/me/carts/active/billing-address"
},
"_uri": "https://api.digitalriver.com/v1/shoppers/me/carts/active"
}
}

Typically, the next steps after applying a coupon code are either re-directing the customer to the Digital River hosted checkout to complete the purchase process or submitting the cart and creating an order to complete the checkout process.

Private Store workflow

This topic describes the private store workflow. This scenario assumes:

  • The site uses a public API key.

  • The site has multiple private stores to choose from, and the private store ID and its corresponding target market ID are unknown. If you know the private store ID and target market ID information, the search step is optional.

  • There is only one access rule configured for authorizing customer by email domain.

  • Customer authentication is required to browse within a purchase plan. Authentication is a prerequisite if isAuthenticationRequiredToBrowse is set to true.

How to associate a customer with a private store

  1. Optional. Search for a private store.

  2. Get an access token.

  3. Authorize a customer into the private store.

  4. Optional. Add a product to a cart.

  5. Optional. Redirect a customer to the Checkout page.

Step 1. Search for a private store

Send a GET request with the access rules search criteria for the private store to the Purchase Plan Search. Search for available private stores that match the email domain. The search matches criteria based on OR logic. If you configure multiple access rules for a private store, the search can locate private stores based on one valid configured access rule. For instance, if a private store restricts access by both email domain and IP address, you can find the private store by searching for the email domain.

Request sample
Response sample
Request sample
GET https://api.digitalriver.com/v1/shoppers/me/purchase-plan/search?
emailDomain=university.edu&apiKey=apiKey
Response sample
{
"purchaseplans": {
"purchaseplan": {
"id": "11858700",
"isauthenticationrequiredtobrowse": "true",
"purchaseplanname": "Student Discounts",
"branddisplayname": "",
"brandlogoimage": "",
"targetmarketid": "35100",
"targetmarketname": "Students"
},
"totalresults": "1"
}
}
{
"purchaseplans": {
"purchaseplan": {
"id": "11858700",
"isauthenticationrequiredtobrowse": "true",
"purchaseplanname": "Student Discounts",
"branddisplayname": "",
"brandlogoimage": "",
"targetmarketid": "35100",
"targetmarketname": "Students"
},
"totalresults": "1"
}
}

Step 2. Get an access token

Send a GET request to the Shoppers Token resource. The following request sends a public API key and specifies the JSON format.

Request sample
Response sample
Request sample
GET https://api.digitalriver.com/v1/shoppers/token?apiKey=yourAPIkey&format=json
Response sample
{
"token": {
"access_token": "96c44081d5ee98a7545ede88de966f0f371112b939b503219575572b5054be5b52b...",
"token_type": "bearer",
"expires_in": "86397",
"refresh_token": "96c44081d5ee98a7545ede88de966f0f371112b939b503219575572b5054be5b8f5..."
}
}
{
"token": {
"access_token": "96c44081d5ee98a7545ede88de966f0f371112b939b503219575572b5054be5b52b...",
"token_type": "bearer",
"expires_in": "86397",
"refresh_token": "96c44081d5ee98a7545ede88de966f0f371112b939b503219575572b5054be5b8f5..."
}
}

Step 3. Authorize a customer into the private store

Send a POST request with the access rule criteria in the payload to the Purchase Plan Authorize resource. The response returns an empty document with an HTTP Status 204. When the request is successful, the customer can browse and purchase products from the private store. If the private store provides an overall discount for products, the Products resource reflects discounted prices, as well as any associated offers. The Cart resource also reflects discount prices. When the request is unsuccessful, an error message indicates the issue.

Request sample
Request body sample
Response sample
Request sample
POST https://api.digitalriver.com/v1/shoppers/me/purchase-plan/authorize
Request body sample
{
"purchasePlanAuthorize": {
"id": "11858700",
"targetMarketId": "35100",
"emailDomain": "university.edu"
}
}
{
"purchasePlanAuthorize": {
"id": "11858700",
"targetMarketId": "35100",
"emailDomain": "university.edu"
}
}
Response sample
HTTP/1.1 204 No Content

Subsequent calls in the workflow could include:

  1. Add a product to a cart.

  2. Redirect a customer to the Checkout page.

Single-click checkout

Use Single-click Checkout to purchase a product on behalf of a customer during an authenticated customer session. This resource bypasses calling the Apply Shopper and Submit Cart resources separately and instantly purchases a single product. A typical example of a product purchased via this API is an auto-renewal, such as a subscription.

The product-direct purchase API performs the following actions with one Shopper API call:

Prerequisite

The request requires a valid authenticated customer token.

  1. Adds a product to the cart.

  2. Applies the default customer address to the cart.

  3. Applies the default payment option to the cart.

  4. Submits the cart.

  5. Creates an order.

Send a Product request with the specific product ID for the product that the customer wants to purchase. The following request sample purchases a product with a product ID of 291233200.

The response header contains a Location header, as shown on line 4, to the order created for the transaction. The ID of the order is 1234567890. The request and response bodies are empty.

Request sample
Response sample
Request sample
POST https://api.digitalriver.com/v1/shoppers/me/products/291233200/purchase
Response sample
HTTP/1.1 201 Created
Server: Apache
X-Server-Name: server.xyz.digitalriverws.net
Location: https://api.digitalriver.com/shoppers/me/orders/1234567890
Content-Length: 0
Accept-Ranges: bytes
Date: Fri, 17 Jan 2014 16:46:30 GMT
Age: 0
Access-Control-Allow-Origin: *
HTTP/1.1 201 Created
Server: Apache
X-Server-Name: server.xyz.digitalriverws.net
Location: https://api.digitalriver.com/shoppers/me/orders/1234567890
Content-Length: 0
Accept-Ranges: bytes
Date: Fri, 17 Jan 2014 16:46:30 GMT
Age: 0
Access-Control-Allow-Origin: *

No further calls are required. If applicable, you can make follow-up calls to get the order by its ID or the order history for the customer.