> For the complete documentation index, see [llms.txt](https://the-wishlist-documentation.gitbook.io/the-wishlist-documentation-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://the-wishlist-documentation.gitbook.io/the-wishlist-documentation-docs/customer-rest-api/representations.md).
# Representations
All requests or responses are JSON objects
#### Customer Request
| Field | Type | Description |
| ---------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *customerRef* | string | Retailer assigned customer reference number. This is not a mandatory field. If provided it must be unique across your tenant. |
| *alternateCustomerRef* | string | Retailer assigned optional customer reference number. This is not a mandatory field. If provided it must be unique. |
| *dob* | date | Date of birth of customer in *dd-mm-yyy* format. for example: 28-11-1999 |
| *firstName* | string | First name |
| *lastName* | string | Last name |
| *email* | string | Customers email address. Email is a mandatory field and must be unique within your tenant. |
| *mobile* | string | Mobile phone number |
| *phone* | string | Phone number |
| *vipStatus* | Boolean | Indicates if the customer is a VIP |
| *loyaltyTier* | string | Customer's loyalty tier |
| *spendToNextTier* | string | Amount customer has to spend to reach next loyalty tier |
| *joinedStoreId* | string | Retailer's store reference code for location customer was first created. This should equate to a locationRef in TWC |
| *preferredStore* | string | The store reference code for the customer's preferred store |
| *memberSince* | date | Date the customer joined the retailer's loyalty program |
| *addresses* | array of Address | An array of the Customer's addresses. A customer can have more than one address, but we recommend only storing the primary address |
| *optin\_preferences* | OptinPreferences | This object indicates marketing preferences for email and SMS |
| *attributeGroups* | AttributeGroups | This field may be used to add additional attributes to entities in TWC and in general is available on most entities in The Wishlist Company platform.
"attributeGroups": {
"extra\_attribute\_group1": {
"attributes": {
"customer\_origin": "social\_media",
"category\_affinity": "electronics, cameras, gaming",
},
"description": "any additional attribute you want to add to entities"
},
"retailer\_defined\_name\_of\_group": {
"attributes": {
"retailer\_defined\_attribute1": "user defined attribute value",
"another\_attribute": "another value"
},
"description": "retailer defined properties and its values, flexible data model to add additional properties."
}
}
|
#### Customer Response
Note: The following list shows the primary response fields. The actual response may include additional internal or depreciated fields
| Field | Type | Description |
| ---------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| *id* | string | TWC generated unique ID (internal identifier) of the customer entity. for example: *47235561-a5fe-43d1-a0ff-00b635208abe* |
| *customerRef* | string | Retailer assigned customer identifier. This is not a mandatory field, but if provided it must be unique across your tenant. |
| *alternateCustomerRef* | string | Retailer assigned optional customer reference number. This is not a mandatory field. If provided it must be unique. |
| *dob* | string | Date of birth |
| *firstName* | string | First name |
| *lastName* | string | Last name |
| *email* | string | Customers email address. Email must be unique across your tenant |
| *mobile* | string | Mobile phone number |
| *phone* | string | Phone number |
| *deleted* | string | Indicates if the customer has been deleted |
| *lifetimeOrderValue* | string | Total value of orders for this customer since joining. Calculated automatically by TWC on Shopify, and other platforms provided orders are loaded into TWC |
| *averageSpendPerAnnum* | string | Customer's average spend per year. Calculated automatically TWC on Shopify, and other platforms provided orders are loaded into TWC |
| *running12monthSpend* | string | Customer's spend in the last 12 months. Calculated automatically by TWC on Shopify, and other platforms provided orders are loaded into TWC |
| *totalOrders* | string | Number of orders customer has placed. Calculated automatically by TWC on Shopify, and other platforms provided orders are loaded into TWC |
| *totalSpend* | string | Customer's total spend. Calculated automatically by TWC on Shopify, and other platforms provided orders are loaded into TWC |
| *lastOrderDate* | date | Date and time of the customer's last order. Determined by TWC on Shopify, and other platforms provided orders are loaded into TWC |
| *lastOrderRef* | string | Reference number of the customer's last order. Determined by TWC on Shopify, and other platforms provided orders are loaded into TWC |
| *createdDate* | string | Time and date that the customer was created in TWC |
| *joinedStoreId* | string | Reference number of the store where the customer joined. Equates to a locationRef in TWC |
| *preferredStore* | string | The store reference code for the customer's preferred store |
| *loyaltyTier* | string | Customer's loyalty tier. Note this field is not managed by TWC |
| *spendToNextTier* | string | Amount customer has to spend to reach next loyalty tier. Note this field is NOT calculated by TWC. |
| *memberSince* | string | Date customer joined any loyalty program. Note this field is not managed by TWC |
| *vipStatus* | Boolean | Indicates customer is a VIP |
| *lastModified* | date | Time and date the customer record was last modified |
| *addresses* | array of Address | Customers addresses array. A customer can have more than one address. |
| *optin\_preferences* | OptinPreferences | Indicates marketing preferences for email and SMS. |
| *attributeGroups* | AttributeGroups | This field may be used to add additional attributes to entities in TWC. This field is generally available on most entities in The Wishlist platform.
"attributeGroups": {
"extra\_attribute\_group1": {
"attributes": {
"customer\_origin": "social\_media",
"category\_affinity": "electronics, cameras, gaming",
},
"description": "any additional attribute you want to add to entities"
},
"retailer\_defined\_name\_of\_group": {
"attributes": {
"retailer\_defined\_attribute1": "user defined attribute value",
"another\_attribute": "another value"
},
"description": "retailer defined properties and its values, flexible data model to add additional properties."
}
}
|
#### Customer Address
| Field | Type | Description |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| *address1* | string | Address line 1 |
| *address2* | string | Address line 2 |
| *addressID* | string | Internal TWC identifier |
| *addressRef* | string | Retailer's Address identifier if one exists |
| *city* | string | City |
| *company* | string | Company |
| *email* | string | The email address associated with the address |
| *firstName* | string | The first name of the person associated with the address |
| *lastName* | string | The last name of the person associated with the address |
| *name* | string | The name of the person associated with the address |
| *postcode* | string | Postal code |
| *phone* | string | Address phone number |
| *province* | string | The state or province for the address |
| *provinceCode* | string | Abbreviation for the customer's province or state |
| *country* | string | Country for example: *Australia* |
| *countryCode* | string | Country codes as per [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1). e.g: *AU* for australia |
#### Optin Preferences
| Field | Type | Description |
| ------- | ---------------- | --------------------------- |
| *email* | Optin Preference | Opt In preference for email |
| *sms* | Optin Preference | Opt-in preference for SMS |
#### Optin Preference
| Field | Type | Description |
| ---------------------- | ------- | ---------------------------------------------- |
| *opt\_in\_active* | boolean | Indicates if a customer has opted in |
| *opt\_in\_updated\_at* | date | Date at which optin preferences were updated |
| *opted\_in\_at* | date | Date at which optin preferences were first set |
#### AttributeGroups
| Field | Type | Description |
| ---------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *attributeGroup* | AttributeGroup | This field holds the groups of attributes as a map of \.
"attributeGroups": {
"extra\_attribute\_group1": {
"attributes": {
"customer\_origin": "social\_media",
"category\_affinity": "electronics, cameras, gaming",
},
"description": "any additional attribute you want to add to entities"
},
"retailer\_defined\_name\_of\_group": {
"attributes": {
"retailer\_defined\_attribute1": "user defined attribute value",
"another\_attribute": "another value"
},
"description": "retailer defined properties and its values, flexible data model to add additional properties."
}
}
|
#### AttributeGroup
| Field | Type | Description |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *attributes* | map | This field holds map of attributes as a map of \
e.g.: {
"customer\_origin": "social\_media",
"category\_affinity": "electronics, cameras, gaming",
}
|
| *description* | string | This field is a short description about the attributes captured under field *attributes*. This is only used in the TWC backoffice tools. |