Responses

Basic JSON Structure

List response

Several endpoints return a list of resources. These resources may only contain a subset of the available attributes. In addition, the results are paginated for performance reasons.

A typical response containing multiple items looks like this:

data contains the actual items as an array

meta and links contain data related to Pagination

Object response

Endpoints returning individual resources return all available attributes for that resource. Blank fields are usually returned as null.

A typical response containing a single item looks like this:

data contains the actual item as an object

meta is usually null

links is omitted

References

Referencing a single object

References to another object will be defined as an object with id and type attributes:

Referencing multiple objects

References to multiple objects will be defined as an array of objects with id and type attributes:

Vouchers (Cards)

References to vouchers contain an extra attribute token:

Errors

If a request fails, the JSON response may contain an errors array with additional information:

source refers to the error's origin

detail contains a human readable error message (in English)

code is an identifier for the specific error (lowercase letters and underscore)

Attribute Types

Date and Time

Attributes denoting date and time are returned as strings conforming to ISO 8601.

• YYYY-MM-DD for dates • YYYY-MM-DDThh:mm:ss.sssZ for combined date and time

Monetary Values

Many JSON libraries return decimal values as floating point numbers which are inadequate for dealing with money. We therefore return monetary values as an object containing the amount in cents (as an integer) and the three-letter ISO 4217 currency code.

The following example shows a "balance" value of €1,200.50 (1200 euros and 50 cents):

When processing such values, make sure to use an appropriate data type.

Countries

Countries are represented as ISO 3166-1 numeric country codes, given as three-digit strings with leading zeros when needed.

The following example shows an address in Germany (country code 276)

Basic JSON Structure#

List response#

Object response#

References#

Referencing a single object#

Referencing multiple objects#

Vouchers (Cards)#

Errors#

Attribute Types#

Date and Time#

Monetary Values#

Countries#