External Reference ID

An external reference ID (externalReferenceId) is a unique identifier that references a shopper or product on a remote system owned by a company. You can use an external reference ID to reference either a shopper or a product, depending on the context.

For more information, see External Reference ID under Classic APIs.

Using an External Reference ID for a Shopper

When you create a shopper, you can specify the external reference ID. You can also update a shopper using the POST shoppers/me API. 

Specifying an External Reference ID when Creating and Getting a Shopper

The Shopper properties in the request body for a POST shoppers API request (where the client maintains the login credentials) includes an externalReferenceId as shown in line 4:

1.  <shopper>
2.   <firstname>John</firstname>
3.      <lastname>Johnson</lastname>
4.      <externalreferenceid>abc123</externalreferenceid>
5.      <emailaddress>jjohnson@myCompany.com</emailaddress>
6.      <locale>en_US</locale>
7.      <currency>USD</currency>
8.  </shopper>

When you get the current shopper using the GET shoppers/me API, you can use the expand query parameter to get the shopper's external reference ID. Note that the external reference ID field is not returned by default. For more information about getting and creating shoppers, refer to the Shoppers API. 

Create a Full Access Token using External Reference ID

For the Client Credentials confidential flow only, you can create a full access token on behalf of a shopper by passing in the external_reference_id form parameter in the request body (payload):


For more information, see POST oauth20/token (Client Credentials) in the Token API.

Using an External Reference ID for a Product

A product ID is assigned when someone creates a product in Global Commerce. Some companies have their own internal identifiers for their products, and that external reference ID may or may not match the product ID in Global Commerce. You can search for and add products to a cart based on either the external reference ID or product ID as you prefer. The following examples demonstrate various ways you can use the external reference ID with the product-related Digital River Shopper APIs.

Retrieve Products from the Default Catalog, Limited by Specific External Reference IDs

The following request gets products with an externalReferenceId of 30, 35, and 40; respectively.

GET shoppers/me/products?externalReferenceId=30,35,40

Add a Product to a Shopping Cart using External Reference ID

The following request example adds a product to a cart using the externalReferenceId query parameter.

POST shoppers/me/carts/active/line-items?externalReferenceId=0123456789


If you do not provide a company ID, the company ID defaults to the one associated with the API key.

Add a product by external reference ID to the shopping cart and redirect to the storefront page

In a typical anonymous shopper workflow, you can add products to a cart by external reference ID, making a single POST call with a payload to the Web Checkout API. The following payload (request entity) adds a product with the externalReferenceId of 123456789, with a quantity of 2, to a cart.

1.  {
2.    "webCheckout": {
3.      "cart": {
4.        "lineItems": {
5.          "lineItem": {
6.            "quantity": "2",
7.            "product": {
8.              "externalReferenceId": "123456789"
9.             }
10.              ... more closing curly braces ...

A successful request with this particular API results in a 302 redirect to a Digital River-hosted guest checkout page. For more information, see POST shoppers/me/carts/active/web-checkout.