API reference

API reference#

POST products

This returns a list of products. You send a JSON body to search and filter the results. Described below.

GET products/32245

This returns a single product.

POST uri

This returns a list of products in a category, or single product, depending on what the URI leads to.

GET categories

Returns a list of categories.

Products Endpoint#

If you use POST products without a JSON body, you get all products back. You use the JSON body to filter and search the products, so you get fewer back.

The response object contains these:

• token: the session token that you always have in this API
• products: an array of products
• productCount: the total number of products without paging. So you can show "page 1 of 7" even if you only fetch 50 at a time.
• filter: is the filter values of the products you are viewing now, also without paging. So you know there are 35 red ones and 12 blue for example.

The request you send can contain these fields, everything is optional:

• skipFirst + limit: for paging
• categories: you want products in these categories
• search: free text search
• relatedProducts: when a product has relatedProducts and this is true, you get the complete data for those releated products. Otherwise you will get a small subset of the data back: only the media and product id.
• swatch.desc: filtering based on the color swatch (This is a client specific field, and not all Centra instances will have this field)
• items.name: filtering on specific item names
• onlyAvailable: true means you only get back products that are in stock or available for preorder. If you also specify items.name, those items must be available
• uri: filter on a product or category with a specific URI
• sortOrder: Sort returned products based on the specified field, ascending or descending. Currently you can filter on: uri, categoryItemSort, collectionUri, priceAsNumber, createdAt and modifiedAt, in either asc or desc order

Remember that there is a special case for related products: If a product relation is a variant, it will appear regardless of the relatedProducts parameter. However, if the relation is standard, it will only appear if relatedProducts is set to true.

If you select more "Product Filter Fields" in the Centra plugin settings, you can send them in the request and also get them back in the response in the "filter".

Example#

(notice ?pretty in the URL, this will return indented JSON)

This means products must match:

Free text search for "som" AND category = 709 AND swatch.desc = (Red OR Blue)

Paging is return 2 products, and skip the first 5.

So how do you know about category 709? Or that swatch.desc can be Red or Blue? This is what the "filter" in the response is for. It contains all possible filtering values, and a count of how many products matches each filtering value in the current set of filtered products and for all products.

Response:

The "filter" object has values for the field "swatch.desc" at the end of this JSON blob. And the last thing is value "Blue". "count":6 means there are 6 blue products in the current filtered set of products, "totalCount":12 means there are 12 blue products in total without filtering. The "data" object contains the data the frontend should use to display "Blue", it is the same data as the "swatch" on the product itself.

In the filter object, the only thing that changes depending on what you filter on is the "count". If you do not filter on anything count = totalCount.

Searching improvements since v2.92#

Using the free-text "search" field in POST /products endpoint now has the following improvements:

• Handling of non-Latin characters (e.g. “grön”, “små”),
• Matching Latin to non-Latin characters (searching “grön” will also match “gron”),
• Proximity (fuzzy) matching of phrases (searching “prdct” should match “product”).

For example, if you have a Product named “Test Product” which contains “Grön” in its description, you should be able to find it using phrases like: "test product", "test grön", "product gron", or even "prdct gron".

Routing#

You can post a uri to the POST products endpoint to filter out products that have a specific uri or that are in a category with a specific uri:

You will get 1 product back for this, if a product exists with the uri "jeans/slim-5-pocket-jeans-white". The "uri" object is the URI filtering:

• uri.uri is the uri
• uri.for is what the uri is for. It can be "category" and/or "product".

There is a more generic endpoint for this:

POST uri

You post a uri, and what the uri can be for. Just like POST products:

• uri is the uri
• for is what it is for. It can be "product" or "category".
• limit + skipFirst is paging, used when you get an array of products in a category or back to limit the number of products

The response changes depending on what was found. The plan is that we will add new things to this endpoint in the future, maybe CMS articles. You would then be able to POST "for":["category", "cms"] and get back CMS articles or a category of products. But you have to explicitly ask for it, you will not get back unknown results.

Example: URI leads to a product#

The response has "found": "product" and a "product" object:

Response:

Example: URI leads nowhere, API returns 404#

The only difference from the previous example is the request has "for":["category"] but we know this uri leads to a product. So no category with that URI is found. The API returns status code 404, and the response has an "errors" object (the rest of the API follows this convention, if there are errors then the response contains an "errors" object).

Response header:

HTTP/1.1 404 Not Found

Response:

Example: URI leads to a category, API returns a category and list of products#

The response contains "found": "category", the "category" object with the category name, and just like POST products it has "products", "productCount" and "filter". The content of these is exactly the same as POST products.

Response (edited to make it shorter):

Categories#

GET categories returns an array of categories like this:

This array is sorted in the order you set in the Centra admin. Notice that some categories in the array are under-categories of another category. You see this on last two, they have the field inCategory with the category id of the category they are a subcategory of. Also notice the name array and uri of these, they contain the full name and uri, of the main category and under-categories.

Products and categories#

A product has an array of items. An item is the thing you buy, what you add to a selection (also called cart, basket). For clothes, the items correspond to sizes of the product, and you would buy a sweater (product) in size M (item).

Products are organized into categories. Each category contains a list of products. A category can also contain categories. For example, one category could be "Clothes" and that could contain a category called "Sweaters".

A product object can contain a relatedProducts array, this array contains other product objects. These related products are related to the main product in some way, for example, it might be the same product in different colors.

Products and categories have a URI. A site normally has routes leading to specific products and categories based on the URIs. A category page should usually display the products in that category. You can ask the API what a specific URI points to, and also request all products in a specific category.

In a product listing (a category page), you would usually list only the main products and maybe indicate that a product has more colors when relatedProducts is not empty. When you view a single product, you would usually display all the related products along with it.

When you filter and search in the API, you are doing that on the main product plus all the related products. For example, if you filter on blue products, you can get back a product that is red but has a blue one in relatedProducts.

Example product#

With one related product

Item Table#

The product data has a itemTable with x and y arrays. This is the x and y axis of a table. And each item in the array of items has itemTableX and itemTableX integer fields.

You can use this to sort and display the items in the correct order in a table.

In the example above, the products have only a single item, so it does not illustrate how this works. This example, with jeans, has more. I have removed most data, only the itemTable and a few items are left:

You can display this as a table, where 4165-32694 is at a and 4165-32707 at b

Selections and orders#

A selection is an open order, or a shopping cart. You add items to the selection, the product items to buy.

If you have found an item 1313-19728 using the products endpoint, you can add it to your selection:

POST items/1313-19728 HTTP/1.1

You get back the selection. The response also has the session token. Use the token for the API-token header, like API-Token 297qi56173p6sm0l5bii30ois3

API Errors#

The API reports errors by returning response code 400 or above.

The response body will contain an "errors" object when there is an error. So there are no errors if there is no "errors".

Example:#

POST https://example.com/api/checkout/items/123-456

Response:

Payment flow#

1: Add something to the selection:#

POST https://example.com/api/checkout/items/1313-19728

In the response object you get back, there is

• token: the token to use for the "API-Token" header, session cookie
• selection: the selection (aka cart) with prices, currency
• products: the product data
• location: the customers country, we detect this with Geo-IP
• paymentMethods: the payment methods you can select
• paymentFields: the fields for the checkout.
• countries: all countries that we ship to. includes states for example for USA

2: (optional) change country#

PUT https://example.com/api/checkout/countries/SE

You get back the same structure as in 1. This can change prices/currency and in some cases can remove items that are not for sale in the selected country.

3: (optional) select a specific payment method#

PUT https://example.com/api/checkout/payment-methods/paypal

paypal here is from the paymentMethods in the previous responses. You get back the same structure as in #1.

4: Begin payment#

POST https://example.com/api/checkout/payment

Response:

This means you should redirect the visitor to the URL, to the payment page of paypal. The paymentReturnPage and paymentFailedPage in the request is where the visitor will return after the payment at paypal. These must on your frontend.

When the customer ends up on paymentFailedPage, you know that payment failed.

When the customer ends up on paymentReturnPage, you MUST ask the API if the payment was a success. It can still fail. You do this by forwarding the GET and POST variables that the visitor had when it accessed the paymentReturnPage to the API:

5: Get the result of the payment#

POST https://example.com/api/checkout/payment-result

You take the GET and POST variables that visitor had when it returned to the "paymentReturnPage" and send them to the API inside "paymentMethodFields".

Response (cut down):

This response is a success. But i will change the format of this to match the other responses better.

Payment flow, with klarna checkout#

Similar to the above, with the following changes:

3: select klarna checkout as payment method#

PUT https://example.com/api/checkout/payment-methods/klarna-checkout

4: Begin payment#

POST https://example.com/api/checkout/payment

Response:

This response has a different action called form, and a formHtml. You need to display this formHtml in the frontend. This thing from klarna should redirect the visitor to the paymentReturnPage or paymentFailedPage after payment. Klarna checkout gives us the customers address after the payment is done, so you only need to send the country to the API. We need the country to calculate prices correctly.

5: Get the result of the payment#

This should be exactly like for PayPal. You will get different data from klarna, but just pass it on to the API and it will tell you if the payment was successful

Payment response cases:#

POST https://example.com/api/checkout/payment can respond with an error, or one of 4 different actions:

• "action":"redirect" like PayPal above, redirect the client to the url in the response.
• "action":"form" like klarna-checkout above, display this htmlForm HTML-snippet. The HTML you get for klarna checkout i unusual, for other payment methods that have this response it is a HTML form that you need to POST in the visitors browser. This requires a server side page on the frontend since you cannot POST a form like this with Javascript (as far as i know).
• "action":"success" this means the payment succeeded at once (no need for step 5 from above). It happens with some invoice payments or when the credit card number is integrated in our checkout page. The response contains the order data that you would otherwise get from step 5.
• "action":"failed" this means the payment failed at once.

So far, these 4 cases have covered all payment integrations we have. If we implement these, the checkout should work with lots of payment providers. Klarna checkout is the most odd one, that probably needs specific treatment in the frontend.

Out of stock errors#

The API does a stock check at POST https://example.com/api/checkout/payment

If something is unavailable, you get back an error in errors, response code 410, and:

• unavailable contains a list of the items that were unavailable. These have been removed from the selection.
• the rest of the response looks like GET selection

Example, the selection.items has item=4-5, but quantity=5. the unavailable response looks like this:

Selection lines bulk update#

Checkout API selection bulk update allows efficiently make multiple changes to a selection in a single request.

Features list:

• Decreasing item quantity: reduce the quantity of an existing item in the selection.
• Removing item from selection: remove an item from the selection by setting its quantity to 0.
• Adding item quantity: increase the quantity of an existing item in the selection.
• Adding item to selection: you can also add new items to the selection with a specified quantity.

By consolidating these functionalities into a single request, the API endpoint fosters efficient and user-friendly management of items in a selection, accommodating a wide range of use cases and requirements.

The new API endpoint built for that purpose is PUT /items.

Request body#

The request body is split into 2 parts:

1. lines - array of line objects representing existing selection lines that will be updated. Each object consists of:
   • line - [String] Selection line identifier.
   • quantity - [Integer] Could be 0.
2. items - array of item objects representing items that will be added to the selection. Each object consists of:
   • item - [String] Shop item identifier (pdi_id-psi_id).
   • quantity [Integer] Must be greater than 0.

Example request body

Response codes#

• 200 OK - when the request is successful and items have been updated successfully, even partially.
• 400 Bad Request - when the request body is malformed or missing required fields, such as the items array or itemId and quantity fields in each item.
• 404 Not Found - when one or more items in the request body cannot be found in the basket.
• 406 Not Acceptable - when validations fail, e.g. an attempt to add an item that is already part of the selection and line update should be used.

Partial success is possible if request payload validation passes but for some reason line update or selection item addition fails. In such case selection response will contain additional field errors that will contain a list of failed operations.

For more information about error handling and responses, please refer to our Checkout API documentation.

Location#

The response from the api contains a location, the visitors country. This is detected from the IP address with Geo-IP. This usually works, but sometimes it does not. For example if you are shopping on a satellite phone. You cannot buy anything until you set a country. Then it will look like this:

The store may not ship to all countries. In this case, shipTo is false. And you cannot buy anything until you set a different country.

We do not detect state from Geo-IP. But we need it for the countries that have states (in the JSON datas "countries") because some countries that have states use state-specific tax. This sets country + state:

PUT https://example.com/api/checkout/countries/us/states/ca

PUT https://example.com/api/checkout/countries/PL

This is probably the most common, no states but shipTo is true:

If your code are connecting to the API from a server, instead of from the visitors browser, our Geo-IP lookup will always use the IP of your server. You need to have Geo-IP or a similar solution on your end, and tell the API what country the visitor is from.

Address search for Klarna Invoice payments#

POST https://example.com/api/checkout/address-search

Response

This is specifically for klarna invoice, in sweden. 410321-9202 is a personal idenitity number for a klarna test customer.

Localization#

The language is set automatically using GEO IP. The API returns data localized to the selected language.

You can change the language with:

PUT /languages/de

Or with the optional language field when you change country:

The response JSON contains a language object, and also a list of languages, and language fields on the location and countries:

The languages array is the possible languages, sorted by name. Use the language as the ID for selecting a language with the PUT /languages/{language}. If Centra is not localized, there will be only one language.

countries have a new language field, the default language for that country. Not sure if you have any use for this.

The language object is the selected language. This is what changes with PUT /languages/{language}

The location.language is just copied from countries. It is not the selected language.

Centra setup:#

In Centra you add new languages with System -> Languages. The "Language code" in Centra is the language id in the API.

The main Centra language (for not localized data) is called en and English by default, this is set up in the API plugin. For example, on a Swedish webshop the Centra data is probably in Swedish so it could make sense to set it as sv Swedish there.

User accounts#

Register:

• POST register
• POST login/{email}
• POST logout

Change the registered address, email, password:

• PUT address
• PUT email
• PUT password

Get pervious orders:

• POST orders

Password reset email sending and use:

• POST password-reset-email/{email}
• POST password-reset

Reminder of how the errors work in the API: If the response does not contain an "errors" object, there are no errors, the operation was successful. This is important here, for example the register operation does not return "register=success". (you also get a return code over 400 for errors)

When you are logged in, the response JSON contains a "loggedIn" object with the customers address. This is the data we have in Centra today, we have 1 address and no separate shipping addresses. The login is connected to the token:

3 operations will login:

• POST login/{email}
• POST register
• POST password-reset (this is used when you click on the link in the password reset email)

When you are logged in, the items you add to your selection are saved to your account. If you log in on a different computer you have the same items.

If you have items in the selection before you login, they are added to your saved selection. So it will contain your previously saved items plus these new ones.

If you log out, the login is removed from the token, and the selection is empty.

Please see the swagger for the input fields.

Some operations are only allowed if you are logged in. If you are not, they will respond with http code 403 Forbidden and

POST register#

This will register a new customer and login. If all goes well, you get back the regular JSON data with a "loggedIn" object.

Possible errors (there are more than this):

• response code 409: "email":"already registered"
• response code 406: "password":"not valid" if Centra thinks the password is not good enough. I dont know what criteria it has.

POST login/{email}#

This will login (yes, really). You get the same regular JSON back as with register.

If it fails you get response code 406 and errors with "password":"incorrect". This happens even if the email is not for a registered customer, this call will not reveal if a customer exists or not. You will find out if you use register or password-reset-email

POST logout#

This just logs out. You get the regular JSON response back, now the "loggedIn" is gone

POST password-reset-email/{email} + POST password-reset#

The first will send an email with a password reset link. You can specify the URI of the link, but the base URL must be set in the Centra checkout API plugin. So you cannot send emails to people that point to other domains.

The second is used when the customer clicks the link in the email. You need to pass on the hash from the link to the API.

Example:

The "linkUri" is optional, but Centra MUST be setup with a frontend URL.

The email contains this link:

https://mywebshop.example.com/my-uri/with/slashes?id=48&i=8a87a9e9fea3c3cfdea183b281ec43f3

When the customer clicks on it, you need to send the "id" and "i" and "newPassword" to the API:

After this the password is changed and you are logged in.

PUT address, PUT email, PUT password#

These just change the address, email and password. I hope the swagger is enough explanation.

POST orders#

This returns a list of the customers previous orders, with shipments and tracking links.

POST "from" and "size" paramters for paging. Without them all orders will be returned. If a customer has a lot of orders it could be slow to get all of them.

The response looks similar to the regular JSON response, except it contains an "orders" object that is an array of orders. And a "ordersPaging" object that keeps track of paging.

Example:

Response:

The orders do have shipments on them, although not in the example abve. If an order is shipped, it has an array of shipments in "shipments" like this: