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.

Forms

Forms

Forms are a hypermedia control that creates new resources. Forms are generally rendered on the UI as input fields or submit buttons.

With forms, you can discover:
  • The properties required to create a resource.
  • The link to invoke the creation of a resource.
Cortex forms follow this format:
  • A type that indicates the properties that will be created in the resource.

  • Properties that define the data required to create a resource. Properties are optional, as some resources don't require data to create them.

  • Links, called action links, that invoke the creation of a resource. If an action link doesn't exist on the form, the resource cannot be created.

Form Example: Adding to cart

The items resource's addtocartform form link enables you to add the item to a cart, which means a new cart lineitem resource is created for the item. The form's type application/vnd.elasticpath.cart.lineitem indicates the form creates a cart lineitem resource: 
{
  "rel": "addtocartform",  
  "type": "elasticpath.carts.line-item",
  "uri": "/commerce-legacy/carts/items/mobee/m5yxi=/form",
  "href": "http://api.elasticpath.net/cortex/carts/items/mobee/m5yxi=/form"
}
Retrieving the addtocartform form link returns the form resource, which lists the properties and actions available for the form. In this example, the form contains:
  • quantity - this property indicates the item's quantity must be specified before the item can be added to cart.
  • addtodefaultcart - this action link adds the item to the shopper's cart.
{
  "self": {
    "type": "elasticpath.carts.line-item",
    "uri": "/commerce-legacy/carts/items/mobee/m5yxi=/form",
    "href": "http://api.elasticpath.net/cortex/carts/items/mobee/m5yxi=/form",
    "max-age": 0
  },
  "quantity": 0
  "links": [
    {
      "rel": "addtodefaultcartaction",
      "uri": "/commerce-legacy/carts/mobee/default/lineitems/items/mobee/m5yxi=",
      "href": "http://api.elasticpath.net/cortex/carts/mobee/default/lineitems/items/mobee/m5yxi="  
    }
  ]
}
To add the item to the cart, construct a POST request using the form fields as the request body and the URL defined by the action link: 
POST /carts/mobee/default/lineitems/items/mobee/m5yxi=
Content-Type: application/json
{
  "quantity" : 1
}
If the action succeeds, Cortex returns status code 201 CREATED and a Location header with a reference to the newly created resource. If the action succeeds but results in modifying an existing resource rather than creating a new resource, then Cortex returns status code 200 OK and a Location header with a reference to the modified resource. 
201 CREATED
Location: http://api.elasticpath.net/cortex/carts/mobee/mjt=/lineitems/gyz=

Forms can be used with the FollowLocation request parameter to reduce the number of calls required to retrieve a newly created resource. Followlocation instructs Cortex to retrieve the resource referenced in the Location header and return it in the response body.