User management

Learn how to manage users.

User Management is a comprehensive service designed to assist third-party applications in efficiently handling user-related operations. This service supports user activation, password resets, subscription management, and order handling tasks, offering a standard interface with user-based authentication. It ensures secure and seamless management of user information hosted by Digital River.

User management details

The table below lists the various user management tasks that third-party applications can perform using specific request and response types. This collection of operations ensures seamless user management, from activation and password resets to subscription and order handling.

Task	Request Type	Response Type
Activate a user	ActivateShopperRequest	ActivateShopperResponse
Inactivate a user	InactivateShopperRequest	InactivateShopperResponse
Reset user password	ResetShopperPasswordRequest	ResetShopperPasswordRequest
Retrieve user information	GetShopperRequest	GetShopperResponse
Add/modify users, including updating the user's default billing method	AddUpdateShopperRequest	AddUpdateShopperResponse
Cancel a user's subscription	CancelSubscriptionRequest	CancelSubscriptionResponse
Activate a user's subscription	ActivateSubscriptionRequest	ActivateSubscriptionResponse
Modify a subscription's renewal date	ModifyRenewalDateRequest	ModifyRenewalDateResponse
Modify a subscription's renewal mechanism (manual or auto)	ModifyAutoRenewalRequest	ModifyAutoRenewalResponse
Search for a user's orders and get the order details	SearchOrderRequest	SearchOrderResponse
Cancel a user's order	CancelOrderRequest	CancelOrderResponse
Return a user's order	ReturnOrderRequest	ReturnOrderResponse
Add or modify extended attributes on a user's order and line items	UpdateOrderAttributesRequest	UpdateOrderAttributesResponse

All tasks mentioned above can use user-based basic authentication. You can configure this authentication per client integration. All the complex types mentioned above inherit CommonRequest and CommonResponse.

Activate a user's subscription

When you activate a user's subscription, you must meet the necessary validations to enable the subscription effectively. This process requires specific information about the user and their subscription details. It involves multiple checks to confirm the validity and ownership of the subscription, the associated product, and the activation key. Here, we outline the steps and validation tasks necessary for successful subscription activation and handling potential errors that may arise during the process.

To activate a subscription, you must send an ActivateSubscriptionRequest to the relevant endpoint. This request must include all necessary details, such as the user ID, subscription ID, product information, and activation date.

Here is a sample ActivateSubscriptionRequest:

Activate subscription request example

{
	"ActivateSubscriptionRequest": {
		"shopperKey": {
			"userID": "26593336708",
			"siteID": "tmamer"
		},
		"SubscriptionID": "4343240414",
		"subscriptionProductKey": {
			"productID": "55551800",
			"companyID": "tmamer",
			"externalReferenceID": ""
		},
		"activationDate": "2009-02-03",
		"renewalDate": "2009-08-08",
		"subscriptionKey": {
			"subscriptionID": "463301709"
		}
	}
}

Remember to verify all validation tasks for successful subscription activation to avoid errors. Refer to the validation table for specific requirements.

There are restrictions for an ActivateSubscriptionRequest. When sending an ActivateSubscriptionRequest, the request does not verify factors such as payment type and auto/manual. The following table lists the validations that occur during an ActivateSubscriptionRequest.

Validation Task	Error Information
The user identified in the shopperKey element is valid	Error Code: 200 Message: Shopper Not Found
The subscription identified in the 'SubscriptionID` element is valid	Error Code: 710 Message: Subscription order [888888] pending activation was not found Details: Where the <SubscriptionID> element passes the 888888 value.
The specified Subscription belongs to the given user	Error Code: 720 Message: Subscription order [888888] does not belong to shopper [loginID =12345, externalReferenceID = 54321] Details: Where the<SubscriptionID> element passes the 888888 value. The values 12345 and 54321 are the Digital River loginID and externalReferenceID for the shopper.
The specified Subscription contains a given product	Error Code: 730 Message: No subscription products found for the order [888888] Details: Where888888 is the value passed in the <subscriptionProductKey> element
The product identified in the `' element is valid	Error Code: 730 Message: No subscription products found for the order [productID=22222externalReferenceID= 33333companyID=44444locale=55555] Details: Where <subscriptionProductKey> element provides the values22222,33333,44444,55555`.
The activation key supplied in the <activatioKey> element is valid for the given Subscription	Error Code: 750 Message: Activation Key [activationKey=111] for provided productKey [productID=22222externalReferenceID= 33333companyID=44444locale=55555] was not found Details: Where 111 is the activation key supplied in the <acivtionKey> element and 22222, 33333, 44444, 55555 are the values provided in the element
The activation date supplied in the <activationDate> element is valid	Error Code: Not applicable Message: Not applicable Details: If invalid, the activation date will be set to the current date
The activation key supplied in the <activationKey> element has not previously been activated	Error Code: 770 Message: The subscription for the provided Activation Key [activationKey=111] has already been activated Details: Where 111 is the <activationKey> activation key supplied in the element
The subscription line item has not already been refunded	Error Code: 780 Message: Order [888888] has been refunded Details: Where 888888 is the value passed in the <SubscriptionID> element
The subscription line item has not already been cancelled	Error Code: 790 Message: Order [888888] was cancelled Details: Where 888888 is the value passed in the <SubscriptionID> element
Your subscription <SubscriptionID> was renewed on renewal date which is before so your message cannot be processed*	Error Code: 851 Message: Requested renewal date is before the subscription activation date Details: Not applicable
Nothing invalid	Error Code: 0 Message: Your request was carried out successfully. Details: Not applicable

Cancel a subscription request

You must provide specific details about the subscription and the user to cancel a subscription request. The process involves constructing a CancelSubscriptionRequest object with the required elements and sending it to the appropriate endpoint. This section will guide you through the steps necessary to cancel a subscription successfully.

To cancel a subscription request, follow these steps:

1. Construct a CancelSubscriptionRequest object with the necessary details:

   • shopperKey including userID and siteID.

   • SubscriptionID for the subscription you want to cancel.

   • subscriptionProductKey with productID, companyID, and externalReferenceID.

   • Set suppressCancelNotification as needed.

   • Provide subscriptionKey with subscriptionID.

   • Send the request using the appropriate endpoint.

2. Here is a sample CancelSubscriptionRequest:

Cancel subscription request example

{
	"CancelSubscriptionRequest": {
		"shopperKey": {
			"userID": "26593336708",
			"siteID": "tmamer"
		},
		"SubscriptionID": "4343240414",
		"subscriptionProductKey": {
			"productID": "55551800",
			"companyID": "tmamer",
			"externalReferenceID": ""
		},
		"suppressCancelNotification": "false",
		"subscriptionKey": {
			"subscriptionID": "463301709"
		}
	}

Modify auto-renewal request

Modifying an auto-renewal request allows you to change the settings related to a subscription's automatic renewal. It can include switching between manual and automatic renewal, updating the renewal date, or changing other relevant details. The following section outlines the steps to successfully modify an auto-renewal request, ensuring that your subscription preferences are up-to-date and accurate.

To modify an auto-renewal request, follow these steps:

1. Construct a ModifyAutoRenewalRequest object with the necessary details:

   • shopperKey including userID and siteID.

   • SubscriptionID for the subscription you want to modify.

   • subscriptionProductKey with productID, companyID, and externalReferenceID.

   • Provide the activationKey.

   • Set the autoRenewalAction to either "Manual" or "Auto".

   • Specify the autoRenewalDate in the YYYY-MM-DD format.

   • Provide the subscriptionKey with subscriptionID.

2. Send the request using the appropriate endpoint.

Here is a sample ModifyAutoRenewalRequest:

Modify auto-renewal request example

{
	"ModifyAutoRenewalRequest": {
		"shopperKey": {
			"userID": "26593336708",
			"siteID": "tmamer"
		},
		"SubscriptionID": "4343240414",
		"subscriptionProductKey": {
			"productID": "55551800",
			"companyID": "tmamer",
			"externalReferenceID": ""
		},
		"activationKey": "22222",
		"autoRenewalAction": "Manual",
		"autoRenewalDate": "2009-08-08",
		"subscriptionKey": {
			"subscriptionID": "463301709"
		}
	}
}

Suspending subscriptions

Suspending a subscription temporarily halts the services and products associated with that subscription without completely canceling it. This function allows users to pause their subscription for a specific period or indefinitely. The process involves generating a unique suspension key and setting start and end dates for the suspension, with options for immediate suspension and indefinite end dates. Below, we outline the necessary steps and requirements for successfully suspending a subscription and handling any potential errors that may arise during the process.

To suspend a subscription, follow these steps:

1. Ensure the system generates a unique suspension key for the subscription.

2. Specify the start and end dates for the suspension in the YYYY:mm:ddTHH:mm:ssZ format.

   • If you want the suspension to start immediately, omit the start date.

   • To make the suspension's end date indefinite, set the noEndDate value to true.

3. Specify the type of suspension you want to create. Do not provide both a suspension end date and no suspension date without a suspension type, as this will result in an error.

4. When modifying an existing suspension date, supply the subscription key, suspension type, and new suspension date. To begin the suspension immediately, use the current date. Set noEndDate to true to make the suspension indefinite.

To end an existing or future suspension, you must supply the subscription key, suspension type, and the current date in the End Date field. This action removes the suspension.

The following image shows the process flow for modifying a suspension.

Modifying a suspension

User management schemas

The user management schema is a structured framework that defines the organization, attributes, and relationships of user data within a system. It typically includes versions outlining various components and configurations, essential for integration and effective user management. The table below lists the versions available:

Version	Scheme Components Table	Raw Schema	Sample XML
26 (Current	View	View	Not available
25	View	View	Not available
24	View	View	Not available

These versions help understand and manage how user-related data is handled, ensuring consistency and compliance across different system integrations.