Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Resource Reference Guide

Resource Reference Guide

Cortex resources model the fundamental aspects of ecommerce with each resource encapsulating a single part of the ecommerce process. For example, Cortex has resources for: items, prices, carts, orders, purchases, profiles and many more that are listed below.

Resources are linked together with other related resources into workflows that can be used to perform an action. For example, the workflow to create a new address for a shopper involves retrieving the default profile resource, following the addresses link, and then following the link to the addressform link which is used to create the new address. By following these workflows, you can perform actions such as add an item to a cart, purchase, register a shopper account, perform a search and so on.


addresses

addresses

The Addresses resource family is responsible for the customer's shipping and billing address. This resource allows you to retrieve a logged in customer's addresses, edit existing addresses, and create new addresses.

Shipping Address vs. Billing Addresses

A shipping address is where you ship the physical goods that you purchased in the store. A billing address is the address associated with the paymentmethods used for a purchase. For example, the billing address would be the address on the credit card that is being used for a purchase. Customers choose which billing and shipping address to use for a purchase through the orders resources.

Currently you cannot create an address and label it as a shipping only address or label it as a billing only address. Cortex does not make a distinction between the shipping and billing addresses. Read Billing Address billing addresses retrieves a list of all the customer's addresses; similarly, Read Shipping Address retrieves a list of all the customer's addresses. Future versions of the API may allow the possibility to label what the address is for, but out of the box this API version does not support this functionality.

Addresses

Read an address from a list of addresses.

Workflow

  1. Start with profile.
  2. Read link following rel: addresses.
  3. Read link following rel: element.
  4. Render response.

Response Fields

Type: addresses.address
Name Description Type
"name":

The customer name.

object
"given-name":

The person's given name.

string
"family-name":

The person's family name.

string
"address":

The customer address. Address field names are based on the v.card specification. For more information on this specification, see v.card.

object
"street-address":

The street address.

string
"extended-address":

Extra field for address information. This field is optional.

string
"locality":

The city name.

string
"region":

Valid region codes for this field can be retrieved using the Geographies Resource.

string
"postal-code":

Postal code or zip code.

string
"country-name":

Valid country codes for this field can be retrieved using the Geographies Resource.

string
"phone-number":

Phone number

string
"organization":

The organization

string

Read Shipping Address

Read a shipping address from a list of shipping addresses.

Workflow

  1. Start with profile.
  2. Read link following rel: addresses.
  3. Read link following rel: shippingaddresses.
  4. Read link following rel: element.
  5. Render response.

Response Fields

Type: addresses.address
Name Description Type
"name":

The customer name.

object
"given-name":

The person's given name.

string
"family-name":

The person's family name.

string
"address":

The customer address. Address field names are based on the v.card specification. For more information on this specification, see v.card.

object
"street-address":

The street address.

string
"extended-address":

Extra field for address information. This field is optional.

string
"locality":

The city name.

string
"region":

Valid region codes for this field can be retrieved using the Geographies Resource.

string
"postal-code":

Postal code or zip code.

string
"country-name":

Valid country codes for this field can be retrieved using the Geographies Resource.

string
"phone-number":

Phone number

string
"organization":

The organization

string

Read Profile From Shipping Addresses

Read the profile linked to the shipping address. The workflow starts with the shipping address and then links to the profile.

Workflow

  1. Start with shipping-addresses.
  2. Read link following rel: profile.
  3. Render response.

Response Fields

Type: profiles.profile
Name Description Type
"given-name":

Customer's first name.

string
"family-name":

Customer's last name.

string

Read Default Shipping Address

Read the customer's default shipping addresses.

Workflow

  1. Start with profile.
  2. Read link following rel: addresses.
  3. Read link following rel: shippingaddresses.
  4. Read link following rel: default.
  5. Render response.

Response Fields

Type: addresses.address
Name Description Type
"name":

The customer name.

object
"given-name":

The person's given name.

string
"family-name":

The person's family name.

string
"address":

The customer address. Address field names are based on the v.card specification. For more information on this specification, see v.card.

object
"street-address":

The street address.

string
"extended-address":

Extra field for address information. This field is optional.

string
"locality":

The city name.

string
"region":

Valid region codes for this field can be retrieved using the Geographies Resource.

string
"postal-code":

Postal code or zip code.

string
"country-name":

Valid country codes for this field can be retrieved using the Geographies Resource.

string
"phone-number":

Phone number

string
"organization":

The organization

string

Read Billing Address

Read billing addresses from the list of billing addresses.

Workflow

  1. Start with profile.
  2. Read link following rel: addresses.
  3. Read link following rel: billingaddresses.
  4. Read link following rel: element.
  5. Render response.

Response Fields

Type: addresses.address
Name Description Type
"name":

The customer name.

object
"given-name":

The person's given name.

string
"family-name":

The person's family name.

string
"address":

The customer address. Address field names are based on the v.card specification. For more information on this specification, see v.card.

object
"street-address":

The street address.

string
"extended-address":

Extra field for address information. This field is optional.

string
"locality":

The city name.

string
"region":

Valid region codes for this field can be retrieved using the Geographies Resource.

string
"postal-code":

Postal code or zip code.

string
"country-name":

Valid country codes for this field can be retrieved using the Geographies Resource.

string
"phone-number":

Phone number

string
"organization":

The organization

string

Read Profile From Billing Addresses

Read the profile linked to the billing address. The workflow starts with the billing address and then links to the profile.

Workflow

  1. Start with billing-addresses.
  2. Read link following rel: profile.
  3. Render response.

Response Fields

Type: profiles.profile
Name Description Type
"given-name":

Customer's first name.

string
"family-name":

Customer's last name.

string

Read Default Billing Address

Read the customer's default billing addresses.

Workflow

  1. Start with profile.
  2. Read link following rel: addresses.
  3. Read link following rel: billingaddresses.
  4. Read link following rel: default.
  5. Render response.

Response Fields

Type: addresses.address
Name Description Type
"name":

The customer name.

object
"given-name":

The person's given name.

string
"family-name":

The person's family name.

string
"address":

The customer address. Address field names are based on the v.card specification. For more information on this specification, see v.card.

object
"street-address":

The street address.

string
"extended-address":

Extra field for address information. This field is optional.

string
"locality":

The city name.

string
"region":

Valid region codes for this field can be retrieved using the Geographies Resource.

string
"postal-code":

Postal code or zip code.

string
"country-name":

Valid country codes for this field can be retrieved using the Geographies Resource.

string
"phone-number":

Phone number

string
"organization":

The organization

string

Delete Address

Delete an address.

If the address was selected to use in an order and the address is deleted, the order will show a NeedInfo link.

Workflow

  1. Start with profile.
  2. Read link following rel: addresses.
  3. Read link following rel: element.
  4. Delete address.

Update Address

Update an address.

Workflow

  1. Start with profile.
  2. Read link following rel: addresses.
  3. Read link following rel: element.
  4. Edit the address object with new detail(s).
  5. Update address.

Add Address

Create an address.

Workflow

  1. Start with profile.
  2. Read link following rel: addresses.
  3. Read link following rel: addressform.
  4. Fill out the form.
  5. Create form to link rel: createaddressaction.

availabilities

Display the item and line item's availability. The availability identifies the item's purchasability. For example, in Elastic Path Commerce Engine the following states are available:

  • ALWAYS
  • NOT_AVAILABLE
  • AVAILABLE_FOR_BACK_ORDER
  • AVAILABLE_FOR_PRE_ORDER

Read Cart Line Item Availability

Read a line item's availability. The availability rule identifies the purchasable state of the item(s) in the line item.

Workflow

  1. Start with cart.
  2. Read link following rel: lineitems.
  3. Read link following rel: element.
  4. Read link following rel: availability.
  5. Render response.

Response Fields

Type: availabilities.availability
Name Description Type
"state":

The state of availability for an item or line item. In Elastic Path Commerce Engine, the states are:

  • ALWAYS
  • NOT_AVAILABLE
  • AVAILABLE_FOR_BACK_ORDER
  • AVAILABLE_FOR_PRE_ORDER
string
"release-date":

Optional property. This is the date the item becomes available for purchase. In Elastic Path Commerce Engine, release-date is only visible when the item is available for pre-order.

object
"value":

The millisecond value of the date in Epoch time.

long
"display-value":

The formatted date value to display on the client application.

string

Read Item Availability

Read an item's availability. The availability rule identifies the item's purchasability.

Workflow

  1. Start with item.
  2. Read link following rel: availability.
  3. Render response.

Response Fields

Type: availabilities.availability
Name Description Type
"state":

The state of availability for an item or line item. In Elastic Path Commerce Engine, the states are:

  • ALWAYS
  • NOT_AVAILABLE
  • AVAILABLE_FOR_BACK_ORDER
  • AVAILABLE_FOR_PRE_ORDER
string
"release-date":

Optional property. This is the date the item becomes available for purchase. In Elastic Path Commerce Engine, release-date is only visible when the item is available for pre-order.

object
"value":

The millisecond value of the date in Epoch time.

long
"display-value":

The formatted date value to display on the client application.

string

carts

Entry Point: /carts/{scope}/default

A cart is basically a basket that customers put items into that they want to purchase. While Cortex API's shopping cart has this as its core functionality, there is much more to this shopping cart than just that.

Key concepts developers should know about carts:

  • You can't delete a cart, you can only empty a cart of its contents.

  • The do not need to instantiate the cart, a cart is always available.

  • The do not need to create an order for the cart, an order is always available.

  • Cortex automatically persists carts between customer sessions so a customer can log on through a mobile phone and then log on through another device to complete the purchase

    Cart memberships resource

A cart's line items is a collection of items that have been added to a cart. A line item can have one or more of the same items in it. For example, one line item can have seven Rocker T-Shirt or a single Rocker T-Shirt, but it won't have one Rocker T-Shirt and a song track. The song track and T-shirt would be in separate line items.

    Items are added to the user's default cart by using a form.

Read Line Item

Retrieve a single line item from a shopper's cart.

Workflow

  1. Start with cart.
  2. Read link following rel: lineitems.
  3. Read link following rel: element.
  4. Render response.

Response Fields

Type: carts.line-item
Name Description Type
"quantity":

The total number of items in the line item.

integer
"configuration":

The details of the line item configuration.

object

Update Line Item

Update the number of items in a line item. For example, if you have 4 Rockstar T-Shirts in a line item, you can use this method to remove 3 of the t-shirts and leave 1 T-shirt in the cart.

Workflow

  1. Start with cart.
  2. Read link following rel: lineitems.
  3. Read link following rel: element.
  4. Edit the line-item object with new detail(s).
  5. Update line-item.

Delete Line Item

Delete a line item from the cart.

Workflow

  1. Start with cart.
  2. Read link following rel: lineitems.
  3. Read link following rel: element.
  4. Delete line-item.

Empty Cart

Remove all line items from the cart.

Workflow

  1. Start with cart.
  2. Read link following rel: lineitems.
  3. Delete line-items.

Add Item To Default Cart

Add an item to the user's default cart.

Workflow

  1. Start with item.
  2. Read link following rel: addtocartform.
  3. Fill out the form.
  4. Create form to link rel: addtodefaultcartaction.

Read Line Item Cart

Retrieve the cart that has the given line item. This workflow is useful when you need to determine which cart the line item belongs to.

Workflow

  1. Start with [line-item][line-item].
  2. Read link following rel: cart.
  3. Render response.

Response Fields

Type: carts.cart
Name Description Type
"total-quantity":

Lists the total number of items in the cart.

integer

Read Default Cart

Retrieve the shopper's default cart. When using default in the cart's URI, default evaluates to the logged in shopper's cart I.D. See the main Cortex documentation for more information on default.

Workflow

  1. Start with default-cart.
  2. Render response.

Response Fields

Type: carts.cart
Name Description Type
"total-quantity":

Lists the total number of items in the cart.

integer

Read Cart

Retrieve a cart with a specific cart identifier.

Workflow

  1. Start with cart.
  2. Render response.

Response Fields

Type: carts.cart
Name Description Type
"total-quantity":

Lists the total number of items in the cart.

integer

Read Cart Memberships

Retrieves the list of carts that the item has been added to.

GET:{cortex}/carts/memberships/{item_uri}

The list is empty if the item is not in your cart.

Workflow

  1. Start with item.
  2. Read link following rel: cartmemberships.
  3. Render response.

Response Fields


coupons

A coupon is a code, consisting of letters or numbers that a shopper can apply to an order. When a coupon is applied to an order, it can trigger a promotion which inturn discounts or adds additional incentives to the order.

Coupons for an order can be managed through the coupon info resource. This is where coupons that are applied to an order are listed, as well as a form to apply new coupons. Each coupon is linked to the promotions it triggered. If no promotions were triggered then no promotion link will be present.

Coupons for a purchase are coupons that were applied to the shopper's purchase.

Read Coupons Applied To Order

Read coupons applied to the order.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: couponinfo.
  4. Read link following rel: coupon.
  5. Render response.

Response Fields

Type: coupons.coupon
Name Description Type
"code":

The coupon code.

string

Apply Coupon To Order

Apply a coupon to the order.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: couponinfo.
  4. Read link following rel: couponform.
  5. Fill out the form.
  6. Create form to link rel: applycouponaction.

Remove A Coupon From Order

Remove an applied coupon from the order.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: couponinfo.
  4. Read link following rel: coupon.
  5. Delete order-coupon.

Read Coupons Appled To Purchase

Read a coupon applied to the purchase.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: coupons.
  4. Read link following rel: element.
  5. Render response.

Response Fields

Type: coupons.coupon
Name Description Type
"code":

The coupon code.

string

datapolicies

The data policies resource retrieves the data policies associated with a customer

Provide data policy consent access to the user.

Read Data Policies For Store From Profile

Retrieve the list of data policies for a store from a customer profile, based on the data policy segment header(s).

Workflow

  1. Start with profile.
  2. Read link following rel: data-policies.
  3. Render response.

Response Fields

Read Data Policies For Store From Root

Retrieve the list of data policies for a store from root, based on the data policy segment header(s).

Workflow

  1. Start with [data-policies][data-policies].
  2. Render response.

Response Fields

Read Data Policy

Retrieves a data policy if a valid data policy segment is provided.

Workflow

  1. Start with profile.
  2. Read link following rel: data-policies.
  3. Read link following rel: data-policy.
  4. Render response.

Response Fields

Type: data-policies.data-policy
Name Description Type
"policy-reference-key":

The data policy reference key.

string
"policy-name":

The data policy name.

string
"data-policy-consent":

The data policy consent flag.

string

Read Data Policy Consent Form

Retrieve a data policy consent form for a data policy.

Workflow

  1. Start with profile.
  2. Read link following rel: data-policies.
  3. Read link following rel: data-policy.
  4. Read link following rel: data-policy-consent-form.
  5. Render response.

Response Fields

Add Data Policy Consent

Add data policy consent for a customer.

Workflow

  1. Start with profile.
  2. Read link following rel: data-policies.
  3. Read link following rel: data-policy.
  4. Read link following rel: datapolicyconsentform.
  5. Fill out the form.
  6. Create form to link rel: consentaction.

discounts

The Discounts resource provides the discount amount for a cart or the discount amount for a purchase.

Read Discount Applied To Cart

Retrieve the discount amount applied to a cart total, excluding line item discounts.

Workflow

  1. Start with cart.
  2. Read link following rel: discount.
  3. Render response.

Response Fields

Type: discounts.discount
Name Description Type
"discount":

The amount of the discount. Similar to prices, discount is an array because the total may be a combination of amounts in multiple currencies, for example $20 CAD + 20000 points.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string

Read Discount Applied To Purchase

Retrieve the discount amount applied to a purchase.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: discount.
  4. Render response.

Response Fields

Type: discounts.discount
Name Description Type
"discount":

The amount of the discount. Similar to prices, discount is an array because the total may be a combination of amounts in multiple currencies, for example $20 CAD + 20000 points.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string

emails

The emails resource stores a customer's emails.

Add an email to a logged in customer.

Out of the box, customers can have only one email, which is their user name. If you create a new email for a registered customer, this changes the customer's user name.

Read Email

Read an email from a list of the customer's emails.

Workflow

  1. Start with profile.
  2. Read link following rel: emails.
  3. Read link following rel: element.
  4. Render response.

Response Fields

Type: emails.email
Name Description Type
"email":

The email address.

string

Add Email

Add an email to a logged in customer. Out of the box, customers can have only one email, which is their user name. If you create a new email for a registered customer, this changes the customer's user name.

Workflow

  1. Start with profile.
  2. Read link following rel: emails.
  3. Read link following rel: emailform.
  4. Fill out the form.
  5. Create form to link rel: createemailaction.

geographies

Entry Point: /geographies/{scope}/countries

The geographies resource family provides access to location related data, including lists of countries, and lists of regions by country.

Read Countries

Retrieve a list of countries available to a scope.

Workflow

  1. Start with countries.
  2. Render response.

Response Fields

Read Country

Read a single country.

Workflow

  1. Start with countries.
  2. Read link following rel: element.
  3. Render response.

Response Fields

Type: geographies.country
Name Description Type
"name":

The name or code of the country.

string
"display-name":

The localized country name, intended for display in the client application.

string

Read Region

Read a single region in a country.

Workflow

  1. Start with countries.
  2. Read link following rel: element.
  3. Read link following rel: regions.
  4. Read link following rel: element.
  5. Render response.

Response Fields

Type: geographies.region
Name Description Type
"name":

The name or code of the region.

string
"display-name":

The localized region name, intended for display in the client application.

string

itemdefinitions

An item definition describes the item. The item's name, media assets (pictures of the item), options, components, from price, and details describing the item's characteristics are all part of the item definitions. Not every item definition contains assets, options, components, etc. What is available on the item definition depends on the item and how your storefront has implemented Cortex API. Some resources may be customized for your implementation, so more, or even less details may exist.

Read Item Definition Component

Read the item definition component from the list of available components.

Workflow

  1. Start with item.
  2. Read link following rel: definition.
  3. Read link following rel: components.
  4. Read link following rel: element.
  5. Render response.

Response Fields

Type: itemdefinitions.item-definition-component
Name Description Type
"display-name":

The localized name of the item definition component, intended for display in the client application.

string
"details":

The details of the item definition component.

array
"display-name":

The formatted string to display on the client.

string
"name":

The name used by the Cortex system.

string
"display-value":

The formatted string to display on the client.

string
"value":

The raw value.

any
"quantity":

The quantity of components.

integer

Read Nested Item Definition Components

Read an single nested item definition component.

Workflow

  1. Start with item.
  2. Read link following rel: definition.
  3. Read link following rel: components.
  4. Read link following rel: element.
  5. Read link following rel: components.
  6. Read link following rel: element.
  7. Render response.

Response Fields

Type: itemdefinitions.item-definition-component
Name Description Type
"display-name":

The localized name of the item definition component, intended for display in the client application.

string
"details":

The details of the item definition component.

array
"display-name":

The formatted string to display on the client.

string
"name":

The name used by the Cortex system.

string
"display-value":

The formatted string to display on the client.

string
"value":

The raw value.

any
"quantity":

The quantity of components.

integer

Read Item Definition Component To Standalone Item

Read the component's stand alone item. Some components can be purchased separately.

Workflow

  1. Start with item.
  2. Read link following rel: definition.
  3. Read link following rel: components.
  4. Read link following rel: element.
  5. Read link following rel: standaloneitem.
  6. Render response.

Response Fields

None.

Read Item Definition

Read the item definition from the item.

Workflow

  1. Start with item.
  2. Read link following rel: definition.
  3. Render response.

Response Fields

Type: itemdefinitions.item-definition
Name Description Type
"display-name":

The localized name of the item definition, intended for display in the client application.

string
"details":

The details of the item definition.

array
"display-name":

The formatted string to display on the client.

string
"name":

The name used by the Cortex system.

string
"display-value":

The formatted string to display on the client.

string
"value":

The raw value.

any

Read Item Definition Option

Read the item definition option from the list of available options.

Workflow

  1. Start with item.
  2. Read link following rel: definition.
  3. Read link following rel: options.
  4. Read link following rel: element.
  5. Render response.

Response Fields

Type: itemdefinitions.item-definition-option
Name Description Type
"display-name":

The localized name of the item definition option, intended for display in the client application.

string
"name":

The name of the item definition option.

string

Read Item Definition Option Value

Read the item definition option value.

Workflow

  1. Start with item.
  2. Read link following rel: definition.
  3. Read link following rel: options.
  4. Read link following rel: element.
  5. Read link following rel: value.
  6. Render response.

Response Fields

Type: itemdefinitions.item-definition-option-value
Name Description Type
"display-name":

The localized name of the item definition option value, intended for display in the client application.

string
"name":

The name of the item definition option value.

string

items

An item is a purchasable good like a T-shirt, a movie, a song, a subscription, etc. The Items resource's responsibility is to simply identify an item. This should not be confused with itemdefinitions, which are descriptions of the item.

Items can be discovered by using the following resources:

Read Item

Retrieve an item with a specific item ID.

Workflow

  1. Start with item.
  2. Render response.

Response Fields

None.


itemselections

The Items selections resource provides Selectors to allow customers to select item options.

    The Items selections resource provides a selector to allow customers to select item option's value.

Select Item Definition Option

Select an item definition option.

Workflow

  1. Start with item.
  2. Read link following rel: definition.
  3. Read link following rel: options.
  4. Read link following rel: element.
  5. Read link following rel: selector.
  6. Read link following rel: choice.
  7. Create choice to link rel: selectaction.

lookups

A lookup is a means of looking up an item.

Search Item By Code

Search for an item by item code.

Workflow

  1. Start with lookups.
  2. Read link following rel: itemlookupform.
  3. Fill out the form.
  4. Create form to link rel: itemlookupaction.

Read Code For Item

Read the code of an item.

Workflow

  1. Start with item.
  2. Read link following rel: code.
  3. Render response.

Response Fields

Type: elasticpath.items.code
Name Description Type
"code":

The sku code.

string

Lookup Batch Items

Look up a batch of items with a list of codes.

Workflow

  1. Start with lookups.
  2. Read link following rel: batchitemslookupform.
  3. Fill out the form.
  4. Create form to link rel: batchlookupaction.

Search Navigation By Code

Search for a Navigation item by category code.

Workflow

  1. Start with lookups.
  2. Read link following rel: navigationlookupform.
  3. Fill out the form.
  4. Create form to link rel: navigationlookupaction.

navigations

Entry Point: /navigations/{scope}

Navigation nodes organize your store's catalogs by providing containers to group related items into. Each navigation node can contain details (attributes), any number of items, and other child nodes. Your company's marketers create these navigation nodes, also known as categories, using the Commerce Manager. You may need to coordinate with your marketers for how the navigation nodes should be used in your client application.

Read Navigation

Read a single navigation node.

Workflow

  1. Start with navigations.
  2. Read link following rel: element.
  3. Render response.

Response Fields

Type: elasticpath.navigations.node
Name Description Type
"name":

The Cortex system's name for the node.

string
"display-name":

The localized name of the node, intended for display in the client application.

string
"details":

An array of the navigation node's attributes. Attributes describe the details of the navigation node, like the node's name, description, associated subcategories, etc. Attributes are different each store. To get a list of navigation attributes, you'll need to coordinate with your store marketer who creates these navigation nodes and attributes.

array
"display-name":

The formatted string to display on the client.

string
"name":

The name used by the Cortex system.

string
"display-value":

The formatted string to display on the client.

string
"value":

The raw value.

any

Read Navigation Item

Retrieve a paginated list of items associated with the navigation node.

Workflow

  1. Start with [navigation][navigation].
  2. Read link following rel: items.
  3. Read link following rel: element.
  4. Render response.

Response Fields

None.

Read Navigation To Child

Read a navigation node's child node.

Workflow

  1. Start with [navigation][navigation].
  2. Read link following rel: child.
  3. Render response.

Response Fields

Type: elasticpath.navigations.node
Name Description Type
"name":

The Cortex system's name for the node.

string
"display-name":

The localized name of the node, intended for display in the client application.

string
"details":

An array of the navigation node's attributes. Attributes describe the details of the navigation node, like the node's name, description, associated subcategories, etc. Attributes are different each store. To get a list of navigation attributes, you'll need to coordinate with your store marketer who creates these navigation nodes and attributes.

array
"display-name":

The formatted string to display on the client.

string
"name":

The name used by the Cortex system.

string
"display-value":

The formatted string to display on the client.

string
"value":

The raw value.

any

Read Navigation To Parent

Read a navigation node's parent node.

Workflow

  1. Start with [navigation][navigation].
  2. Read link following rel: parent.
  3. Render response.

Response Fields

Type: elasticpath.navigations.node
Name Description Type
"name":

The Cortex system's name for the node.

string
"display-name":

The localized name of the node, intended for display in the client application.

string
"details":

An array of the navigation node's attributes. Attributes describe the details of the navigation node, like the node's name, description, associated subcategories, etc. Attributes are different each store. To get a list of navigation attributes, you'll need to coordinate with your store marketer who creates these navigation nodes and attributes.

array
"display-name":

The formatted string to display on the client.

string
"name":

The name used by the Cortex system.

string
"display-value":

The formatted string to display on the client.

string
"value":

The raw value.

any

orders

An order is a list of intentions Cortex API will undertake to complete a purchase. For example, an order lists the billing and shipping address to use for the purchase, shipping options (Canada Post, FedEx, etc), paymentmethods to use for the purchase, the cart containing the items to purchase, and the taxes to pay for the purchase. Once the order is POSTed to a purchase, Cortex API executes the purchase based on the intentions in the order.

Just like the cart, an order is always available, persisted between sessions, and is updated automatically. For example, if a customer removes an item from their cart, the order is updated to remove the item. Once the order is POSTed to a purchase, the order is cleared and a new order is created for the customer.

The order contains NeedInfo links if the billing address, shipping address, shipping option or the payment methods haven't been selected.

    Advisors on the order resource

Billing Address Info:

The Billing address info resource provides the customer with a selector to select the billing address to use for the purchase and an addressform to create a billing address to use for the purchase. The billing address is the address that is related to the payment means, which in some cases is the address your credit card uses.

Deliveries:

The deliveries resource groups the shipment details, which are the how and where your goods are being shipped, for your orders. Out of the box, you can't split orders into different shipments, so when you get the list of delivery elements for an order only one element appears in the list. The order's shipment details are specified through the shipmentdetails resource.

Use a selector to select the billing address to use for the purchase. Follow the workflow to read the billing address info and then create a choice to select the billing address to use for the purchase.

Read Order Delivery

Read a delivery from a list of deliveries

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: deliveries.
  4. Read link following rel: element.
  5. Render response.

Response Fields

Type: orders.delivery
Name Description Type
"delivery-type":

The delivery type for an order.

string

Billingaddress Info Selector

Use a selector to select the billing address to use for the purchase. Follow the workflow to read the billing address info and then create a choice to select the billing address to use for the purchase.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: billingaddressinfo.
  4. Read link following rel: selector.
  5. Read link following rel: chosen.
  6. Create choice to link rel: selectaction.

Read Billing Address

Read the currently selected billingaddress for the order.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: billingaddressinfo.
  4. Read link following rel: billingaddress.
  5. Render response.

Response Fields

Type: addresses.address
Name Description Type
"name":

The customer name.

object
"given-name":

The person's given name.

string
"family-name":

The person's family name.

string
"address":

The customer address. Address field names are based on the v.card specification. For more information on this specification, see v.card.

object
"street-address":

The street address.

string
"extended-address":

Extra field for address information. This field is optional.

string
"locality":

The city name.

string
"region":

Valid region codes for this field can be retrieved using the Geographies Resource.

string
"postal-code":

Postal code or zip code.

string
"country-name":

Valid country codes for this field can be retrieved using the Geographies Resource.

string
"phone-number":

Phone number

string
"organization":

The organization

string

Read Billingaddress Needinfo From Order

When a billingaddress needinfo appears on the order, it means the billingaddress has not been selected for the purchase. Follow the workflow to read the billingaddress needinfo.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: needinfo.
  4. Render response.

Response Fields

Type: elasticpath.controls.info
Name Description Type
"name":

The info object's name.

string

Read Billingaddress Needinfo From Purchaseform

Read billingaddress needinfo.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: purchaseform.
  4. Read link following rel: needinfo.
  5. Render response.

Response Fields

Type: elasticpath.controls.info
Name Description Type
"name":

The info object's name.

string

Read Order

Retrieves the cart's order. An order may have NeedInfos. Needinfos identify a condition that must be satisfied before a transaction can complete. Needinfos link to a selector where the customer can select the missing condition. Once the Needinfos are satisfied the order can be submitted to a purchase.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Render response.

Response Fields

None.

Read Order Email

Read email address associated with order.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: emailinfo.
  4. Read link following rel: email.
  5. Render response.

Response Fields

Type: emails.email
Name Description Type
"email":

The email address.

string

Read Email Needinfo From Order

Read the order's email needinfo. When an email needinfo appears on the order, it means the customer's email has not been selected for the purchase. Likely, this customer does not have an account. Follow the workflow to read the email needinfo.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: needinfo.
  4. Render response.

Response Fields

Type: elasticpath.controls.info
Name Description Type
"name":

The info object's name.

string

Read Email Needinfo From Purchaseform

Read order email needinfo. When an email needinfo appears on the purchase form, it means the customer's email has not been selected for the purchase. Likely, this customer does not have an account. Follow the workflow to read the email needinfo.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: purchaseform.
  4. Read link following rel: needinfo.
  5. Render response.

Response Fields

Type: elasticpath.controls.info
Name Description Type
"name":

The info object's name.

string

prices

Prices describe the amount of money required to purchase an item or items. The prices resource server links prices to: items, cart line items and item definitions

Read Item Price

Read the unit price of an item. The unit price of an item is the price for one unit (quantity = 1)

Workflow

  1. Start with item.
  2. Read link following rel: price.
  3. Render response.

Response Fields

Type: elasticpath.prices.item-price
Name Description Type
"list-price":

The unit price of an item before catalog discounts are applied.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string
"purchase-price":

The unit price of an item after catalog discounts are applied.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string

Read Cart Line Item Price

Read the unit price of a cart line item. The unit price of a cart line item is the price for one unit when a given quantity is purchased (the line item quantity).

Workflow

  1. Start with cart.
  2. Read link following rel: lineitems.
  3. Read link following rel: element.
  4. Read link following rel: price.
  5. Render response.

Response Fields

Type: elasticpath.prices.cart-line-item-price
Name Description Type
"list-price":

The unit price of an item in the shopper's cart before shopping cart discounts are applied.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string
"purchase-price":

The unit price of an item in the shopper's cart after shopping cart discounts are applied. This represents the price the shopper will actually pay for each unit. If no discounts have been applied, the list and purchase price will be the same.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string

Read Lowest Price Of Item Options

Read the price of the item option with the lowest price. This link will only appear if the item has options.

Workflow

  1. Start with item.
  2. Read link following rel: definition.
  3. Read link following rel: fromprice.
  4. Render response.

Response Fields

Type: elasticpath.prices.price-range
Name Description Type
"from-price":

The price of the item's least expensive option.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string

Read Shipment Line Item Price

Retrieves the price of a shipment line item.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: shipments.
  4. Read link following rel: element.
  5. Read link following rel: lineitems.
  6. Read link following rel: element.
  7. Read link following rel: price.
  8. Render response.

Response Fields

Type: elasticpath.prices.shipment-line-item-price
Name Description Type
"list-price":

The price of a shipment line item before discounts are applied.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string
"purchase-price":

The price of a shipment line item after discounts are applied. If no discounts have been applied, the list and purchase price will be the same.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string

profiles

Entry Point: /profiles/{scope}/default

The profiles resource provides access to the currently logged in customer and his/her details. Using the resource you can retrieve and update a customer's first name, last name, username, addresses. You can also retrieve the customer's purchases and paymentmethods through this resource.

Alias Default Profile

Retrieve the customer's default profile.

Workflow

  1. Start with default-profile.
  2. Render response.

Response Fields

Type: profiles.profile
Name Description Type
"given-name":

Customer's first name.

string
"family-name":

Customer's last name.

string

Read Profile

Retrieve the customer's first name, last name, username, addresses, and link to the customer's paymentmethods.

Workflow

  1. Start with profile.
  2. Render response.

Response Fields

Type: profiles.profile
Name Description Type
"given-name":

Customer's first name.

string
"family-name":

Customer's last name.

string

Read Purchases From Profile

Retrieve a list of purchases for the logged in customer.

Workflow

  1. Start with profile.
  2. Read link following rel: purchases.
  3. Render response.

Response Fields

Update Profile

Update the customer's profile.

Workflow

  1. Start with profile.
  2. Edit the profile object with new detail(s).
  3. Update profile.

promotions

Promotions are incentives offered to shoppers to promote the purchase of items in a store. A store’s marketer creates promotions and defines a set of conditions that must be met before the promotion is applied to a given shopper. Promotions may trigger discounts or may trigger other incentives such as free items. When a promotion triggers a discount, the discounts are automatically applied to the item price, cart line item price, shipping option cost, line items total, cart total, and the order total.

Promotions are linked to a number of different resources:

  • Promotions - The promotions resource provides a list of all the promotions available for the store.
  • Items - Promotions are linked to items when a promotion exists for that item and the shopper is eligible to receive the promotion.
  • Carts - Promotions are linked to carts when the contents of the shopper's cart meet the conditions of the promotion.
  • Cart line items - Promotions are linked to cart line items when the line item meets the conditions of the promotion.
  • Shipping options - Promotions are linked to shipping options on an order shipment when the option meets the conditions of the promotion.
  • Purchases - Promotions are linked to purchases when the purchase had promotions applied to it.
  • Coupons - Promotion are linked to a coupon when the coupon triggered the promotions to apply.

Read Applied Item Promotions

Retrieve promotions applied to an item.

Workflow

  1. Start with item.
  2. Read link following rel: appliedpromotions.
  3. Read link following rel: element.
  4. Render response.

Response Fields

Type: promotions.promotion
Name Description Type
"name":

The promotion identifier.

string
"display-name":

The promotion's localized name, intended for display in the client application.

string
"display-description":

The promotion's localized marketing description, intended for display in the client application.

string
"display-conditions":

The promotion's localized terms and conditions, intended for display in the client application.

string

Read Applied Cart Promotions

Retrieve promotions applied to a cart.

Workflow

  1. Start with cart.
  2. Read link following rel: appliedpromotions.
  3. Read link following rel: element.
  4. Render response.

Response Fields

Type: promotions.promotion
Name Description Type
"name":

The promotion identifier.

string
"display-name":

The promotion's localized name, intended for display in the client application.

string
"display-description":

The promotion's localized marketing description, intended for display in the client application.

string
"display-conditions":

The promotion's localized terms and conditions, intended for display in the client application.

string

Read Applied Cart Line Item Promotions

Retrieve the promotions applied to a cart line item.

Workflow

  1. Start with cart.
  2. Read link following rel: lineitems.
  3. Read link following rel: element.
  4. Read link following rel: appliedpromotions.
  5. Read link following rel: element.
  6. Render response.

Response Fields

Type: promotions.promotion
Name Description Type
"name":

The promotion identifier.

string
"display-name":

The promotion's localized name, intended for display in the client application.

string
"display-description":

The promotion's localized marketing description, intended for display in the client application.

string
"display-conditions":

The promotion's localized terms and conditions, intended for display in the client application.

string

Read Applied Shipping Option Promotions

Retrieve promotions applied to a shipping option.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: deliveries.
  4. Read link following rel: element.
  5. Read link following rel: shippingoptioninfo.
  6. Read link following rel: selector.
  7. Read link following rel: chosen.
  8. Read link following rel: null.
  9. Read link following rel: appliedpromotions.
  10. Read link following rel: element.
  11. Render response.

Response Fields

Type: promotions.promotion
Name Description Type
"name":

The promotion identifier.

string
"display-name":

The promotion's localized name, intended for display in the client application.

string
"display-description":

The promotion's localized marketing description, intended for display in the client application.

string
"display-conditions":

The promotion's localized terms and conditions, intended for display in the client application.

string

Read Promotions Triggered By Order Coupon

Retrieve a promotion trigged by a coupon on an order.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: couponinfo.
  4. Read link following rel: coupon.
  5. Read link following rel: promotion.
  6. Render response.

Response Fields

Type: promotions.promotion
Name Description Type
"name":

The promotion identifier.

string
"display-name":

The promotion's localized name, intended for display in the client application.

string
"display-description":

The promotion's localized marketing description, intended for display in the client application.

string
"display-conditions":

The promotion's localized terms and conditions, intended for display in the client application.

string

Read Applied Purchase Promotions

Retrieve promotions applied to a purchase.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: appliedpromotions.
  4. Read link following rel: element.
  5. Render response.

Response Fields

Type: promotions.promotion
Name Description Type
"name":

The promotion identifier.

string
"display-name":

The promotion's localized name, intended for display in the client application.

string
"display-description":

The promotion's localized marketing description, intended for display in the client application.

string
"display-conditions":

The promotion's localized terms and conditions, intended for display in the client application.

string

Read Promotions Triggered By Purchase Coupon

Retrieve a promotion trigged by a coupon on a purchase.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: coupons.
  4. Read link following rel: element.
  5. Read link following rel: promotion.
  6. Render response.

Response Fields

Type: promotions.promotion
Name Description Type
"name":

The promotion identifier.

string
"display-name":

The promotion's localized name, intended for display in the client application.

string
"display-description":

The promotion's localized marketing description, intended for display in the client application.

string
"display-conditions":

The promotion's localized terms and conditions, intended for display in the client application.

string

Read Possible Item Promotions

Retrieve possible promotions for an item. This API is currently not available.

Workflow

  1. Start with item.
  2. Read link following rel: possiblepromotions.
  3. Read link following rel: element.
  4. Render response.

Response Fields

Type: promotions.promotion
Name Description Type
"name":

The promotion identifier.

string
"display-name":

The promotion's localized name, intended for display in the client application.

string
"display-description":

The promotion's localized marketing description, intended for display in the client application.

string
"display-conditions":

The promotion's localized terms and conditions, intended for display in the client application.

string

Read Possible Cart Promotions

Retrieve possible promotions for a cart. This API is currently not available.

Workflow

  1. Start with cart.
  2. Read link following rel: possiblepromotions.
  3. Read link following rel: element.
  4. Render response.

Response Fields

Type: promotions.promotion
Name Description Type
"name":

The promotion identifier.

string
"display-name":

The promotion's localized name, intended for display in the client application.

string
"display-description":

The promotion's localized marketing description, intended for display in the client application.

string
"display-conditions":

The promotion's localized terms and conditions, intended for display in the client application.

string

purchases

Entry Point: /purchases/{scope}

A purchase is a receipt of an executed order. A Purchase lists the order's total cost, purchase date, purchase status (COMPLETE or FAILED), tax paid, paymentmeans, which lists the billing and shipping details as well as customer's paymentmethods, and line items, which are lists of the items the customer purchased.

Each time customers make successful purchases, Cortex API records them in its database. Using the purchases resource, client developers can retrieve the customer's purchase history, which allows customers to inspect their previous purchases, check for correctness, and track the purchase's status. Cortex API records each successful purchase and the last failed purchase. Cortex API does not track each failed purchase, it only records the last failed purchase. Once the purchase completes, the failed purchase is removed from the record and a successful purchase is recorded.

    Advisors on the purchase form

The Paymentmeans resource is responsible for recording a purchase's billing details, such as a customer's billing address and paymentmethod.

Purchase line items are collections of items the customer purchased. Each line item can contain one or more of the same item, but will not have two different items. For example, one line item can have 7 Rock-Star t-shirts or one Rock-Star t-shirt, but it won't have one Rock-Star t-shirt and a Song track. The Song track and t-shirt would be in separate line items.

    Submit the purchase form to complete the purchase.

Purchases List

Retrieve a customer's purchase.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Render response.

Response Fields

Type: purchases.purchase
Name Description Type
"purchase-number":

Purchase number associated with the purchase. This is the reference customers use if they need to communicate with the store's customer service representative.

string
"status":

Indicates the status of the purchase. The following are possible status values:

  • IN_PROGRESS - The purchase is being processed.
  • COMPLETED - The purchase is processed.
  • CANCELLED - The purchase is cancelled.
string
"monetary-total":

The total cost paid for the purchase, including taxes.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string
"taxes":

The taxes for the purchase

array
"title":

The name of the tax.

string
"tax-total":

The total amount of tax paid for the purchase.

object
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string
"purchase-date":

The date on which the purchase was made.

object
"value":

The millisecond value of the date in Epoch time.

long
"display-value":

The formatted date value to display on the client application.

string

Read Purchase Billing Address

Read the billing address for the purchase.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: billingaddress.
  4. Render response.

Response Fields

Type: addresses.address
Name Description Type
"name":

The customer name.

object
"given-name":

The person's given name.

string
"family-name":

The person's family name.

string
"address":

The customer address. Address field names are based on the v.card specification. For more information on this specification, see v.card.

object
"street-address":

The street address.

string
"extended-address":

Extra field for address information. This field is optional.

string
"locality":

The city name.

string
"region":

Valid region codes for this field can be retrieved using the Geographies Resource.

string
"postal-code":

Postal code or zip code.

string
"country-name":

Valid country codes for this field can be retrieved using the Geographies Resource.

string
"phone-number":

Phone number

string
"organization":

The organization

string

Create Purchase

Submit the purchase form to complete the purchase.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: purchaseform.
  4. Fill out the form.
  5. Create form to link rel: submitorderaction.

Read Purchase Lookup Form

Retrieve the purchase lookup form.

Workflow

  1. Start with lookups.
  2. Read link following rel: purchaselookupform.
  3. Render response.

Response Fields

Lookup Purchase By Number

Look up a purchase by the purchase number.

Workflow

  1. Start with lookups.
  2. Read link following rel: purchaselookupform.
  3. Fill out the form.
  4. Create form to link rel: purchaselookupaction.

Read Purchase Line Item

Retrieve a purchase's line item, which includes details on the item that was purchased such as item name, quantity purchased, and cost.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: lineitems.
  4. Read link following rel: element.
  5. Render response.

Response Fields

Type: purchases.line-item
Name Description Type
"name":

The name of the item that was purchased.

string
"quantity":

The number of items that were purchased.

integer
"configuration":

The Fields associated with the purchase line item (Dictionary of String/Strings)

object
"line-extension-tax":

The tax paid for the purchased item(s).

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string
"line-extension-amount":

The purchase price of the item(s), excluding taxes.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string
"line-extension-total":

The total amount paid for the item(s), including taxes.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string

Read Purchase Line Item Option

Read the option for the item purchased by the customer.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: lineitems.
  4. Read link following rel: element.
  5. Read link following rel: options.
  6. Read link following rel: element.
  7. Render response.

Response Fields

Type: purchases.option
Name Description Type
"name":

The name of the item option.

string
"display-name":

The localized name of the item option, intended for display in the client application.

string
"selected-value-id":

The id of the selected value.

string
"option-id":

The id of the option.

string

Purchase Line Item Option Value

The purchase line item option value.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: lineitems.
  4. Read link following rel: element.
  5. Read link following rel: options.
  6. Read link following rel: element.
  7. Read link following rel: value.
  8. Render response.

Response Fields

Type: purchases.value
Name Description Type
"name":

The name of the item option.

string
"display-name":

The localized name of the option name, intended for display in the client application.

string

Purchase Line Item Components

Read the component for the item purchased by the customer.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: lineitems.
  4. Read link following rel: element.
  5. Read link following rel: components.
  6. Read link following rel: element.
  7. Render response.

Response Fields

Type: purchases.line-item
Name Description Type
"name":

The name of the item that was purchased.

string
"quantity":

The number of items that were purchased.

integer
"configuration":

The Fields associated with the purchase line item (Dictionary of String/Strings)

object
"line-extension-tax":

The tax paid for the purchased item(s).

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string
"line-extension-amount":

The purchase price of the item(s), excluding taxes.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string
"line-extension-total":

The total amount paid for the item(s), including taxes.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string

Read Paymentmean

Read a payment mean from a list of payment means.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: paymentmeans.
  4. Read link following rel: element.
  5. Render response.

Response Fields

None.


recommendations

Recommendations suggest additional items that may interest shoppers. For example, if a shopper is viewing an iPod, you may want to display related items such as iPod accessories. If the shopper is viewing items in a Digital Camera navigation node then you can use recommendations to highlight a set of featured digital cameras in that node.

Recommendations are lists of items, accessible through item for item recommendations, navigation nodes for navigation recommendations, and the recommendations entry point for store recommendations. The recommendation's rel name reflects the type of recommendation. For example, when accessing an item's recommendations a rel name could be "crosssells", which indicates the rel links to a list of "cross-sell" items.

Read Scope Recommendations

Read recommended items for a scope. This API is currently not available.

Workflow

  1. Start with [navigation][navigation].
  2. Read link following rel: recommendations.
  3. Read link following rel: {recommendation-group-rel}.
  4. Render response.

Response Fields

Read Item Recommendations

Read other items recommended for an item.

Workflow

  1. Start with item.
  2. Read link following rel: recommendations.
  3. Read link following rel: {recommendation-group-rel}.
  4. Render response.

Response Fields

Read Navigation Node Recommendations

Read recommended items for a navigation node. This API is currently not available.

Workflow

  1. Start with [navigation][navigation].
  2. Read link following rel: recommendations.
  3. Read link following rel: {recommendation-group-rel}.
  4. Render response.

Response Fields


registrations

Entry Point: /registrations/{scope}/newaccount

The registrations resource family enables you to create new customers.

Register Newaccount

Register a new account for a customer.

You cannot create a new customer if a customer is already logged into Cortex API. For example, if a customer logged on through a web browser, the customer cannot create a new customer until the customer logs out. If you attempt to create a customer when a customer is logged in, Cortex API throws an error.

All the fields in the registration form must be filled out to create a customer.

Workflow

  1. Start with [root][root].
  2. Read link following rel: newaccountform.
  3. Fill out the form.
  4. Create form to link rel: registeraction.

searches

Entry Point: /searches/{scope}

The searches resource family uses the Elastic Path Search Server to perform searches. Cortex API sends the search keywords entered by the customer to the search server for processing. Once the search server processes the search, the results are returned to Cortex API.

Client developers can think of search as a three-part process. First, you get the search form and fill it out with the search keywords. Second, you POST the search form to create the search. Then, you follow the link returned by Cortex API to retrieve the search results. Search results are paginated and ordered according to how relevant the results are to the search keywords.

Search Items

Submit a search query for items matching search criteria and read the result.

Workflow

  1. Start with searches.
  2. Read link following rel: keywordsearchform.
  3. Fill out the form.
  4. Create form to link rel: itemkeywordsearchaction.

shipmentdetails

The shipmentdetails resource defines how and where the physical goods you're purchasing are shipped. The where you're shipping is the shipping address, while the how are the shipping options (i.e. Canada Post, FedEx, etc) available for your store.

Uses a Selector to choose the shipping option for the order. The shipping option is how the order will be shipped, i.e. (FedEx, Canada Post, etc). The shipping options available for your shipment depend on which shipping regions and shipping options are configured for your store. Check with your store's administrator for more information on these options.

Read Order Destination Info

Retrieves the order's destinationinfo, which contains links to:

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: deliveries.
  4. Read link following rel: element.
  5. Read link following rel: destinationinfo.
  6. Render response.

Response Fields

Type: elasticpath.controls.info
Name Description Type
"name":

The info object's name.

string

Read Order Shipping Address

Retrieve the shipping address that is currently selected for the order.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: deliveries.
  4. Read link following rel: element.
  5. Read link following rel: destinationinfo.
  6. Read link following rel: destination.
  7. Render response.

Response Fields

Type: addresses.address
Name Description Type
"name":

The customer name.

object
"given-name":

The person's given name.

string
"family-name":

The person's family name.

string
"address":

The customer address. Address field names are based on the v.card specification. For more information on this specification, see v.card.

object
"street-address":

The street address.

string
"extended-address":

Extra field for address information. This field is optional.

string
"locality":

The city name.

string
"region":

Valid region codes for this field can be retrieved using the Geographies Resource.

string
"postal-code":

Postal code or zip code.

string
"country-name":

Valid country codes for this field can be retrieved using the Geographies Resource.

string
"phone-number":

Phone number

string
"organization":

The organization

string

Select Shipping Address

Uses a Selector to select a shipping option (i.e. FedEx, Canada Post, etc) to use for the order.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: deliveries.
  4. Read link following rel: element.
  5. Read link following rel: destinationinfo.
  6. Read link following rel: selector.
  7. Read link following rel: chosen.
  8. Create choice to link rel: selectaction.

Read Order Address Form

Retrieve the address form to create a new shipping address for the order.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: deliveries.
  4. Read link following rel: element.
  5. Read link following rel: destinationinfo.
  6. Read link following rel: addressform.
  7. Render response.

Response Fields

Read Order Shipping Option Info

Retrieves the order's shippingoptioninfo, which contains links to:

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: deliveries.
  4. Read link following rel: element.
  5. Read link following rel: shippingoptioninfo.
  6. Render response.

Response Fields

Type: elasticpath.controls.info
Name Description Type
"name":

The info object's name.

string

Read Order Shipping Option

Retrieves the shipping option that is currently selected for the order. The shipping option is how the order will be shipped, i.e. (FedEx, Canada Post, etc). If a shipping option has not been selected for the order, the shipping option link will not appear on the shippingoptioninfo. For information on how to select the shippingoption, see Select Shipping Choice

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: deliveries.
  4. Read link following rel: element.
  5. Read link following rel: shippingoptioninfo.
  6. Read link following rel: shippingoption.
  7. Render response.

Response Fields

Type: shipmentdetails.shipping-option
Name Description Type
"name":

Name of the shipping option.

string
"display-name":

The localized name of the carrier, intended for display in the client application.

string
"carrier":

Name of the carrier.

string
"cost":

The shipping costs for shipping the item(s) to the selected shipping address.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string

Select Shipping Option

Uses a Selector to choose the shipping option for the order. The shipping option is how the order will be shipped, i.e. (FedEx, Canada Post, etc). The shipping options available for your shipment depend on which shipping regions and shipping options are configured for your store. Check with your store's administrator for more information on these options.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: deliveries.
  4. Read link following rel: element.
  5. Read link following rel: shippingoptioninfo.
  6. Read link following rel: selector.
  7. Read link following rel: chosen.
  8. Create choice to link rel: selectaction.

Read Destination Needinfo From Order

Read the needinfo link for the shipping address. If this link appears on the order, it means the shipping address has not been selected or created for the order. Needinfo links can appear on the order, the purchase form, and the delivery.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: needinfo.
  4. Render response.

Response Fields

Type: elasticpath.controls.info
Name Description Type
"name":

The info object's name.

string

Read Destination Needinfo From Delivery

Read the needinfo link for the shipping address from the delivery. Needinfo links can appear on the order, the purchase form, and the delivery.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: deliveries.
  4. Read link following rel: element.
  5. Read link following rel: needinfo.
  6. Render response.

Response Fields

Type: elasticpath.controls.info
Name Description Type
"name":

The info object's name.

string

Read Destination Needinfo From Purchaseform

Read the needinfo link for the shipping address from the purchase form. Needinfo links can appear on the order, the purchase form, and the delivery.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: purchaseform.
  4. Read link following rel: needinfo.
  5. Render response.

Response Fields

Type: elasticpath.controls.info
Name Description Type
"name":

The info object's name.

string

Read Shippingoption Needinfo From Order

Read the needinfo for the shipping option from the order. This needinfo appears when a shipping option has not been selected for the order. Needinfo links can appear on the order, the purchase form, and the delivery.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: needinfo.
  4. Render response.

Response Fields

Type: elasticpath.controls.info
Name Description Type
"name":

The info object's name.

string

Read Shippingoption Needinfo From Delivery

Read the needinfo for the shipping option from the order. This needinfo appears when a shipping option has not been selected for the order. Needinfo links can appear on the order, the purchase form, and the delivery.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: deliveries.
  4. Read link following rel: element.
  5. Read link following rel: needinfo.
  6. Render response.

Response Fields

Type: elasticpath.controls.info
Name Description Type
"name":

The info object's name.

string

Read Shippingoption Needinfo From Purchaseform

Read the needinfo for the shipping option from the purchaseform. This needinfo appears when a shiping option has not been selected for the order. Needinfo links can appear on the order, the purchase form, and the delivery.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: purchaseform.
  4. Read link following rel: needinfo.
  5. Render response.

Response Fields

Type: elasticpath.controls.info
Name Description Type
"name":

The info object's name.

string

shipments

A shipment lists the shipments created by a purchase.Represents shipment line items.

Read Shipping Option For Shipment

Retrieve the shipment options associated with a shipment.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: shipments.
  4. Read link following rel: element.
  5. Read link following rel: shippingoption.
  6. Render response.

Response Fields

Type: shipmentdetails.shipping-option
Name Description Type
"name":

Name of the shipping option.

string
"display-name":

The localized name of the carrier, intended for display in the client application.

string
"carrier":

Name of the carrier.

string
"cost":

The shipping costs for shipping the item(s) to the selected shipping address.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string

Read Shipment Line Items

Retrieve the shipment line items associated with a shipment.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: shipments.
  4. Read link following rel: element.
  5. Read link following rel: lineitems.
  6. Render response.

Response Fields

Read Shipment Line Item

Read a shipment line item.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: shipments.
  4. Read link following rel: element.
  5. Read link following rel: lineitems.
  6. Read link following rel: element.
  7. Render response.

Response Fields

Type: shipments.line-item
Name Description Type
"name":

The name.

string
"quantity":

The quantity.

integer

Read Shipment Line Item Options

Retrieve the options associated with a shipment line item.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: shipments.
  4. Read link following rel: element.
  5. Read link following rel: lineitems.
  6. Read link following rel: element.
  7. Read link following rel: options.
  8. Render response.

Response Fields

Read Shipment Line Item Option

Read a shipment line item option.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: shipments.
  4. Read link following rel: element.
  5. Read link following rel: lineitems.
  6. Read link following rel: element.
  7. Read link following rel: options.
  8. Read link following rel: element.
  9. Render response.

Response Fields

Type: shipments.option
Name Description Type
"name":

The name.

string
"display-name":

The display name.

string

Read Shipment Line Item Option Value

Retrieve the option value associated with a shipment line item.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: shipments.
  4. Read link following rel: element.
  5. Read link following rel: lineitems.
  6. Read link following rel: element.
  7. Read link following rel: options.
  8. Read link following rel: element.
  9. Read link following rel: value.
  10. Render response.

Response Fields

Type: shipments.value
Name Description Type
"name":

The name.

string
"display-name":

The display name.

string

Read Shipping Address For Shipment

Retrieve the shipment address associated with a shipment.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: shipments.
  4. Read link following rel: element.
  5. Read link following rel: destination.
  6. Render response.

Response Fields

Type: addresses.address
Name Description Type
"name":

The customer name.

object
"given-name":

The person's given name.

string
"family-name":

The person's family name.

string
"address":

The customer address. Address field names are based on the v.card specification. For more information on this specification, see v.card.

object
"street-address":

The street address.

string
"extended-address":

Extra field for address information. This field is optional.

string
"locality":

The city name.

string
"region":

Valid region codes for this field can be retrieved using the Geographies Resource.

string
"postal-code":

Postal code or zip code.

string
"country-name":

Valid country codes for this field can be retrieved using the Geographies Resource.

string
"phone-number":

Phone number

string
"organization":

The organization

string

Read Shipments For Purchase

Retrieve the shipments associated with a purchase.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: shipments.
  4. Read link following rel: element.
  5. Render response.

Response Fields

Type: shipments.shipment
Name Description Type
"status":

Indicates the status of the shipment.

object
"code":

The status code.

string

taxes

Taxes describe the amount of tax owing for orders, shipments and shipment lineitems.

Read Order Taxes

Retrieves the total tax for an order, which includes the order's tax amount, currency, and type of tax (VAT, HST, etc.).

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: tax.
  4. Render response.

Response Fields

Type: taxes.taxes
Name Description Type
"total":

The total tax.

object
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string
"cost":

The cost of the tax(es).

array
"title":

The name of the tax.

string

Read Shipment Taxes

Retrieves the total tax for a shipment, which includes the shipments' tax amount, currency, and type of tax (VAT, HST, etc.).

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: shipments.
  4. Read link following rel: element.
  5. Read link following rel: tax.
  6. Render response.

Response Fields

Type: taxes.taxes
Name Description Type
"total":

The total tax.

object
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string
"cost":

The cost of the tax(es).

array
"title":

The name of the tax.

string

Read Shipment Line Item Taxes

Retrieve the tax amount for a shipment line item.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: shipments.
  4. Read link following rel: element.
  5. Read link following rel: lineitems.
  6. Read link following rel: element.
  7. Read link following rel: tax.
  8. Render response.

Response Fields

Type: taxes.taxes
Name Description Type
"total":

The total tax.

object
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string
"cost":

The cost of the tax(es).

array
"title":

The name of the tax.

string

totals

The totals resource calculates the total costs for:

Read Cart Total

Retrieve the total cost of all cart line items before cart total discounts are applied.

Workflow

  1. Start with cart.
  2. Read link following rel: total.
  3. Render response.

Response Fields

Type: totals.total
Name Description Type
"cost":

The total costs. This is an array because the total cost have multiple currencies. For example, $20 USD + 20,000 loyalty points.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string

Read Cart Line Item Total

Retrieve the total cost of a single cart line item for a requested quantity, after cart line item discounts are applied.

Workflow

  1. Start with cart.
  2. Read link following rel: lineitems.
  3. Read link following rel: element.
  4. Read link following rel: total.
  5. Render response.

Response Fields

Type: totals.total
Name Description Type
"cost":

The total costs. This is an array because the total cost have multiple currencies. For example, $20 USD + 20,000 loyalty points.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string

Read Order Total

Retrieve the total cost of the shopper's order including taxes and shipping costs.

Workflow

  1. Start with cart.
  2. Read link following rel: order.
  3. Read link following rel: total.
  4. Render response.

Response Fields

Type: totals.total
Name Description Type
"cost":

The total costs. This is an array because the total cost have multiple currencies. For example, $20 USD + 20,000 loyalty points.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string

Read Shipment Total

Retrieve the total cost for a shipment.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: shipments.
  4. Read link following rel: element.
  5. Read link following rel: total.
  6. Render response.

Response Fields

Type: totals.total
Name Description Type
"cost":

The total costs. This is an array because the total cost have multiple currencies. For example, $20 USD + 20,000 loyalty points.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string

Read Shipment Line Item Total

Retrieve the total cost for a shipment line item.

Workflow

  1. Start with purchases.
  2. Read link following rel: element.
  3. Read link following rel: shipments.
  4. Read link following rel: element.
  5. Read link following rel: lineitems.
  6. Read link following rel: element.
  7. Read link following rel: total.
  8. Render response.

Response Fields

Type: totals.total
Name Description Type
"cost":

The total costs. This is an array because the total cost have multiple currencies. For example, $20 USD + 20,000 loyalty points.

array
"currency":

The currency the cost is in.

string
"amount":

The decimal value of the cost.

decimal
"display":

Formatted currency string that can be displayed on the client application.

string

wishlists

Entry Point: /wishlists/{scope}/default

A wishlist is a list that customers build up containing items that they are interested in, or desire to purchase. This applies even to items which are out of stock, which allows a customer to track the item and to be notified when the item becomes available. A wishlist is similar to a cart in that items can be added or removed. Items can also be moved between the wishlist and the cart. Only one wishlist is available per shopper. This default wishlist is automatically available and cannot be deleted.

Wishlists

Returns a list of links to the shopper's wishlists. Only the default wishlist is currently supported, so responses will contain only one link..

Workflow

  1. Start with wishlists.
  2. Render response.

Response Fields

Wishlist

Retrieves a collection of links to wishlist lineitems.

Workflow

  1. Start with wishlist.
  2. Render response.

Response Fields

None.

Default Wishlist

Retrieves the shopper's default wishlist.

Workflow

  1. Start with default-wishlist.
  2. Render response.

Response Fields

None.

Wishlist Line Items

Retrieves a collection of links to wishlist items and a link to the wishlist.

Workflow

  1. Start with wishlist-line-items.
  2. Render response.

Response Fields

Wishlist Line Item

Retrieves wishlist item details, which include: - A link to the list of wishlist items - A link to the wishlist - A link to the item in the items resource - A link to the movetocart form

Workflow

  1. Start with wishlist.
  2. Read link following rel: lineitems.
  3. Read link following rel: element.
  4. Render response.

Response Fields

Type: wishlists.wishlist-line-item
Name Description Type
"configuration":

The details of the line item configuration.

object

Delete Wishlist Items

Deletes the items from a shopper's wishlist.

Workflow

  1. Start with wishlist.
  2. Read link following rel: lineitems.
  3. Delete wishlist-line-items.

Delete Wishlist Item

Delete item from wishlist.

Workflow

  1. Start with wishlist.
  2. Read link following rel: lineitems.
  3. Read link following rel: element.
  4. Delete wishlist-line-item.

Add Item To Default Wishlist

Adds an item to the default wishlist. After executing the add item to default wishlist action a redirect link is provided to the newly added item on the wishlist.

Workflow

  1. Start with item.
  2. Read link following rel: addtowishlistform.
  3. Fill out the form.
  4. Create form to link rel: addtodefaultwishlistaction.

Move From Wishlist To Cart

Moves a line item from the wishlist to the cart. You must specify the quantity in the request body.

Once posted, the item deletes from the wishlist and adds to the cart. Then Cortex returns a redirect link to the newly added cart line item. You can also get to the movetocart form by following the link in a wishlist line item. The movetocart form contains an action link to move the item to the cart. Note that the action link will only be present if the wishlist line item is purchasable. If the wishlist line item is not purchasable, the action link will not appear on the form. Only purchasable items can be moved from wishlists into a cart.

Workflow

  1. Start with wishlist.
  2. Read link following rel: lineitems.
  3. Read link following rel: element.
  4. Read link following rel: movetocartform.
  5. Fill out the form.
  6. Create form to link rel: movetocartaction.

Move From Cart To Wishlist

Moves a line item from the cart to the wishlist.

Once posted, Cortex will return a redirect link to the newly added wishlist line item. You can also get to the movetowishlist form by following the link in a cart line item. The movetowishlist form contains an action link to move the item to the wishlist.

Workflow

  1. Start with cart.
  2. Read link following rel: lineitems.
  3. Read link following rel: element.
  4. Read link following rel: movetowishlistform.
  5. Fill out the form.
  6. Create form to link rel: movetowishlistaction.

Read Wishlist Memberships

Retrieves the list of wishlists that the item has been added to.

GET:{cortex}/wishlists/memberships/{item_uri}

The list is empty if the item is not in your wishlist.

Workflow

  1. Start with item.
  2. Read link following rel: wishlistmemberships.
  3. Render response.

Response Fields