Skip to main content
Documentation & User Guides | Fotoware

Custom Order Data

Custom Order Data

The orderData attribute of the order and the itemData field of an ordered item are both arrays that may contain custom order fields containing custom, additional information about the order or each individual ordered item. These are key-value pairs that follow a schema that is defined in the site configuration. Custom order data may be entered by a customer when submitting an order. It may also be modified later by an administrator. API clients can also use custom order data to store additional context information in orders.

Values are arbitrary strings or boolean values, and IDs are opaque strings defined by the FotoWeb server:

  {"id": "ID1", "value": "foo"},
  {"id": "ID2", "value": "bar"},
  {"id": "ID3", "value": true},
  {"id": "ID4", "value": false},





id String ID of the custom order field
value String or Boolean Value of the custom order field

Field Configuration

The site configuration controls which fields are availablem what their IDs are and what values they can have. The configuration is separate for

  • The order as a whole (order fields). Values for order fields can be put into the orderData array of the shopping cart or an order.
  • individual order items (order item fields). Values for order item fields can be put into the itemData array of each ordered item in the orderItems array of the shopping cart or an order.

For each item in orderData or itemData, a field ID must be given in the id attribute. These field IDs can be obtained from the field configuration.

The value of each field must be a string, unless the field is a checkbox field (of type checkbox). Then the value must be either true or false.

The following request can be used to query the field configuration. It is part of both the order management API and the shopping cart API, so it is available to all authenticated API clients:



GET api_descriptor.order.config
Accept: application/vnd.fotoware.order-config+json
200 OK
Content-Type: application/vnd.fotoware.order-config+json

with the following response body:

  "orderFields": [{...}, ...],
  "itemFields": [{...}, ...]

The attributes orderFields and itemFields are both arrays of objects where each object describes one field and

  • orderFields is the set of order fields and
  • itemFields is the set of order item fields.

Each field object has the following format:

  "id": "...",
  "type": "text" | "checkbox" | "dropdown",
  "label": "...",
  "writable": true | false,
  "required": true | false,
  "multiValue": true | false,
  "multiLine": true | false,
  "validation": {
    "maxLength": 40 | null,
    "max": 500 | null,
    "min": 100 | null,
    "regex": "..." | null,
    "taxonomy": {
      "href": "..." | null,
      "strict": true | false
    } | null,
    "values": [...],
    "helpText": "..." | null






id String

ID of the field.

This string is defined by FotoWeb and not meant to be human-readable.

type String

Type of the field. Must be one of:

  • text: Text input field. Allowed values are all strings that fulfill all validation criteria.
  • checkbox: Check box. Allowed values are true and false.
  • dropdown: Dropdown box. Allowed values are given in the values attribute.
label String Human-readable label of the field "Publication Date"
writable Boolean Field can be edited by user.  
required Boolean Customer must enter a value for this field.  
multiValue Boolean Field can have multiple values  
multiLine Boolean

Text field supports multi-line input.

User interface SHOULD provide a multi-line text input field

validation.maxLength Integer Maximum number of characters in text field or null for unlimited  
validation.min Integer

Minimum numeric value in text field or null.

If not null, then only numeric values (decimal numbers) are accepted.

validation.max Integer

Maximum numeric value in text field or null.

If not null, then only numeric values (decimal numbers) are accepted.

validation.regex String

Regular expression or null.

If not null, then value must match this ECMAScript regular expression.


validation.taxonomy Object If not null, then a taxonomy is associated with the field. See fields below.  
validation.taxonomy.href Link (String)

URL of taxonomy. Refers to a "Taxonomy" representation.

A user interface SHOULD allow the user to choose items from that taxonomy which can be assigned to fields.


If true, then value MUST exist in the taxonomy. User must choose a value from the taxonomy or leave the field empty.

If false, then arbitrary values (that match all of the other validation criteria) can be entered alternatively to taxonomy items.

validation.values Array of Strings

If type is dropdown, this specifies the possible values that can be selected. All values must be strings.

It is not possible to enter other values. Other validation settings are ignored.

Set to null for types other than dropdown.

["Red", "Green", "Blue"]
validation.helpText String

Help text to display if validation fails.

If null, then the field does not have a specific help text, and a user interface SHOULD show a standard help text if validation fails.

"You must enter a valid date (YYYY-MM-DD)"

A user interface SHOULD perform all the validation specified by the field configuration. API requests to update an order or shopping cart will fail if

  • One or more fields do not fulfill their validation criteria OR
  • One or more required fields do not have a value.
  • Was this article helpful?