Custom Order Data

Last updated
Save as PDF
Share
1. Share
2. Tweet
3. Share

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},
  {...},
  ...
]

where

Attribute	Type	Description
`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:

Request	Response
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": [{...}, ...] }

Request

Response

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
  }
}

where

Attribute	Type	Description	Example
`id`	String	ID of the field. This string is defined by FotoWeb and not meant to be human-readable.	`0c821e42-9c3f-445d-bf65-6a3e0c3d4045`
`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.	`"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"`
`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.
`validation.taxonomy.strict`		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.