Commerce Foundation UserProfile CommerceUpdate
This Commerce Server 2009 operation is used to update an existing user profile object and any of its relationships. You can use this operation to create new credit card and address records, as well as associate existing address and credit card records to the user.
Syntax
var updateUserProfile = new CommerceUpdate<CommerceEntity>("UserProfile");
Parameters
At a minimum, the caller must specify the ID of the user profile to retrieve. This operation supports the CommerceModelSearch criteria mechanism only.
Parameter |
Description |
|---|---|
Id |
Specifies the Id of the UserProfile to delete. Required if Email is not specified. If both Email and Id are specified, an exception will be thrown. |
Specifies the email address of the UserProfile to delete. Required if Id is not specified. If both Email and Id are specified, an exception will be thrown. |
Operation Sequence Components
Operation Sequence Component |
Description |
|---|---|
UserProfileLoader |
Retrieves the user from Commerce Server and caches it for other pipeline processing. |
UserProfileAddressesProcessor |
Adds, updates, and/or deletes addresses associated with this user. |
UserProfileCreditCardsValidator |
Adds, updates, and/or deletes credit cards associated with this user. |
UserProfileShippingMethodProcessor |
Adds, updates, and/or deletes shipping method associated with this user. |
UserProfileCommitter |
Commits the user profile changes to Commerce Server. |
UserProfileResponseBuilder |
Converts the user profiles of the cached Commerce Server to Commerce Server 2009 user profiles and adds them to the response. |
UserProfileAddressResponseBuilder |
Converts Commerce Server addresses to Commerce Server 2009 addresses and adds them to the response. |
UserProfileCreditCardsResponseBuilder |
Converts Commerce Server credit cards to Commerce Server 2009 credit cards and adds them to the response. |
UserProfileShippingMethodsResponseBuilder |
Converts Commerce Server shipping methods to Commerce Server 2009 shipping methods and adds them to the response. |
Related Operations
Related Operation |
Description |
|---|---|
CommerceCreateRelatedItem<Address>(Addresses) |
Creates and adds a new address to the system. At a minimum, you need to specify the following information when creating an address:
PropertyDescription
AddressNameA user friendly name for this address.
Line1The street address or PO Box.
StateProvinceCodeThe code for the state or province. For example, ON for Ontario.
ZipPostalCodeThe zip code or postal code.
CountryRegionCodeThe code for the country. For example, CA for Canada.
|
CommerceCreateRelatedItem<CreditCard>(CreditCards) |
Creates and adds a new credit card to the system. At a minimum, you need to specify the following information when creating a credit card profile:
PropertyDescription
PaymentGroupIdentifies the payment group type.
CreditCardNumberThe account number for the credit card.
ExpirationMonthThe month component of the expiry date for the credit card.
ExpirationYearThe year component of the expiry date for the credit card.
CreditCardIdentifierAn identifier for the credit card, such as the last four digits.
BillingAddressIdThe ID of an address profile to use as a billing address.
|
CommerceUpdateRelatedItem<Address> (Addresses) |
Updates an existing address. At a minimum, the caller must specify the ID of the address to update. This operation supports CommerceModelSearch only. |
CommerceUpdateRelatedItem<CreditCard>(CreditCards) |
Updates an existing credit card. At a minimum, the caller must specify the ID of the credit card to update. This operation supports CommerceModelSearch only. |
CommerceCreateRelationship<Address>(PreferredAddress) |
Marks one Address in the user's Addresses list as the preferred address. |
CommerceCreateRelationship<CreditCard>(PreferredCreditCard) |
Marks one CreditCard in the user's CreditCards list as the preferred credit card. |
CommerceDeleteRelatedItem<Address>(Addresses) |
Deletes an existing address. Care should be taken when deciding to delete an address profile as it is deleted permanently from the system. Any user profiles that reference this credit card will also need to be updated to remove the address from their address list, as well as to make sure that their preferred address card is not set to the address being deleted. At a minimum, the caller must specify the ID of the address to update. This operation supports CommerceModelSearch only. |
CommerceDeleteRelatedItem<CreditCard>(CreditCards) |
Deletes an existing credit card. Care should be taken when deciding to delete a credit card profile as it is deleted permanently from the system. Any user profiles that reference this credit card will also need to be updated to remove the credit card from their credit card list, as well as to make sure that their preferred credit card is not set to the credit card being deleted. This operation requires the ID of the credit card to delete. This operation supports CommerceModelSearch only. |
CommerceDeleteRelationship<Address>(PreferredAddress) |
Clears the users's preferred address. |
CommerceDeleteRelationship<CreditCard>(PreferredCreditCard) |
Clears the users's preferred credit card. |
CommerceDeleteRelationship<ShippingMethod>(PreferredShippingMethod) |
Clears the users's preferred shipping method. |
CommerceCreateRelationship<ShippingMethod>(PreferredShippingMethod) |
Sets the user's preferred shipping method. |
CreditCard Related Operations
The CreditCard commerce entity contains a relationship to a PaymentMethod. There must be support to change the payment method from one type to another, for example, editing a credit card and changing its type, such as from Visa to MasterCard. It's not necessary to allow deletion of the relationship from the credit card to the payment method. This is because the payment method is required for the credit card, and by allowing the ability to delete the relationship to the payment method, there's an opportunity for credit cards to have no payment methods associated to them, which could lead to errors.
To work around this limitation, the caller can only create a new relationship to an existing item.
Related Operation |
Description |
|---|---|
CommerceCreateRelationship<PaymentMethod>(PaymentMethod) |
Changes the relationship to another existing payment method. |
Valid Update Operations
Operation Parameter |
Description |
|---|---|
SearchCriteria.Model type(s) |
An exception will be thrown if any model type other than UserProfile is specified. |
SearchCriteria.Model.Id |
ID of the user to update. Required if Email is not specified. If both Email and Id are specified, an exception will be thrown. |
SearchCriteria.Model.Email |
E-mail address of the user to update. Required if Id is not specified. If both Email and Id are specified, an exception will be thrown. |
Valid Update Operations
CommerceUpdateRelatedItem<Address> (Addresses)
Related Operation Parameter |
Description |
|---|---|
SearchCriteria.Model.Id |
When updating an existing address, you must specify the ID of the address to update. |
CommerceUpdateRelatedItem<CreditCard> (CreditCards)
Related Operation Parameter |
Description |
|---|---|
SearchCriteria.Model.Id |
When updating an existing credit card, you must specify the ID of the credit card to update. |
CommerceDeleteRelatedItem<Address> (Addreses)
Related Operation Parameter |
Description |
|---|---|
SearchCriteria.Model.Id |
Id of the address to delete. If id is not specified, all related addresses are deleted. |
CommerceDeleteRelatedItem<CreditCard> (CreditCards)
Related Operation Parameter |
Description |
|---|---|
SearchCriteria.Model.Id |
Id of the credit card to delete. If id is not specified, all related credit cards are deleted. |
CommerceDeleteRelationship<Address> (PreferredAddress)
Related Operation Parameter |
Description |
|---|---|
SearchCriteria.Model |
Must be empty. |
CommerceDeleteRelationship<CreditCard> (PreferredCreditCard)
Related Operation Parameter |
Description |
|---|---|
SearchCriteria.Model |
Must be empty. |
CommerceDeleteRelationship<ShippingMethod> (PreferredShippingMethod)
Related Operation Parameter |
Description |
|---|---|
SearchCriteria.Model |
Must be empty. |
Return Value
This Microsoft Multi-Channel Commerce Foundation operation returns a CommerceUpdateOperationResponse.
Exceptions
Microsoft Multi-Channel Commerce Foundation can throw the following exception during this operation:
- FaultException<ItemDoesNotExistFault>
Remarks
The UserProfile object contains a PreferredAddress and PreferredCreditCard property. The object referenced by these properties will also be in the list of Addresses and CreditCards. If a caller were to attempt to update the object in the PreferredAddress record and update the same element in AddressList, there could be collisions and could result in data being overwritten. To prevent this scenario from occurring, the API does not allow updates through the PreferredAddress and PreferredCreditCard properties. Instead, the user updates through elements in the AddressList or CreditCardList.
See Also
Other Resources
Developing with the Commerce Foundation Profiles System
Commerce Foundation User Profile
Commerce Foundation UserProfile CommerceCreate
Commerce Foundation UserProfile CommerceDelete