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.

Selectors

Selectors

Selectors are how to make choices in Cortex API. For example, to choose a billing or shipping addresses to use for a purchase, a paymentmeans to use for a purchase, or an option for an item, you would use a selector. The workflows for using a selector is: GET the selector, GET a selector's choice, and then POST to the choice's selectaction link. Once the choice is POSTed, Cortex API returns status code 200 and a Location header linking back to the selector, or, in the case of an item option selection, linking to the selected item.

Basic Anatomy of the Selectors

The examples below show Cortex API selectors. The table below them describes the common elements found in all the selectors.

option-value-selector

This selector is for selecting options for an item.

{
	"self": {
		"type": "application/vnd.elasticpath.selector",
		"uri": "/commerce-legacy/itemselections/<scope>/<itemid>/options/<optionid>/selector",
		"href": "http://www.onlinestore.com/itemselections/<scope>/<itemid>/options/<optionid>/selector",
		"max-age": 0
  },
	"links": [
    {
		"type": "application/vnd.elasticpath.links",
		"rel": "choice",
		"rev": "selector",
		"href": "http://www.onlinestore.com/itemselections/<scope>/<itemid>/options/<optionid>/values/<optionvalueid>/selector",
		"uri": "/commerce-legacy/itemselections/<scope>/<itemid>/options/<optionid>/values/<optionvalueid>/selector"
    },
    {
		"type": "application/vnd.elasticpath.links",
		"rel": "chosen",
		"rev": "selector",
		"href": "http://www.onlinestore.com/itemselections/<scope>/<itemid>/options/<optionid>/values/<optionvalueid>/selector",
		"uri": "/commerce-legacy/itemselections/<scope>/<itemid>/options/<optionid>/values/<optionvalueid>/selector"
    },
    {
		"type": "application/vnd.elasticpath.itemdefinition.option",
		"rel": "option",
		"rev": "selector",
		"href": "http://www.onlinestore.com/itemdefinitions/<scope>/<itemid>/options/<optionid>",
		"uri": "/commerce-legacy/itemdefinitions/<scope>/<itemid>/options/<optionid>"
    }
  ],
		"name": "option-value-selector",
		"selection-rule": "1"
}

shipping-option-selector

This selector enables you to choose a shipping option for an order.

{
	"self": {
		"type": "application/vnd.elasticpath.selector",
		"uri": "/commerce-legacy/shipmentdetails/<storeid>/<shipmentID>/shippingoptioninfo/selector",
		"href": "http://www.onlinestore.com/shipmentdetails/<storeid>/<shipmentID>/shippingoptioninfo/selector",
		"max-age": 0
  },
	"links": [
    {
		"type": "application/vnd.elasticpath.links",
		"rel": "chosen",
		"rev": "selector",
		"href": "http://www.onlinestore.com/shipmentdetails/<storeid>/<shipmentID>/shippingoptioninfo/selector/shipmentdetails/<storeid>/<shipmentID>/shippingoptions/<shippingoptionID>",
		"uri": "/commerce-legacy/shipmentdetails/<storeid>/<shipmentID>/shippingoptioninfo/selector/shipmentdetails/<storeid>/<shipmentID>/shippingoptions/<shippingoptionID>"
    },
    {
		"type": "application/vnd.elasticpath.links",
		"rel": "choice",
		"rev": "selector",
		"href": "http://www.onlinestore.com/shipmentdetails/<storeid>/<shipmentID>/shippingoptioninfo/selector/shipmentdetails/<storeid>/<shipmentID>/shippingoptions/<shippingoptionID>",
		"uri": "/commerce-legacy/shipmentdetails/<storeid>/<shipmentID>/shippingoptioninfo/selector/shipmentdetails/<storeid>/<shipmentID>/shippingoptions/<shippingoptionID>"
    },
    {
		"type": "application/vnd.elasticpath.info",
		"rel": "shippingoptioninfo",
		"rev": "selector",
		"href": "http://www.onlinestore.com/shipmentdetails/<storeid>/<shipmentID>/shippingoptioninfo",
		"uri": "/commerce-legacy/shipmentdetails/<storeid>/<shipmentID>/shippingoptioninfo"
    }
  ],
		"name": "shipping-option-selector",
		"selection-rule": "1"
}

destination-selector

This selector enables you to choose a destination for an order.

{
	"self": {
	"type": "application/vnd.elasticpath.selector",
	"uri": "/commerce-legacy/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo/selector",
	"href": "www.onlinstore.com/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo/selector",
	"max-age": 0
  },
	"links": [ {
	"type": "application/vnd.elasticpath.links",
	"rel": "chosen",
	"rev": "selector",
	"href": "www.onlinstore.com/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo/selector/profiles/<scope>/<profileID>/addresses/<addresseID>",
	"uri": "/commerce-legacy/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo/selector/profiles/<scope>/<profileID>/addresses/<addresseID>"
}, {
	"type": "application/vnd.elasticpath.links",
	"rel": "choice",
	"rev": "selector",
	"href": "www.onlinstore.com/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo/selector/profiles/<scope>/<profileID>/addresses/<addresseID>",
	"uri": "/commerce-legacy/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo/selector/profiles/<scope>/<profileID>/addresses/<addresseID>"
}, {
	"type": "application/vnd.elasticpath.info",
	"rel": "destinationinfo",
	"rev": "selector",
	"href": "www.onlinstore.com/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo",
	"uri": "/commerce-legacy/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo"
} ],
	"name": "destination-selector",
	"selection-rule": "1"
}

payment-method-selector

This selector enables you to choose the payment method to use for an order.

{
	"self": {
		"type": "application/vnd.elasticpath.selector",
		"uri": "/commerce-legacy/paymentmethods/orders/<scope>/<orderid>",
		"href": "http://www.onlinestore.com/paymentmethods/orders/<scope>/<orderid>",
		"max-age": 0
  },
	"links": [
    {
		"type": "application/vnd.elasticpath.links",
		"rel": "chosen",
		"rev": "selector",
		"href": "http://www.onlinestore.com/paymentmethods/<scope>/<paymentid>/orders/<scope>/<orderid>",
		"uri": "/commerce-legacy/paymentmethods/<scope>/<paymentid>/orders/<scope>/<orderid>"
    },
    {
		"type": "application/vnd.elasticpath.links",
		"rel": "choice",
		"rev": "selector",
		"href": "http://www.onlinestore.com/paymentmethods/<scope>/<paymentid>/orders/<scope>/<orderid>",
		"uri": "/commerce-legacy/paymentmethods/<scope>/<paymentid>/orders/<scope>/<orderid>"
    },
    {
		"type": "application/vnd.elasticpath.info",
		"rel": "paymentmethodinfo",
		"rev": "selector",
		"href": "http://www.onlinestore.com/paymentmethods/orders/<scope>/<orderid>",
		"uri": "/commerce-legacy/paymentmethods/orders/<scope>/<orderid>"
    }
  ],
		"name": "payment-method-selector",
		"selection-rule": "1"
}

billing-address-selector

This selector enables you to choose the billing address to use for an order.

{
	"self": {
		"type": "application/vnd.elasticpath.selector",
		"uri": "/commerce-legacy/orders/<scope>/<orderid>/billinginfo",
		"href": "http://www.onlinestore.com/orders/<scope>/<orderid>/billinginfo",
		"max-age": 0
  },
	"links": [
    {
		"type": "application/vnd.elasticpath.address",
		"rel": "choice",
		"rev": "selector",
		"href": "http://www.onlinestore.com/orders/<scope>/<orderid>/billinginfo/profiles/<scope>/<profileid>/addresses/<addressid>",
		"uri": "/commerce-legacy/orders/<scope>/<orderid>/billinginfo/profiles/<scope>/<profileid>/addresses/<addressid>"
    },
    {
		"type": "application/vnd.elasticpath.address",
		"rel": "chosen",
		"rev": "selector",
		"href": "http://www.onlinestore.com/orders/<scope>/<orderid>/billinginfo/profiles/<scope>/<profileid>/addresses/<addressid>",
		"uri": "/commerce-legacy/orders/<scope>/<orderid>/billinginfo/profiles/<scope>/<profileid>/addresses/<addressid>"
    },
    {
		"type": "application/vnd.elasticpath.info",
		"rel": "billingaddressinfo",
		"rev": "selector",
		"href": "http://www.onlinestore.com/orders/<scope>/<orderid>/billingaddressinfo",
		"uri": "/commerce-legacy/orders/<scope>/<orderid>/billingaddressinfo"
    }
  ],
		"name": "billing-address-selector",
		"selection-rule": "1"
}
Property Description
"rel":"choice" Links to a choice a customer can select by POSTing to the choice's selectaction rel. Once the choice is POSTed, Cortex API returns status code 200 and a Location header linking back to the selector, or, in the case of an item option selection, linking to the selected item.
"rel":"chosen"

Identifies this rel has been chosen for this selector. This rel has either been previously chosen for this selector or this is the selector's default selection.
"name":"option-value-selector" The selector's name differs per each type of selector.
"selection-rule":"1" Indicates the number of selections that must be made in the selector. If this rule isn't satisfied, a NeedInfo link will likely occur. For example, if a payment method is not specified for an order, a needinfo link will appear and stop the order from being purchased.

Selector Workflows

Selector's operate differently for item option selectors, a billing or shipping address address selectors, or a paymentmethod selectors.

Item Selector

The following workflow shows how to get the item selector and make a selection.

configurable_product_JSON_heirarchy

Payment Method Selector

The following workflow shows how to get the Payment Method selector and make a selection.

paymentinfo_selector

Billing Address Selector

The following workflow shows how to get the billing address selector and make a selection.

billing-address-selector

Destination Selector

The following workflow shows how to get the destination selector and make a selection.

destination_selector

Shipping Option Selector

The following workflow shows how to get the shipping option selector and make a selection.

shipping_option_selector