Developers

Cart fields

Summary of cart field endpoints

All endpoints take optional query parameters that enhance the response objects:

  • include — Enhance the response objects (e.g. ?include=translations). Currently the only supported value is:
    • translations — Include translations for all translatable objects and keys.
  • language_code — A two-digit ISO 639 language code. Return all translatable values in the response in the given language. Set all translatable values in the request in the given language.

List all cart fields for the current site

Get list of cart fields.

GET /admin/api/ecommerce/v1/cart_fields

Example response:

Status: 200 OK

[
  {
    "id": 62,
    "enabled": true,
    "position": 1,
    "kind": "email",
    "name": "an-e-mail",
    "label": "An e-mail",
    "description": "Please enter your e-mail here",
    "mapping": "customer.email",
    "required": true,
    "options": null,
    "hints": {
      "skip_newline": false
    },
    "created_at": "2021-03-15T14:59:25.000Z",
    "updated_at": "2021-03-15T14:59:25.000Z"
  }
]

Filter attributes

Read more about filters.

  • Object cart_field attributes: id, enabled, position, kind, name, label, mapping, required, created_at, updated_at.

List attributes of a cart field

GET /admin/api/ecommerce/v1/cart_fields/1

Example request:

GET http://helloworld.voog.com/admin/api/ecommerce/v1/cart_fields/62

Example response:

Status: 200 OK

{
  "id": 62,
  "enabled": true,
  "position": 1,
  "kind": "email",
  "name": "an-e-mail",
  "label": "An e-mail",
  "description": "Please enter your e-mail here",
  "mapping": "customer.email",
  "required": true,
  "options": null,
  "hints": {
    "skip_newline": false
  },
  "created_at": "2021-03-15T14:59:25.000Z",
  "updated_at": "2021-03-15T14:59:25.000Z"
}

Create a new cart field for the current site

POST /admin/api/ecommerce/v1/cart_fields

Example data:

{
  "kind": "select",  
  "label": "Pick a fruit",
  "description": "Please pick your preferred fruit",
  "required": true,
  "options": { 
    "elements": ["Apple", "Orange", "Fig"]
  },
  "hints": {
    "skip_newline": true
  },
  "translations": {    
    "label": {
      "et": "Vali puuvili"
    },
    "description": {
      "et": "Palun vali eelistatud puuvili"
    },
    "options": {
      "et": {
        "elements": ["Õun", "Apelsin", "Viigimari"]
      }                               
    }                                 
  }
}

Example response:

Status: 201 Created

{
  "id": 63,
  "enabled": true,
  "position": 2,
  "kind": "select",
  "name": "pick-a-fruit",
  "label": "Pick a fruit",
  "description": "Please pick your preferred fruit",
  "mapping": null,
  "required": true,
  "options": { 
    "elements": ["Apple", "Orange", "Fig"]
  },
  "hints": {
    "skip_newline": true
  },
  "created_at": "2021-03-15T14:59:25.000Z",
  "updated_at": "2021-03-15T14:59:25.000Z"
}

Parameters

  • enabled — Flag switching the cart field on or off, true by default.
  • position — An integer determining the cart field's position from the top.
  • kind — Cart field type, one of checkbox, country, date, email, heading, infobox, select, text, textarea.
  • name — A unique name for the field. Auto-generated if not provided.
  • label — The displayed label for the field.
  • description — An optional longer description for the field, rendered below the field.
  • mapping — Optional mapping to a systemic field, one of:
    • customer.email – Customer's e-mail address
    • <address>.address1 – Address line 1
    • <address>.address2 – Address line 2
    • <address>.city – City
    • <address>.company_name – Company name
    • <address>.country_code – 2-digit ISO 3166 country code, lowercase
    • <address>.name – Customer's name
    • <address>.phone – Customer's phone number
    • <address>.zip – Zip code

Above, <address> is either billing_address or shipping_address for specifying the billing
and shipping addresses, respectively.

  • required — A flag specifying if the field is required or optional.
  • options — An object for passing field type-specific options.
    • country
    • allowed – Listed countries, an array of lowercase 2-digit ISO 3166 codes.
    • heading
    • separator – If true, add a horizontal separator above the heading.
    • select
    • elements — Listed options, an array of strings.
    • textarea
    • n_rows – Number of visible rows in the text area, an integer greater than or equal to 1.
  • hints — An object of hints to the rendering engine.
    • skip_newline — If true, attempt to keep the field on the same line as the previous field, depending on viewport width.
  • translations — Values for translatable fields by language context. The translatable fields are label, description and options.elements (for the select field type).

Replace the set of cart fields

This endpoint receives an array of cart field specifications and replaces the existing set of
fields with the received set. See the creation endpoint for supported
parameters of a single cart field's payload. Additionally, id is a supported parameter. If the ID
matches an existing cart field, its attributes are updated instead of creating a new field.

POST /admin/api/ecommerce/v1/cart_fields/replace

Example data:

[
  {
    "id": 62,
    "kind": "email",
    "label": "An e-mail",
    "description": "Please enter your e-mail here",
    "mapping": "customer.email",
    "required": true
  },
  {
    "kind": "select",  
    "label": "Pick a fruit",
    "description": "Please pick your preferred fruit",
    "required": true,
    "options": { 
      "elements": ["Apple", "Orange", "Fig"]
    },
    "hints": {
      "skip_newline": true
    }  
  }
]

Example response:

Status: 200 OK

[
  {
    "id": 62,
    "enabled": true,
    "position": 1,
    "kind": "email",
    "name": "an-e-mail",
    "label": "An e-mail",
    "description": "Please enter your e-mail here",
    "mapping": "customer.email",
    "required": true,
    "options": null,
    "hints": {
      "skip_newline": false
    },
    "created_at": "2021-03-15T14:59:25.000Z",
    "updated_at": "2021-03-15T14:59:25.000Z"
  },
  {
    "id": 63,
    "enabled": true,
    "position": 2,
    "kind": "select",
    "name": "pick-a-fruit",
    "label": "Pick a fruit",
    "description": "Please pick your preferred fruit",
    "mapping": null,
    "required": true,
    "options": { 
      "elements": ["Apple", "Orange", "Fig"]
    },
    "hints": {
      "skip_newline": true
    },
    "created_at": "2021-03-15T14:59:25.000Z",
    "updated_at": "2021-03-15T14:59:25.000Z"
  }
]

Update attributes of a cart field

PUT /admin/api/ecommerce/v1/cart_fields/1

This request updates the cart field with the provided attributes.

Example request:

PUT http://helloworld.voog.com/admin/api/ecommerce/v1/cart_fields/63

Example data:

{
  "kind": "select",  
  "label": "Pick a fruit",
  "description": "Please pick your preferred fruit",
  "required": true,
  "options": { 
    "elements": ["Apple", "Orange", "Fig"]
  },
  "hints": {
    "skip_newline": true
  }, 
  "translations": {    
    "label": {
      "et": "Vali puuvili"
    },
    "description": {
      "et": "Palun vali eelistatud puuvili"
    },
    "options": {
      "et": {
        "elements": ["Õun", "Apelsin", "Viigimari"]
      }                               
    }                                 
  }   
}

Example response:

Status: 200 OK

{
  "id": 63,
  "enabled": true,
  "position": 2,
  "kind": "select",
  "name": "pick-a-fruit",
  "label": "Pick a fruit",
  "description": "Please pick your preferred fruit",
  "mapping": null,
  "required": true,
  "options": { 
    "elements": ["Apple", "Orange", "Fig"]
  },
  "hints": {
    "skip_newline": true
  },
  "created_at": "2021-03-15T14:59:25.000Z",
  "updated_at": "2021-03-15T14:59:25.000Z"
}

Parameters

  • enabled — Flag switching the cart field on or off, true by default.
  • position — An integer determining the cart field's position from the top.
  • kind — Cart field type, one of checkbox, country, date, email, heading, infobox, select, text, textarea.
  • name — A unique name for the field. Auto-generated if not provided.
  • label — The displayed label for the field.
  • description — An optional longer description for the field, rendered below the field.
  • mapping — Optional mapping to a systemic field, one of:
    • customer.email – Customer's e-mail address
    • <address>.address1 – Address line 1
    • <address>.address2 – Address line 2
    • <address>.city – City
    • <address>.company_name – Company name
    • <address>.country_code – 2-digit ISO 3166 country code, lowercase
    • <address>.name – Customer's name
    • <address>.phone – Customer's phone number
    • <address>.zip – Zip code

Above, <address> is either billing_address or shipping_address for specifying the billing
and shipping addresses, respectively.

  • required — A flag specifying if the field is required or optional.
  • options — An object for passing field type-specific options.
    • country
    • allowed – Listed countries, an array of lowercase 2-digit ISO 3166 codes.
    • heading
    • separator – If true, add a horizontal separator above the heading.
    • select
    • elements — Listed options, an array of strings.
    • textarea
    • n_rows – Number of visible rows in the text area, an integer greater than or equal to 1.
  • hints — An object of hints to the rendering engine.
    • skip_newline — If true, attempt to keep the field on the same line as the previous field, depending on viewport width.
  • translations — Values for translatable fields by language context. The translatable fields are label, description and options.elements (for the select field type).

Remove a cart field

DELETE /admin/api/ecommerce/v1/cart_fields/1

This request deletes the given cart_field.

Example request:

DELETE http://helloworld.voog.com/admin/api/ecommerce/v1/cart_fields/1

Example response:

Status: 204 No Content

Remove all cart fields

DELETE /admin/api/ecommerce/v1/cart_fields

This request deletes all cart fields at once.

Example request:

DELETE http://helloworld.voog.com/admin/api/ecommerce/v1/cart_fields

Example response:

Status: 204 No Content