Purchase Plan Workflow

This topic describes the Purchase Plan workflow. When setting up a Purchase Plan workflow, follow these steps.

  1. Search for a private store (optional).
  2. Get an access token.
  3. Authorize the shopper into the private store.

Scenario assumptions

This purchase plan scenario assumes:

  • The site uses a public API key.
  • The site has multiple purchase plans to choose from, and the purchase plan ID and its corresponding target market ID are unknown. If you know the purchase plan ID and target market ID information, the search step is optional.
  • Only one access rule is configured for authorizing shoppers by email domain.
  • Shopper authentication is required to browse within a purchase plan. Authentication is a prerequisite if isAuthenticationRequiredToBrowse is set to true.

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 API. The example request searches for available private stores matching the email domain. The search matches criteria based on OR logic, so if multiple access rules are configured 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, searching by only the email domain finds the associated private store.

Request

GET https://api.digitalriver.com/v1/shoppers/me/purchase-plan/search?emailDomain=university.edu&apiKey=apiKey HTTP/1.1

Response

<purchaseplans>
   <purchaseplan>
      <id>11858700</id>
      <isauthenticationrequiredtobrowse>true</isauthenticationrequiredtobrowse>
      <purchaseplanname>Student Discounts</purchaseplanname>
      <branddisplayname/>
      <brandlogoimage/>
      <targetmarketid>35100</targetmarketid>
      <targetmarketname>Students</targetmarketname>
   </purchaseplan>
   <totalresults>1</totalresults>
</purchaseplans>

Step 2. Get an Access Token

Send a GET request to the Shoppers Token API under Shopper APIs. The following request passes in a public API key and overrides the response format as xml.

Request

GET https://api.digitalriver.com/v1/shoppers/token?apiKey=yourAPIkey&format=xml HTTP/1.1

Response

<token>
   <access_token>96c44081d5ee98a7545ede88de966f0f371112b939b503219575572b5054be5b52b...</access_token>
   <token_type>bearer</token_type>
   <expires_in>86397</expires_in>
   <refresh_token>96c44081d5ee98a7545ede88de966f0f371112b939b503219575572b5054be5b8f5...</refresh_token>
</token>

Step 3. Authorize the Shopper into the Private Store

Send a POST request with the access rule criteria in the payload to the Purchase Plan Authorize API. You must pass the private store id, targetMarketId, and emailDomain access rule in the request body.

Request

POST https://api.digitalriver.com/v1/shoppers/me/purchase-plan/authorize HTTP/1.1

Payload

<purchasePlanAuthorize>
    <id>11858700</id>
    <targetMarketId>35100</targetMarketId>
    <emailDomain>university.edu</emailDomain>
</purchasePlanAuthorize>

Response

The service returns an empty document with an HTTP Status 204.

HTTP/1.1 204 No Content

If the request was successful, the shopper can browse and purchase products from the purchase plan on the private store. If the private store provides an overall discount for products in the private store, the Products API reflects discounted prices, as well as any associated offers. The Carts API also reflects discount prices. If the request was unsuccessful, an error message indicates the issue.

Continue the Workflow

Subsequent calls in the workflow could include:

  1. Add a product to a cart.
  2. Redirect a shopper to the Checkout page.