API Conventions

The Vanilo REST API returns responses in a consistent manner, based on several conventions. These standards are described below.

The API definitions are based on and documented with the OpenAPI 3 Standard.

The Vanilo OpenAPI reference is available at: Vanilo Cloud API Reference.

Identifiers

Returned objects have identifiers returned as the id property. The format of these identifiers is varying, it can be:

numeric, examples: 3211, 1564578985;
textual, examples: PCD-7321, 602-1FKD-1ET1, color or 5f21ed4e1b;
UUID: 0c94aace-04ac-4da5-a57d-72f13f589406;

It is important that you treat all these identifiers as strings in your applications. Even though if you get an id that looks numeric, there's no guarantee that new entries will also have a numeric id.

Therefore, your application must treat every id coming from Vanilo as a string.

Date & Time Formats

Date and DateTime values are returned as strings formatted as defined by RFC 3339, section 5.6, for example:

date: 2019-07-21
date-time 2021-04-24T19:17:06.000000Z

All dates and times are in the UTC Timezone.

Collections

If a response returns a collection of items (eg. a list of products, a list of orders, etc) then the response is always being wrapped in the following "envelope":

{
  "data": [],
  "links": {
    "first": "https://your.shop/api/1.0/resource?page=1",
    "last": "https://your.shop/api/1.0/resource?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://your.shop/api/1.0/resource",
    "per_page": 100,
    "to": 2,
    "total": 2
  }
}

Items (Data)

The data property is an array that contains multiple objects of the same type (eg. products, orders, etc).

Filtering

Collections can be filtered by multiple criteria. The swagger spec of each resource contains their particular filters, but all of them follow the same convention, that's described below.

Filters are passed as query parameters: /api/1.0/orders?filter[user_id]=444.

Multiple filters can be passed: /api/1.0/orders?filter[status]=cancelled&filter[user_id]=888.

Multiple values can be passed, using colons as separator: /api/1.0/orders?filter[user_id]=444,888

To filter by data in deeper level, use the "dot notation": /api/1.0/orders?filter[billing_address.email][email protected]

The filters check for exact values by default. To get the items matching greater than/less than/not equals conditions you can use the colon notations like ?filter[created_at:gt]=2023-11-27:00:00:00.

The Table of Comparison Operators

Comparison	Notation	Example	Meaning
`>`	`gt`	`/api/1.0/orders?filter[id:gt]=37556`	Orders with id greater than 37556
`>=`	`gte`	`/api/1.0/orders?filter[id:gte]=41222`	Orders with id greater than or equal to 41222
`<`	`lt`	`/api/1.0/orders?filter[id:lt]=3550`	Orders with id less than 3550
`<=`	`lte`	`/api/1.0/orders?filter[id:lte]=1730`	Orders with id less than or equal to 1730
`!=`	`neq`	`/api/1.0/orders?filter[status:neq]=cancelled`	Orders with non-cancelled status

Further Examples:

Orders created between May 1 and May 8: /api/1.0/orders?filter[created_at:gte]=2023-05-01T00:00:00&filter[created_at:lte]=2023-05-08T23:59:59
Orders modified since a specific date: /api/1.0/orders?filter[updated_at:gt]=2023-09:07:15:30:00
Orders with non-cancelled and non-completed status: /api/1.0/orders?filter[status:neq]=cancelled,completed

Sorting

Sorting of the items happens via the query sort query parameter: /api/1.0/users?sort=name. This sorts the results in ascending order (A-Z).

To sort in descending order (Z-A) add a hyphen to the field: /api/1.0/users?sort=-name.

To sort by multiple columns, separate the column names by a colon: /api/1.0/users?sort=lastname,firstname

Including Sub-resources

Certain resources, like order, contain several sub-resources (eg. payments, shipments, adjustments) which are not included in the response by default. To include them with the response, use the includes query parameter.

Examples:

To include the payments with the orders: /api/1.0/orders?include=payments
To include the payments and the shipments with the orders: /api/1.0/orders?include=payments,shipments

Links

The links property takes the guesswork out of dealing with pagination: it gives you the relative links to the current page. Likely the most important entry for an API is the next element which gives you the link to the next page of items as long as there are more results. If there are no more results, it returns null.

Creating Resources

Creating resources can be done via POST requests to the collection, eg.: https://your.shop/api/1.0/products.

Whenever you create a resource, the response will have the following structure:

HTTP 201 status
Location header will contain the URL of the newly created resource
The payload is JSON that minimally contains a message property that describes the resource(s) created.

Example:

HTTP/1.1 201 Created
Date: Mon, 26 Apr 2021 12:22:40 GMT
Location: https://your.shop/api/1.0/products/KNCB-1131
Content-Type: application/json

{
  "message": "The product has been created"
}

Updating Resources

Resources can be updated using the PATCH method on an existing resource like https://your.shop/api/1.0/products/KNCB-1131

This allows partial update, meaning you only need to supply the fields in the payload that you want to update.

Successful responses after an update have the following traits:

HTTP 200 status
The payload is JSON that minimally contains a message property informing that the resource has been updated.

Example:

HTTP/1.1 200 OK
Date: Mon, 26 Apr 2021 19:18:40 GMT
Content-Type: application/json

{
  "message": "The product has been updated"
}

PUT - Idempotent Updates

Certain resources can be updated with PUT, which is an idempotent operation.

In short, "Idempotency" means that the effect of a request on a resource is independent of the number of times it is executed. If you execute a PUT request with the same parameters on a resource N times, the very first request will update the resource; but the subsequent requests will effectively not change anything.

Certain resources can be updated using the PUT method on an existing resource like https://your.shop/api/1.0/products/SKU123/taxons

The PUT method will fully replace the existing values.

Example:

PUT https://your.shop/api/1.0/products/SKU123/taxons

{
  "ids": ["35", "91"]
}

The effect of the operation will be that the taxons (category assignments) of the product identified by sku "SKU123" will be:

updated to the taxon with id 35 and 91;
if there were any former taxon assignments, those will be removed.

As a consequence, if you want to remove all the taxon assignments of the products, just send an empty array:

PUT https://your.shop/api/1.0/products/SKU123/taxons

{
  "ids": []
}

This will remove all the taxonomy assignments of the product.

Successful responses after a PUT update are the same as PATCH updates:

HTTP 200 status
The payload is JSON that minimally contains a message property informing that the resource has been updated.

Example:

HTTP/1.1 200 OK
Date: Mon, 17 Apr 2024 19:01:49 GMT
Content-Type: application/json

{
  "message": "The taxonomy assignments have been updated"
}

Deleting Resources

Use the DELETE method on an existing resource like https://your.shop/api/1.0/products/KNCB-1131 to remove it.

Possible responses are:

404 Not Found - if the resource was not found on the URL,
409 Conflict - if the resource can't be deleted because it's still needed.

After a successful deletion, you'll get a 204 No Content response without any payload. This means that getting a 204 is the confirmation of the deletion of the resource.

Example:

HTTP/1.1 204 No Content
Date: Mon,26 Apr 2021 17:26:44 GMT 
Cache-control: no-cache,private

API Conventions

Identifiers

Date & Time Formats

Collections

Items (Data)

Filtering

The Table of Comparison Operators

Sorting

Including Sub-resources

Links

Meta

Creating Resources

Updating Resources

PUT - Idempotent Updates

Deleting Resources