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
OrderTracking
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. |
TODO:
/myaccount/loggedIn (GET)
/myaccount/login (GET/POST)
/myaccount/logout (GET)
/myaccount/changePassword (POST)
/myaccount/forgotPassword (POST)
/myaccount/settings (GET)
/myaccount/settings (POST)
/myaccount/settings (PUT)
/myaccount/settings (DELETE)
/myaccount/shippingAddresses (GET)
/myaccount/shippingAddresses/id (GET)
/myaccount/shippingAddresses (POST)
/myaccount/shippingAddresses/id (PUT)
/myaccount/shippingAddresses/id (DELETE)
/myaccount/billingAddresses (GET)
/myaccount/billingAddresses/id (GET)
/myaccount/billingAddresses (POST)
/myaccount/billingAddresses/id (PUT)
/myaccount/billingAddresses/id (DELETE)
/myaccount/creditCards (GET)
/myaccount/creditCards/id (GET)
/myaccount/creditCards (POST)
/myaccount/creditCards/id (PUT)
/myaccount/creditCards/id (DELETE)
/myaccount/orders (GET)
/myaccount/orders/orderId (GET)
/myaccount/orders/orderId/tracking (GET)
/myaccount/orders/orderId/case (GET)
/myaccount/orders/orderId/case (POST)
/myaccount/notReviewedYet (GET)
/myaccount/reviews (GET)