UltraCart REST MyAccount API
Introduction
The MyAccount API is the backbone of the UltraCart customer portal. It is an mini-app and part of your UltraCart web site allowing customers to view order history, edit their personal information, and correspond with you, the Merchant. There are two forms of the customer portal. The first is hosted by UltraCart. The second may be hosted anywhere on your own personal web sites. The UltraCart hosted portal is stylized using the Screen Branding themes. Any externally hosted portal is left to individual styling via the normal means.
You may view your UltraCart hosted customer portal using this url and substituting your Merchant ID:
https://secure.ultracart.com/cgi-bin/UCMyAccount?merchantId=DEMO
(also, if you're using a custom SSL certificate, replace secure.ultracart.com with your server name...)
A reference implementation for externally hosted portals is sourced on github: https://github.com/UltraCart/my_account
It recommended that you start with that implementation since the API was custom built for it.
Examples and Demo (Every call is used by the example script and the demo. Just search for the call.)
Examples: https://github.com/UltraCart/my_account/blob/master/js/myaccount_rest_1.3.js
Demo: https://secure.ultracart.com/merchant/integrationcenter/my_account_demo/
Note: The myaccount_rest link above will go stale as the version is incremented. If that's the case, just go here and look for the latest version: https://github.com/UltraCart/my_account/tree/master/js
Every call in the MyAccount REST API uses two cookies for authentication:
UltraCartMerchantId
- Merchant ID
UltraCartShoppingCartId
- Cart ID
This is to remain consistent with the UltraCart shopping cart engine. Using the same two cookies avoids multiple login prompts to the customer.
These cookies are automatically set by the login methods, so after login, security is transparent.
Most pages may use a simple model to handle expired sessions or invalid logins:
var redirectToLogin = function () { var location_href = "index.html"; if (location.hash && location.hash.length > 0) { location_href += "?hash=" + location.hash.substring(1); } location.href = location_href; }; jQuery(document).ajaxError(function (event, xhr) { if (xhr.status == 401) redirectToLogin(); });
Be aware that the valid presence of these two cookies is not enough to constitute a "logged in" status. The customer must have submitted their profile username and password as some point and the server must have a flag set on its internal record denoting the customer as logged. So do not assume that just because you're seeing these two cookies accompany REST calls that the customer is logged in.
Object Model
These json objects are used with the REST MyAccount API.
- id fields are only required for existing objects. When creating/adding new objects, the id field is always blank and provided by the UltraCart servers.
- Any string fields larger than their maximum size are silently truncated. The field sizes are large enough to handle most data, and the truncation is rarely a problem. The biggest issue with with email addresses. But, an email over 100 characters is also a rarity (pity the soul that has that address).
Address
Field | Type | Required | Comment |
id | int | Yes* | Object Identifier. This will always be returned from the server. Do not create one on your own (won't be accepted). A common problem that causes our json deserializer to vomit is submitting a new Address with an empty string. Null is okay. A string that is a parsable integer is okay. But a zero length string has no integer equivalent. Be careful not to do this! |
company | string(50) | No | |
firstName | string(30) | Yes | |
lastName | string(30) | Yes | |
address1 | string(32) | Yes | |
address2 | string(32) | No | |
city | string(32) | Yes | |
state | string(32) | Yes | |
postalCode | string(20) | Yes | In the US, this is known as 'zip code' |
country | string(32) | Yes | |
title | string(50) | No | |
dayPhone | string(25) | No | |
eveningPhone | string(25) | No |
Case
The case is the parent object for a series of emails that can be exchanges between a customer and a merchant when there is a problem. The case is created when the customer clicks the "Feedback" button for an order.
They can then send a message to a merchant.
Field | Type | Required | Edit/Update | Comment |
caseOid | string | Yes* | No | Object Identifier. This will always be returned from the server. Do not create one on your own (won't be accepted). |
merchantId | string(5) | Yes | No | not required during insert. it's collected from cookies |
orderId | string(30) | Yes | No | |
string(100) | Yes | Yes | order email is used if missing | |
customerProfileId | string | Yes | No | this is an integer (it's type is a string to avoid server parser errors) this is the customer identifier. It is created when a customer creates a new profile during ordering. This value can be found from the MyAccount object returned from the login methods. |
creationDate | string | No | No | ISO-8601 format. very handy when used with something like moment.js Assigned during case creation. Immutable afterwards. |
creationDateFormatted | string | No | No | A formatted version of creationDate. Format is: dd MMM yyyy HH:mm:ss Sometimes it's not practical to format the ISO-8601 string, for example, within a Handlebars template. |
subject | string(200) | Yes | Yes | This is whatever the customer chooses to name their correspondence with you. This isn't a prominent feature (it's not used as extensively as it could be). |
status | string(50) | Yes | Yes | Valid Values:
As a merchant, you'll want to monitor New and Reply Received very closely. They require immediate response. |
lastUpdateDate | string | No | No | ISO-8601 format. very handy when used with something like moment.js Updated whenever activity occurs. The system updates this. It will ignore any changes you make to this field. |
lastUpdateDateFormatted | string | No | No | A formatted version of lastUpdateDate. Format is: dd MMM yyyy HH:mm:ss Sometimes it's not practical to format the ISO-8601 string, for example, within a Handlebars template. |
messages | CaseMessage[ ] | No | Insert | an array of messages (emails). Contains both customer and merchant emails. |
Case Message
This is a wrapper object for a message, either from a customer to merchant, or merchant to customer.
Messages cannot be updated once inserted since the emails go out immediately. It would be pointless to edit a message record.
Field | Type | Required | Edit/Update | Comment |
caseMessageOid | String | Yes* | No | Object Identifier. This will always be returned from the server. |
caseOid | string | Yes* | No | Object Identifier. This will always be returned from the server. Do not create one on your own (won't be accepted). The caseOid is usually not required when a message is being created because it is extracted from the REST url. If this message is the first of a new case, the oid won't even exist yet. Don't worry about it. It will be created and populatd in the reture value from any insert calls. |
message | string(2000) | Yes | No | the main body of the email |
messageSender | string(20) | No | No | The messageSender is determined by the API call. Any message created from the MyAccount REST API will be from a customer. Any message created with the OrderEditor API (currently private) will be from the merchant. Values: |
messageDate | string | No | No | ISO-8601 format. very handy when used with something like moment.js Assigned during message creation. Immutable afterwards. |
messageDateFormatted | string | No | No | A formatted version of messageDate. Format is: dd MMM yyyy HH:mm:ss |
ChangePasswordRequest
This is the wrapper object for the old and new passwords needed to change a customer's password. The email address is not needed because the customer must be logged in to change their password and the email address is collected from their login record.
Field | Type | Required | Edit/Update | Comment |
oldPassword | string(30) | Yes* | No | old password |
newPassword | string(30) | Yes* | No | new password |
CreditCard
A credit card object used on the payment pages.
The credit card has several int fields. Be careful that you do not submit a json object with an empty string "" in any of these fields. That will cause a parse exception and your record rejected. For number fields, must provide either a number, or null/empty. Zero length strings are not the same thing.
Field | Type | Required | Edit/Update | Comment |
merchantId | string(30) | Yes* | No | old password |
customerProfileId | string(30) | Yes* | No | new password |
id | id | Yes* | No | an internal identifer to the record. Used during updates/deletes. Do not create your own. The server will assign an id when the object is created and it will be returned from the insert call. |
cardType | string | Yes | Yes | A Valid card type. This depends on what the merchant has configured, but the possible values are: Case and spaces matter on the card type. Take care. |
cardExpMonth | int | Yes | Yes | 1-12 corresponding to the 12 months of Jan-Feb |
cardExpYear | int | Yes | Yes | Four digit year. |
cardNumber | string | Yes | Yes | A valid credit card number. Validity depends on the card type. When credit card records are returned from the server, they are always masked. The only time this record has the full CC number is upon insert/update. Don't worry about wiping the CC field. Leave the mask in place. The server is smart enough to check for an updated number and apply it. If the mask is returned, the server will ignore the field. |
lastUsedDate | string | No | No | ISO-8601 format. very handy when used with something like moment.js Updated whenever the card is used or changed. Do not provide or update this value. Any updates are ignored. This value is assigned on the server. |
lastUsedDateFormatted | string | No | No | A formatted version of lastUsedDate. Format is: dd MMM yyyy HH:mm:ss |
CustomerCredentials
This is the wrapper object for the values needed during login.
Field | Type | Required | Edit/Update | Comment |
merchantId | string(50) | Yes | N/A | |
string(100) | Yes | N/A | ||
password | string(30) | Yes | N/A |
MyAccount
This contains the high level record for the customer. While there is overlap between this record and the shipping/billing addresses, this is the address of record.
It cannot be deleted, except to delete the entire customer.
This record cannot be created, except during the ordering process by the customer. It can only be selected / updated / deleted from the MyAccount API
Field | Type | Required | Comment |
merchantId | string(5) | Yes | |
customerProfileId | int | Yes* | Object Identifier. This will always be returned from the server. Do not create one on your own (won't be accepted). A common problem that causes our json deserializer to vomit is submitting a new Address with an empty string. Null is okay. A string that is a parsable integer is okay. But a zero length string has no integer equivalent. Be careful not to do this! |
title | string(50) | No | |
company | string(50) | No | |
firstName | string(30) | Yes | |
lastName | string(30) | Yes | |
address1 | string(32) | Yes | |
address2 | string(32) | No | |
city | string(32) | Yes | |
state | string(32) | Yes | |
postalCode | string(20) | Yes | In the US, this is known as 'zip code' |
country | string(32) | Yes | |
title | string(50) | No | |
dayPhone | string(25) | No | |
eveningPhone | string(25) | No | |
fax | string(32) | No | Does anyone even use fax machines any more? If so, this field is for them. |
taxId | string(15) | No | Very popular field for wholesale customers. |
password | string(30) | No | This is not returned when the records are selected, and it cannot be updated via this record. It must be updated via a specific call (changePassword). As I write this, I'm not really sure why it's even a part of this record... |
NotReviewedItem
This object represents a purchased item that does not yet have a review written by the customer. It's used on the reviews page and contains enough information to display a line enticing the customer to write a review and then direct them to the review screen.
Reviews cannot be created via this API. This was done on purpose to drive all reviews through the review cgi. That cgi has a multitude of functionality chosen not to duplicate.
Field | Type | Comment |
merchantId | string(5) | |
itemId | string(30) | The merchant item id. |
merchantItemOid | string | An string containing a number that is used to internally identify the item record. Both the item id and oid are provided because both are needed at different times during the display and link creation. |
lastOrderDate | string | ISO-8601 format. very handy when used with something like moment.js Contains the last date the item was ordered. Since the "not reviewed yet" item list is a distinct list, this value helps show the most recent purchases first. |
lastOrderDateFormatted | string | A formatted version of lastOrderDate. Format is: dd MMM yyyy HH:mm:ss Sometimes it's not practical to format the ISO-8601 string, for example, within a Handlebars template. |
item | Item | A complex item containing all the details about the item. See its page for specifics. |
Order
Every money field below is a number value. The number field has a corresponding string field with the suffix of 'Formatted'. These formatted fields contain the currency sign and decimal places. You should use the formatted fields wherever possible. Doing currency conversions of past orders is extremely complicated.
Field | Type | Comment |
labels | hash | this hash contains all the labels for the various fields below. This hash is powerful because it contains the mappings you specify in the back end "screen branding' section. See the order labels section for individual listings. |
merchantId | string | your merchant id |
customerProfileId | int | customer's internal identifier |
orderId | string | order id |
rejected | boolean | true if the order was rejected |
themeCode | string | the theme code applied to this order. See screen branding. This code is often used when creating buy links to apply the proper look and feel to an order page. Some merchants only have one theme. Some merchants have 50. |
creationDate | string | ISO-8601 format. When the order was created |
creationDateFormatted | string | DD-MMM-YYYY format. When the order was created |
shipOnDate | string | ISO-8601 format. When the order was requested to ship on. |
shipOnDateFormatted | string | DD-MMM-YYYY format. When the order was requested to ship on. |
saturdayDelivery | boolean | true if the order is set for Saturday delivery |
rejectedDate | string | ISO-8601 format. When the order was rejected (null if it hasn't been) |
rejectedDateFormatted | string | DD-MMM-YYYY format of when the order was rejected, if it was. |
quoteExpirationDate | string | ISO-8601 format. If this order is a quote, when the quote expires. |
quoteExpirationDateFormatted | string | DD-MMM-YYYY format. If this order is a quote, when the quote expires. |
status | string | Completed, Rejected, Quote Sent, Quote Requested, Pre-Order Item, Pending |
testOrder | boolean | true if this order was a test |
shippingMethod | string | a bare bones description of the shipping method |
shippingMethodName | string | a friendly version of the shipping method. This should be preferred for display over shippingMethod |
shippingMethodDetailed | string | an elaborate string contain shippingMethodName and any features such as lift gates and ship to residential, |
shippingMethodCompany | string | UPS, FedEx, etc. |
shipping3rdPartyAccountNumber | string | |
string | ||
ccEmails | string[ ] | an array of email addresses who were cc'd on the order. |
giftEmail | string | the gift recipient's email address |
billToCompany | string | |
billToTitle | string | |
billToFirstName | string | |
billToLastName | string | |
billToAddress1 | string | |
billToAddress2 | string | |
billToCity | string | |
billToState | string | |
billToPostalCode | string | |
billToCountry | string | |
billToDayPhone | string | |
billToEveningPhone | string | |
shipToCompany | string | |
shipToTitle | string | |
shipToFirstName | string | |
shipToLastName | string | |
shipToAddress1 | string | |
shipToAddress2 | string | |
shipToCity | string | |
shipToState | string | |
shipToPostalCode | string | |
shipToCountry | string | |
shipToDayPhone | string | |
shipToEveningPhone | string | |
gift | boolean | true if the order is a gift |
liftGate | boolean | true if the order requires a lift gate to deliver. |
shipToResidential | boolean | true if the delivery is a residence |
hidePaymentInformation | boolean | whether or not to show payment information. Imagine the scenario where the cost is zero and/or gift certificates were used. |
refundPresent | boolean | duplicate of hasRefund. Use hasRefund, as this field is deprecated and will be removed without warning. |
taxShipping | boolean | is shipping taxed? this affects the display of subtotal information (tax before subtotal or subtotal before tax). |
taxCounty | string | |
referralCode | string | |
advertisingSource | string | |
paymentMethod | string | Credit Card, PayPal Order, etc. Supported payment methods as of 6/2013 (list may change):
|
paymentNote | string | A friendly working of the paymentMethod. For display purposes, use this value instead of paymentMethod. It will always read the same or better. |
cardType | string | The type of credit card used. VISA, MasterCard, etc. |
cardNumber | string | masked. last four digits. |
coupons | Coupon | The coupon class contains two simple fields: code and description |
items | Item[ ] | The items for this order |
giftWrapTitle | string | the name of the gift wrap |
giftWrapCost / giftWrapCostFormatted | number / string | |
hasDiscount | boolean | true if a discount was made somewhere (often useful for adding an extra table column, etc.) |
hasRefund | boolean | true if a refund was made somewhere (often useful for adding an extra table column, etc.) |
subtotalBeforeDiscount / subtotalBeforeDiscountFormatted | number / string | |
discount / discountFormatted | number / string | |
subtotal / subtotalFormatted | number / string | subtotal with any discounts and refunds already applied |
subtotalRefunded / subtotalRefundedFormatted | number / string | |
taxRate / taxRateFormatted | number / string | |
shippingHandlingDiscount / shippingHandlingDiscountFormatted | number / string | |
shippingHandlingTotal / shippingHandlingTotalFormatted | number / string | total with any discounts and refunds already applied. |
shippingHandlingRefunded / shippingHandlingRefundedFormatted | number / string | |
tax / taxFormatted | number / string | tax with any refund already applied |
taxRefunded / taxRefundedFormatted | number / string | |
giftCharge / giftChargeFormatted | number / string | |
surcharge / surchargeFormatted | number / string | |
showBuysafe | boolean | true if this order used buySAFE and the amounts should be shown. |
buysafeCost / buysafeCostFormatted | number / string | |
buysafeRefunded / buysafeRefundedFormatted | number / string | |
boolean | true if this order used InsureShip and the amounts should be shown. InsureShip is no longer available. This would only apply to old legacy orders. It's doubtful you need to consider this field. | |
number / string | insure ship cost | |
number / string | value of any insure ship refunded | |
total / totalFormatted | number / string | grand total |
totalRefunded / totalRefundedFormatted | number / string | of the total, this amount was refunded |
showCurrencyWarning | boolean | true if the currency warning (next line) should be shown. |
currencyWarning | string | this is the standard currency warning if the order was placed in a different currnency. It contains a nicely formatted message to show to the customer. |
giftCertificateCode | string | the gift certificate code. If the gift certificate was a credit card type, the code will be masked. |
giftCertificateAmount / giftCertificateAmountFormatted | number / string | the amount used of the gift certificate |
giftMessage | string[ ] | array of gift message lines when this field was entered, newlines were captured to preserve the look. so this field is an array of strings broken by newlines. You may join them or iterate them as desired. |
specialInstructions | string[ ] | array of special instructions text when this field was entered, newlines were captured to preserve the look. so this field is an array of strings broken by newlines. You may join them or iterate them as desired. |
comments | string[ ] | array of comments when this field was entered, newlines were captured to preserve the look. so this field is an array of strings broken by newlines. You may join them or iterate them as desired. |
trackingNumbers | string[ ] | array of tracking numbers |
orderCase | Case | See the case object above. If there is a case (customer feedback) associated with this order, it will be populated in this value. |
Order Labels
The order labels are formatted labels for use when displaying an order. They should be used whenever possible.
The default value is what is used if you have not configured anything custom in your Checkout Text section of the Configuration area.
Hash Key | Default |
quoteRequestIdField | Quote Request ID |
requestDateField | Request Date |
expirationDateField | Quote Expiration Date |
orderIdField | Order ID |
sbtField | SBT |
orderDateField | Order Date |
billToHeader | Bill To |
shipToHeader | Ship To |
jobTitleField | Job Title |
titleField | Title |
nameField | Name |
companyField | Company |
addressField | Address |
cityField | City |
stateField | State |
zipField | Zip |
countryField | Country |
emailField | |
ccEmailField | CC Email |
giftEmailField | Gift Email |
giftField | Gift |
phoneField | Phone |
eveningPhoneField | Evening Phone |
taxCountyField | Tax County |
shippingMethodField | Shipping Method |
residential | Residential |
liftGate | Lift Gate |
shipOnDateField | Ship on Date |
deliveryDateField | Delivery Date |
shipOnAccountField | Ship on Account |
advertisingSourceField | Advertising Source |
wrappingPaperField | Wrapping Paper |
itemHeader | Item |
quantityHeader | Quantity |
descriptionHeader | Description |
amountHeader | Amount |
refundedHeader | Refunded |
subtotalBeforeDiscountsField | Subtotal before discounts |
discountsField | Discounts |
subtotalField | Subtotal |
shippingHandlingField | Shipping/Handling |
taxRateField | Tax Rate |
taxField | Tax |
giftChargeField | Gift Charge |
surchargeField | Surcharge |
giftCertificateField | Gift Certificate |
totalField | Total |
buySafeFree | Free! |
yourActualMessage | Your actual financial statement may vary due to actual currency conversion. |
OrderTracking
Read-Only tracking information for an order
Field | Type | Comment |
merchantId | string | Your merchant id |
orderId | string | The order id |
hasTrackingUrl | boolean | true if the url is present. This flag, although seemingly useless, makes templating very easy. when a boolean is quicker and simpler to use than a "is this field present and not empty" check |
trackingNumber | string | The tracking number |
trackingUrl | string | The full url to the shipper's web site. |
ReviewedItem
This read-only object contains an item review.
Field | Type | Comment |
itemId | string | the item id of the item reviewed |
item | Item | A complex item containing all the details about the item. See its page for specifics. |
reviewOid | integer | review record's internal identifier |
merchantId | string | the merchant id (your merchant id) |
customerProfileId | integer | customer's internal identifier |
merchantItemOid | integer | item's internal identifier |
overall | number | 1-5 The overall rating of the item. This should be featured prominently. |
ratingName1 | string | The name (category) of this rating. Configured by the merchant. Examples: Ease of Use, Price, Durability, etc. |
ratingName2 | string | The name (category) of this rating. |
ratingName3 | string | The name (category) of this rating. |
ratingName4 | string | The name (category) of this rating. |
ratingName5 | string | The name (category) of this rating. |
ratingName6 | string | The name (category) of this rating. |
ratingName7 | string | The name (category) of this rating. |
ratingName8 | string | The name (category) of this rating. |
ratingName9 | string | The name (category) of this rating. |
ratingName10 | string | The name (category) of this rating. |
ratingScore1 | number | 1-5, the rating for the associated rating name. |
ratingScore2 | number | 1-5, the rating for the associated rating name. |
ratingScore3 | number | 1-5, the rating for the associated rating name. |
ratingScore4 | number | 1-5, the rating for the associated rating name. |
ratingScore5 | number | 1-5, the rating for the associated rating name. |
ratingScore6 | number | 1-5, the rating for the associated rating name. |
ratingScore7 | number | 1-5, the rating for the associated rating name. |
ratingScore8 | number | 1-5, the rating for the associated rating name. |
ratingScore9 | number | 1-5, the rating for the associated rating name. |
ratingScore10 | number | 1-5, the rating for the associated rating name. |
recommendToFriend | boolean | true if the customer would recomment the item to a friend. |
title | string | The title of the review |
review | string | The review itself. These are the customer's comments. |
statusCode | string | Approved , Rejected , or Unapproved |
featured | boolean | true if the merchant has chosen to feature this review |
recommendStoreToFriend | boolean | true if the customer would recommend your store to friends. |
storeFeedback | string | any comments the customer had for your store |
submittedDate | string | ISO-8601 format. very handy when used with something like moment.js Contains the date when the review was submitted |
submittedDateFormatted | string | A formatted version of submittedDate. Format is: dd MMM yyyy HH:mm:ss Sometimes it's not practical to format the ISO-8601 string, for example, within a Handlebars template. |
helpfulYesVotes | integer | the number of times other customers have marked a review as helpful. |
helpfulNoVotes | integer | the number of times other customers have marked a review as unhelpful. |
MyAccount REST API
/rest/myaccount/loggedIn
Method | GET | Comments |
---|---|---|
Description | returns MyAccount object if logged in, else empty object | Useful for determining if the customer is logged in without triggering a 401 Unauthorized response from the server. In the demo, this call is only used on the main page to determine whether to show the login screen or not. Most of the MyAccount pages will use security like this: var redirectToLogin = function () { var location_href = "index.html"; if (location.hash && location.hash.length > 0) { location_href += "?hash=" + location.hash.substring(1); } location.href = location_href; }; var theDocument = jQuery(document); theDocument.ajaxError(function (event, xhr) { if (xhr.status == 401) redirectToLogin(); }); |
Cookies |
| |
Path Parameters | none | |
Query Parameters | none | |
Headers | none | |
Receives Json | none | |
Returns Json | MyAccount object if logged in, else empty object | Note: To avoid json parser errors from the likes of FireFox, if the customer is not logged in, the method does NOT return null. It returns an empty object. Notice the example below checks for both result and result.email, so it's checking for a valid object that has some properties as well. By checking both 'result' and 'result.email' for values, you'll get correct results as to whether the customer is logged in or not. |
Example | this.loggedIn = function (options) { options = options || {}; var settings = null; jQuery.ajax({ url: restUrl + '/loggedIn', type: 'get', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function (result) { if(result && result.email){ settings = result; } else { settings = null; // if the result is an empty object, then customer is not logged in. } if (options.success) { options.success(settings); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return settings; }; |
/rest/myaccount/login
Method | GET or POST | Comments |
---|---|---|
Description | logs in a customer and returns their base information (MyAccount object) | There are two ways to login: GET or POST. For the GET, the three parameters are submitted. For POST, a CustomerCredentials object is submitted (it's a simple object with three fields). |
Cookies |
| not required, but if passed along and valid, the same shopping cart will continue to be used. Otherwise, a new cart is created and Set-Cookie headers will accompany a successful login. |
Path Parameters | none | |
Query Parameters | For GET:
password For POST: none | |
Headers | none | |
Receives Json | CustomerCredentials | |
Returns Json | MyAccount object if successful | A failed login will result in a 401 Unauthorized http status. Any missing parameers will result in a 400 Bad Request http status. |
Example | this.login = function (email, password, options) { options = options || {}; var credentials = {merchantId: merchantId, email: email, password: password}; var account = null; jQuery.ajax({ url: restUrl + '/login', data: JSON.stringify(credentials), type: 'post', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, contentType: 'application/json; charset=UTF-8', cache: false, dataType: 'json' }).done(function (result) { account = result; if (options.success) { options.success(account); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return account; }; |
/rest/myaccount/logout
Method | GET or POST | Comments |
---|---|---|
Description | logs out a customer | |
Cookies |
| used to determine which customer to logout |
Path Parameters | none | |
Query Parameters | none | |
Headers | none | |
Receives Json | none | |
Returns Json | none | |
Example | this.logout = function (options) { options = options || {}; // even if logged out, there may be a shopping cart, so return that cart if it's returned from the server. var cart = null; jQuery.ajax({ url: '/rest/myaccount/logout', type: 'get', headers: { "cache-control": "no-cache" }, async: (options.success || options.failure) ? true : false, cache: false, dataType: 'json' }).done(function (result) { cart = result; if (options.success) { options.success(cart); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return cart; }; |
/rest/myaccount/changePassword
Method | POST | Comments |
---|---|---|
Description | Updates password | This is the only way for a user to change their password |
Cookies |
| The customer must be successfully logged in to change their password. |
Path Parameters | none | |
Query Parameters | none | |
Headers | none | |
Receives Json | ChangePasswordRequest | |
Returns Json | nothing (204 on success) | A failed login will result in a 401 Unauthorized http status. Any missing parameers will result in a 400 Bad Request http status. Any parameters too long will result in a 400 Bad Request http status |
Example | this.changePassword = function (oldPassword, newPassword, options) { options = options || {}; jQuery.ajax({ url: '/rest/myaccount/changePassword', data: JSON.stringify({oldPassword: oldPassword, newPassword: newPassword}), type: 'post', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, contentType: 'application/json; charset=UTF-8', dataType: 'json' }).done(function () { if (options.success) { options.success(); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); }; |
/rest/myaccount/forgotPassword
Method | POST | Comments |
---|---|---|
Description | Emails customer new password | |
Cookies |
| The customer doesn't need to be logged in (obviously), but the Merchant ID is required. |
Path Parameters | none | |
Query Parameters | merchantId | Optional in place of cookie |
Headers | none | |
Receives Json | String (email) | Just a single email address as a string |
Returns Json | Plain text | The string |
Example | this.forgotPassword = function (email, options) { var msg = null; options = options || {}; jQuery.ajax({ url: '/rest/myaccount/forgotPassword', data: JSON.stringify(email), type: 'post', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, contentType: 'application/json; charset=UTF-8', dataType: 'text' }).done(function (result) { msg = result; if (options.success) { options.success(result); } }) .fail(function (jqXHR, textStatus, errorThrown) { msg = errorThrown; if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return msg; }; |
/rest/myaccount/settings
Method | GET | Comments |
---|---|---|
Description | returns customer settings | |
Cookies |
| The customer must be logged in. |
Path Parameters | none | |
Query Parameters |
| |
Headers |
| |
Receives Json | none | |
Returns Json | MyAccount object | password is not returned. a string of asterisks is returned instead. |
Example | this.getSettings = function (options) { options = options || {}; var account = null; jQuery.ajax({ url: '/rest/myaccount/settings', type: 'get', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function (result) { account = result; if (options.success) { options.success(account); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return account; }; |
/rest/myaccount/settings
Method | POST | Comments |
---|---|---|
Description | creates a new customer profile | This method will begin an email validated registration process. The merchant id, email, and password are the only required fields. You may also provide the first and last name to pre-populate the account. Upon successful email verification, any prior orders associated with the email address will be updated and assigned to the newly created account. |
Cookies |
| A new account cannot be created if the customer is logged in. They must log out first to create an account. |
Path Parameters | none | |
Query Parameters | redirectUrl themeCode | The redirectUrl is the url where you wish the customer to be redirected to after they click on their email confirmation. This should be the full url, including protocol. For security reasons, this exact url must be supplied in the Customer Profiles Settings page. themeCode is the screen branding theme code. it ensures that if a redirect happens to a legacy page, the proper themeCode is displayed. You probably won't need this parameter if you have a StoreFront. |
Headers |
| |
Receives Json | MyAccount object | |
Returns Json | MyAccount object | the return object will contain the customer profile id (unique identifier) If the merchant account does not allow customer profiles, a 400 Bad Request is returned. If the email is already registered for this merchant, a 400 Bad Request is returned. password is not returned. a string of asterisks is returned instead. |
Example | this.createAccount = function (customerInformation, options) { options = options || {}; var account = null; jQuery.ajax({ url: '/rest/myaccount/settings', data: JSON.stringify(customerInformation), type: 'post', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, contentType: 'application/json; charset=UTF-8', dataType: 'json' }).done(function (result) { account = result; if (options.success) { options.success(account); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return account; }; |
/rest/myaccount/settings
Method | PUT | Comments |
---|---|---|
Description | updates customer settings | password cannot be updated here. It can only be done through changePassword. |
Cookies |
| |
Path Parameters | none | |
Query Parameters |
| |
Headers |
| |
Receives Json | MyAccount object | whatever you pass in as values is set for the object. If you pass in an empty object, all account properties are blanked out. If you pass in a single value, all others are blanked out. You should start with a fully populated account object from the get method and update that if you wish to change a single field. |
Returns Json | MyAccount object | password is not returned. a string of asterisks is returned instead. |
Example | this.updateSettings = function (changes, options) { options = options || {}; var account = null; jQuery.ajax({ url: '/rest/myaccount/settings', data: JSON.stringify(changes), type: 'put', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, contentType: 'application/json; charset=UTF-8', dataType: 'json' }).done(function (result) { account = result; if (options.success) { options.success(account); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return account; }; |
/rest/myaccount/settings
Method | DELETE | Comments |
---|---|---|
Description | deletes a customer profile | once a profile is deleted, it's gone. be careful allowing this. |
Cookies |
| Customer must be logged in to delete their profile. |
Path Parameters | none | |
Query Parameters |
| |
Headers |
| |
Receives Json | none | The settings object is not required to delete a profile. The cart id is sufficient. |
Returns Json | none | 204 No Content returned on success |
Example | this.deleteAccount = function (options) { options = options || {}; jQuery.ajax({ url: '/rest/myaccount/settings', type: 'delete', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function () { if (options.success) { options.success(); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); }; |
/rest/myaccount/shippingAddresses
Method | GET | Comments |
---|---|---|
Description | returns all shipping addresses | |
Cookies |
| The customer must be logged in. |
Path Parameters | none | |
Query Parameters |
| |
Headers |
| |
Receives Json | none | |
Returns Json | Array of Address objects | |
Example | this.getShippingAddresses = function (options) { options = options || {}; var addresses = []; jQuery.ajax({ url: '/rest/myaccount/shippingAddresses', type: 'get', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function (result) { addresses = result; if (options.success) { options.success(addresses); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return addresses; }; |
/rest/myaccount/shippingAddresses/{id}
Method | GET | Comments |
---|---|---|
Description | returns a shipping address record | |
Cookies |
| The customer must be logged in. |
Path Parameters | id | address record identifier |
Query Parameters |
| |
Headers |
| |
Receives Json | none | |
Returns Json | Address object | |
Example | this.getShippingAddress = function (id, options) { options = options || {}; var address = null; jQuery.ajax({ url: '/rest/myaccount/shippingAddresses/' + id, type: 'get', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function (result) { address = result; if (options.success) { options.success(address); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return address; }; |
/rest/myaccount/shippingAddresses
Method | POST | Comments |
---|---|---|
Description | adds a shipping address | |
Cookies |
| Customer must be logged in to perform this operation |
Path Parameters | none | |
Query Parameters |
| |
Headers |
| |
Receives Json | Address object | |
Returns Json | Address object | the return object will contain the record id (unique identifier) Any field violations (exceeded length, missing fields) will return a 400 Bad Request. If the address already exists, a 400 Bad Request is returned. |
Example | this.insertShippingAddress = function (address, options) { options = options || {}; var insertedAddress = null; // will contain oid jQuery.ajax({ url: '/rest/myaccount/shippingAddresses', type: 'post', data: JSON.stringify(address), async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, contentType: 'application/json; charset=UTF-8', dataType: 'json' }).done(function (result) { insertedAddress = result; if (options.success) { options.success(insertedAddress); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return insertedAddress; }; |
/rest/myaccount/shippingAddresses/{id}
Method | PUT | Comments |
---|---|---|
Description | updates a shipping address record | |
Cookies |
| |
Path Parameters | id | shipping address record identifier |
Query Parameters |
| |
Headers |
| |
Receives Json | MyAccount object | |
Returns Json | MyAccount object | If the address is updated to an address that already exists, a 400 Bad Request is returned. |
Example | this.updateShippingAddress = function (address, options) { options = options || {}; var updatedAddress = null; jQuery.ajax({ url: '/rest/myaccount/shippingAddresses/' + address.id, type: 'put', data: JSON.stringify(address), async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, contentType: 'application/json; charset=UTF-8', dataType: 'json' }).done(function (result) { updatedAddress = result; if (options.success) { options.success(updatedAddress); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return updatedAddress; }; |
/rest/myaccount/shippingAddresses/{id}
Method | DELETE | Comments |
---|---|---|
Description | deletes a shipping address | |
Cookies |
| Customer must be logged in to delete an address |
Path Parameters | id | address record identifier |
Query Parameters |
| |
Headers |
| |
Receives Json | none | |
Returns Json | none | 204 No Content returned on success |
Example | this.deleteShippingAddress = function (address, options) { options = options || {}; jQuery.ajax({ url: '/rest/myaccount/shippingAddresses/' + address.id, type: 'delete', data: JSON.stringify(address), async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, contentType: 'application/json; charset=UTF-8', dataType: 'json' }).done(function () { if (options.success) { options.success(); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); }; |
/rest/myaccount/billingAddresses
Method | GET | Comments |
---|---|---|
Description | returns all billing addresses | |
Cookies |
| The customer must be logged in. |
Path Parameters | none | |
Query Parameters |
| |
Headers |
| |
Receives Json | none | |
Returns Json | Array of Address objects | |
Example | this.getBillingAddresses = function (options) { options = options || {}; var addresses = []; jQuery.ajax({ url: '/rest/myaccount/billingAddresses', type: 'get', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function (result) { addresses = result; if (options.success) { options.success(addresses); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return addresses; }; |
/rest/myaccount/billingAddresses/{id}
Method | GET | Comments |
---|---|---|
Description | returns a billing address record | |
Cookies |
| The customer must be logged in. |
Path Parameters | id | address record identifier |
Query Parameters |
| |
Headers |
| |
Receives Json | none | |
Returns Json | Address object | |
Example | this.getBillingAddress = function (id, options) { options = options || {}; var address = null; jQuery.ajax({ url: '/rest/myaccount/billingAddresses/' + id, type: 'get', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function (result) { address = result; if (options.success) { options.success(address); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return address; }; |
/rest/myaccount/billingAddresses
Method | POST | Comments |
---|---|---|
Description | adds a billing address | |
Cookies |
| Customer must be logged in to perform this operation |
Path Parameters | none | |
Query Parameters |
| |
Headers |
| |
Receives Json | Address object | |
Returns Json | Address object | the return object will contain the record id (unique identifier) Any field violations (exceeded length, missing fields) will return a 400 Bad Request. If the address already exists, a 400 Bad Request is returned. |
Example | this.insertBillingAddress = function (address, options) { options = options || {}; var insertedAddress = null; // will contain oid jQuery.ajax({ url: '/rest/myaccount/billingAddresses', type: 'post', data: JSON.stringify(address), async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, contentType: 'application/json; charset=UTF-8', dataType: 'json' }).done(function (result) { insertedAddress = result; if (options.success) { options.success(insertedAddress); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return insertedAddress; }; |
/rest/myaccount/billingAddresses/{id}
Method | PUT | Comments |
---|---|---|
Description | updates a billing address | |
Cookies |
| |
Path Parameters | id | billing address record identifier |
Query Parameters |
| |
Headers |
| |
Receives Json | MyAccount object | |
Returns Json | MyAccount object | If the address is updated to an address that already exists, a 400 Bad Request is returned. |
Example | this.updateBillingAddress = function (address, options) { options = options || {}; var updatedAddress = null; jQuery.ajax({ url: '/rest/myaccount/billingAddresses/' + address.id, type: 'put', data: JSON.stringify(address), async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, contentType: 'application/json; charset=UTF-8', dataType: 'json' }).done(function (result) { updatedAddress = result; if (options.success) { options.success(updatedAddress); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return updatedAddress; }; |
/rest/myaccount/billingAddresses/{id}
Method | DELETE | Comments |
---|---|---|
Description | deletes a billing address | |
Cookies |
| Customer must be logged in to delete an address |
Path Parameters | id | address record identifier |
Query Parameters |
| |
Headers |
| |
Receives Json | none | |
Returns Json | none | 204 No Content returned on success |
Example | this.deleteBillingAddress = function (address, options) { options = options || {}; jQuery.ajax({ url: '/rest/myaccount/billingAddresses/' + address.id, type: 'delete', data: JSON.stringify(address), async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, contentType: 'application/json; charset=UTF-8', dataType: 'json' }).done(function () { if (options.success) { options.success(); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); }; |
/rest/myaccount/creditCards
Method | GET | Comments |
---|---|---|
Description | returns all credit cards | |
Cookies |
| The customer must be logged in. |
Path Parameters | none | |
Query Parameters |
| |
Headers |
| |
Receives Json | none | |
Returns Json | Array of CreditCard objects | The card number is not returned (only a mask) |
Example | this.getCreditCards = function (options) { options = options || {}; var creditCards = []; jQuery.ajax({ url: '/rest/myaccount/creditCards', type: 'get', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function (result) { creditCards = result; if (options.success) { options.success(creditCards); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return creditCards; }; |
/rest/myaccount/creditCards/{id}
Method | GET | Comments |
---|---|---|
Description | returns a credit card record | |
Cookies |
| The customer must be logged in. |
Path Parameters | id | credit card identifier (not card number) |
Query Parameters |
| |
Headers |
| |
Receives Json | none | |
Returns Json | CreditCard object | The card number is not returned (only a mask) |
Example | this.getCreditCard = function (id, options) { options = options || {}; var creditCard = null; jQuery.ajax({ url: '/rest/myaccount/creditCards/' + id, type: 'get', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function (result) { creditCard = result; if (options.success) { options.success(creditCard); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return creditCard; }; |
/rest/myaccount/creditCards
Method | POST | Comments |
---|---|---|
Description | adds a credit card | |
Cookies |
| Customer must be logged in to perform this operation |
Path Parameters | none | |
Query Parameters |
| |
Headers |
| |
Receives Json | CreditCard object | |
Returns Json | CreditCard object | the return object will contain the record id (unique identifier) Any field violations (exceeded length, missing fields) will return a 400 Bad Request. If the card number already exists, a 400 Bad Request is returned. The card number is not returned (only a mask) |
Example | this.insertCreditCard = function (creditCard, options) { options = options || {}; var insertedCard = null; // will contain oid jQuery.ajax({ url: '/rest/myaccount/creditCards', type: 'post', data: JSON.stringify(creditCard), async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, contentType: 'application/json; charset=UTF-8', dataType: 'json' }).done(function (result) { insertedCard = result; if (options.success) { options.success(insertedCard); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, jqXHR, textStatus, errorThrown); } }); return insertedCard; }; |
/rest/myaccount/creditCards/{id}
Method | PUT | Comments |
---|---|---|
Description | updates a credit card | |
Cookies |
| |
Path Parameters | id | credit card record identifier (not card number) |
Query Parameters |
| |
Headers |
| |
Receives Json | CreditCard object | The card number is only updated if it contains a valid card. If the mask is returned or an empty field returned, the card number is not updated. |
Returns Json | CreditCard object | If the card number is updated to a card that already exists, a 400 Bad Request is returned. |
Example | this.updateCreditCard = function (creditCard, options) { options = options || {}; var updatedCard = null; jQuery.ajax({ url: '/rest/myaccount/creditCards/' + creditCard.id, type: 'put', data: JSON.stringify(creditCard), async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, contentType: 'application/json; charset=UTF-8', dataType: 'json' }).done(function (result) { updatedCard = result; if (options.success) { options.success(updatedCard); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return updatedCard; }; |
/rest/myaccount/creditCards/{id}
Method | DELETE | Comments |
---|---|---|
Description | deletes a credit card | |
Cookies |
| Customer must be logged in to delete an address |
Path Parameters | id | credit card identifier (not card number) |
Query Parameters |
| |
Headers |
| |
Receives Json | none | |
Returns Json | none | 204 No Content returned on success |
Example | this.deleteCreditCard = function (creditCard, options) { options = options || {}; jQuery.ajax({ url: '/rest/myaccount/creditCards/' + creditCard.id, type: 'delete', data: JSON.stringify(creditCard), async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, contentType: 'application/json; charset=UTF-8', dataType: 'json' }).done(function () { if (options.success) { options.success(); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(textStatus, errorThrown); } }); }; |
/rest/myaccount/orders
Method | GET | Comments |
---|---|---|
Description | returns orders belonging to customer | |
Cookies |
| The customer must be logged in. |
Path Parameters | none | |
Query Parameters | pageNumber pageSize search _filterTime | pagination number number of records per page (max is 10) order id, item id, or item description search term One of the following values:
|
Headers | Returned headers: uc-pagination-page-size uc-pagination-page-number uc-pagination-total-records uc-pagination-total-pages | page size of result set page number of result set total number of records found total number of pages found |
Receives Json | none | |
Returns Json | Array of Order objects | |
Example | /** * returns back pagination of orders, the success callback will * receive 1) orders, 2) pagination object (pageSize,pageNumber,totalRecords,totalPages) * @param [options] success and failure callbacks, 'pageNumber' and 'pageSize' * @return Object no callbacks specified, this returns back an object containing 'orders' and 'pagination' of orders (on success), else null */ this.getOrders = function (options) { options = options || {}; var data = {}; data['pageNumber'] = options.pageNumber || ''; data['pageSize'] = options.pageSize || ''; // data['searchString'] = options.search || ''; data['_filterTime'] = options.filter || ''; var orders = []; var pagination = {}; jQuery.ajax({ url: '/rest/myaccount/orders', type: 'get', data: data, async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function (result, textStatus, jqXHR) { orders = result; pagination['pageSize'] = parseInt(jqXHR.getResponseHeader('uc-pagination-page-size')); pagination['pageNumber'] = parseInt(jqXHR.getResponseHeader('uc-pagination-page-number')); pagination['totalRecords'] = parseInt(jqXHR.getResponseHeader('uc-pagination-total-records')); pagination['totalPages'] = parseInt(jqXHR.getResponseHeader('uc-pagination-total-pages')); if (options.success) { options.success(orders, pagination); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(textStatus, errorThrown); } }); return {orders: orders, pagination: pagination}; }; |
/rest/myaccount/orders/{orderId}
Method | GET | Comments |
---|---|---|
Description | returns an order | |
Cookies |
| The customer must be logged in. |
Path Parameters | orderId | Order ID |
Query Parameters |
| |
Headers |
| |
Receives Json | none | |
Returns Json | Order object | 404 if order is not found. |
Example | this.getOrder = function (orderId, options) { options = options || {}; var order = null; jQuery.ajax({ url: '/rest/myaccount/orders/' + orderId, async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function (result) { order = result; if (options.success) { options.success(order); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(textStatus, errorThrown); } }); return order; }; |
/rest/myaccount/orders/{orderId}/tracking
Method | GET | Comments |
---|---|---|
Description | returns an order tracking information | |
Cookies |
| The customer must be logged in. |
Path Parameters | orderId | Order ID |
Query Parameters |
| |
Headers |
| |
Receives Json | none | |
Returns Json | Array of OrderTracking objects | empty array if no tracking available. |
Example | this.getOrderTracking = function (orderId, options) { options = options || {}; var tracking = null; jQuery.ajax({ url: '/rest/myaccount/orders/' + orderId + "/tracking", async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function (result) { tracking = result; if (options.success) { options.success(tracking); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(textStatus, errorThrown); } }); return tracking; }; |
/rest/myaccount/orders/{orderId}/case
Method | GET | Comments |
---|---|---|
Description | returns a case object for an order | See Case Management to better understand what a case is |
Cookies |
| The customer must be logged in. |
Path Parameters | orderId | Order ID |
Query Parameters |
| |
Headers |
| |
Receives Json | none | |
Returns Json | Case object | empty object (NOT a 404) if no case created yet for this object. case actions are not returned (internal use only) |
Example | this.getOrderCase = function (orderId, options) { options = options || {}; var orderCase = null; jQuery.ajax({ url: '/rest/myaccount/orders/' + orderId + "/case", type: 'get', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function (result) { if (result && result.caseOid) { orderCase = result; } if (options.success) { options.success(orderCase); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return orderCase; }; |
/rest/myaccount/orders/{orderId}/case
Method | POST | Comments |
---|---|---|
Description | inserts a case object for an order | See Case Management to better understand what a case is |
Cookies |
| The customer must be logged in. |
Path Parameters | orderId | Order ID |
Query Parameters |
| |
Headers |
| |
Receives Json | Case Object | The case must have one and only one message. A case can't exist without customer initiated feedback. If no message is supplied, a 400 Bad Request is returned. |
Returns Json | Case object | contains record identifier as well as submitted fields. |
Example | this.insertOrderCase = function (orderId, orderCase, options) { options = options || {}; jQuery.ajax({ url: '/rest/myaccount/orders/' + orderId + "/case", data: JSON.stringify(orderCase), type: 'post', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json', contentType: 'application/json; charset=UTF-8' }).done(function (result) { if (result) { orderCase = result; } if (options.success) { options.success(orderCase); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return orderCase; }; |
/rest/myaccount/orders/{orderId}/case/messages
Method | GET | Comments |
---|---|---|
Description | returns all messages for the case associated with an order | See Case Management to better understand what a case is |
Cookies |
| The customer must be logged in. |
Path Parameters | orderId | Order ID |
Query Parameters |
| |
Headers |
| |
Receives Json | none | |
Returns Json | Array of CaseMessage | if order doesn't exist, a 404 is returned. If no case exists, a 404 is returned. |
Example | this.getOrderCaseMessages = function (orderId, options) { options = options || {}; var messages = []; jQuery.ajax({ url: '/rest/myaccount/orders/' + orderId + "/case/messages", type: 'get', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function (result) { if (result) { messages = result; } if (options.success) { options.success(messages); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return messages; }; |
/rest/myaccount/orders/{orderId}/case/messages
Method | POST | Comments |
---|---|---|
Description | inserts a case message object for a case | See Case Management to better understand what a case is This will trigger an email to customer service. |
Cookies |
| The customer must be logged in. |
Path Parameters | orderId | Order ID |
Query Parameters |
| |
Headers |
| |
Receives Json | CaseMessage Object | If this order id doesn't exist, a 404 is returned. If no case exists for this order, a 400 Bad Request is returned. If no message is supplied, a 400 Bad Request is returned. |
Returns Json | Case object | contains record identifier as well as submitted fields. |
Example | this.insertOrderCaseMessage = function (orderId, messageText, options) { options = options || {}; var orderCaseMessage = {message: messageText}; // this is all that's needed to insert message. jQuery.ajax({ url: '/rest/myaccount/orders/' + orderId + "/case/messages", data: JSON.stringify(orderCaseMessage), type: 'post', async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json', contentType: 'application/json; charset=UTF-8' }).done(function (result) { if (result) { orderCaseMessage = result; } if (options.success) { options.success(orderCaseMessage); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(jqXHR, textStatus, errorThrown); } }); return orderCaseMessage; }; |
/rest/myaccount/notReviewedYet
Method | GET | Comments |
---|---|---|
Description | returns a distinct list of purchased items not yet reviewed. | |
Cookies |
| The customer must be logged in. |
Path Parameters | none | |
Query Parameters | pageNumber pageSize | pagination number number of records per page (max is 10) |
Headers | Returned headers: uc-pagination-page-size uc-pagination-page-number uc-pagination-total-records uc-pagination-total-pages | page size of result set page number of result set total number of records found total number of pages found |
Receives Json | none | |
Returns Json | Array of NotReviewedItem objects | |
Example | /** * returns back pagination of NotReviewedItem items, the success callback will * receive 1) review items, 2) pagination object (pageSize,pageNumber,totalRecords,totalPages) * @param [options] success and failure callbacks, 'pageNumber' and 'pageSize' * @return Object no callbacks specified, this returns back an object containing 'notYetReviewed' and 'pagination' of records (on success), else null */ this.getNotReviewedYet = function (options) { options = options || {}; var data = {}; data['pageNumber'] = options.pageNumber || ''; data['pageSize'] = options.pageSize || ''; var notReviewedYet = []; var pagination = {}; jQuery.ajax({ url: '/rest/myaccount/notReviewedYet', type: 'get', data: data, async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function (result, textStatus, jqXHR) { notReviewedYet = result; pagination['pageSize'] = parseInt(jqXHR.getResponseHeader('uc-pagination-page-size')); pagination['pageNumber'] = parseInt(jqXHR.getResponseHeader('uc-pagination-page-number')); pagination['totalRecords'] = parseInt(jqXHR.getResponseHeader('uc-pagination-total-records')); pagination['totalPages'] = parseInt(jqXHR.getResponseHeader('uc-pagination-total-pages')); if (options.success) { options.success(notReviewedYet, pagination); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(textStatus, errorThrown); } }); return {notReviewedYet: notReviewedYet, pagination: pagination}; }; |
/rest/myaccount/orders
Method | GET | Comments |
---|---|---|
Description | returns a list of reviews the customer has submitted | |
Cookies |
| The customer must be logged in. |
Path Parameters | none | |
Query Parameters | pageNumber pageSize | pagination number number of records per page (max is 10) |
Headers | Returned headers: uc-pagination-page-size uc-pagination-page-number uc-pagination-total-records uc-pagination-total-pages | page size of result set page number of result set total number of records found total number of pages found |
Receives Json | none | |
Returns Json | Array of ReviewedItem objects | |
Example | /** * returns back pagination of ReviewedItem items, the success callback will * receive 1) review items, 2) pagination object (pageSize,pageNumber,totalRecords,totalPages) * @param [options] success and failure callbacks, 'pageNumber' and 'pageSize' * @return Object no callbacks specified, this returns back an object containing 'reviews' and 'pagination' of records (on success), else null */ this.getReviews = function (options) { options = options || {}; var data = {}; data['pageNumber'] = options.pageNumber || ''; data['pageSize'] = options.pageSize || ''; var reviews = []; var pagination = {}; jQuery.ajax({ url: '/rest/myaccount/reviews', type: 'get', data: data, async: (options.success || options.failure) ? true : false, headers: { "cache-control": "no-cache" }, cache: false, dataType: 'json' }).done(function (result, textStatus, jqXHR) { reviews = result; pagination['pageSize'] = parseInt(jqXHR.getResponseHeader('uc-pagination-page-size')); pagination['pageNumber'] = parseInt(jqXHR.getResponseHeader('uc-pagination-page-number')); pagination['totalRecords'] = parseInt(jqXHR.getResponseHeader('uc-pagination-total-records')); pagination['totalPages'] = parseInt(jqXHR.getResponseHeader('uc-pagination-total-pages')); if (options.success) { options.success(reviews, pagination); } }) .fail(function (jqXHR, textStatus, errorThrown) { if (options.failure) { options.failure(textStatus, errorThrown); } }); return {reviews: reviews, pagination: pagination}; }; |