Product API — response codes and objects

In this reference we will explore the structure of successful and error responses of product API as well as possible causes for various errors. For information about account API see Account API — response codes and objects

Product API is available at{barcode} endpoint where {barcode} is a placeholder for an actual EAN / UPC / ISBN barcode.

200 — Everything’s OK

A successful request like this:

curl -X GET -H 'Authorization: Bearer HERE_GOES_YOUR_JWT_TOKEN' -H 'Accept: application/json' \

returns a response with 200 response code and a ProductResponse object.

Note that we use Accept: application/json header to specify response content type (in this case JSON). But our API also supports application/xml content type, therefore all following response examples also include XML representation.

If Accept header is omitted then application/json is assumed by default.

For a formal description of the response object please refer to ProductResponse JSON schema and XML schema.

categories field is an array of objects containing id and title of each product category (or an empty array if the product is not yet categorized). Products are categorized using Google’s product taxonomy, please refer to this article for more information about taxonomy.

manufacturer field contains information about product manufacturer or brand. It may be null if the information is not yet available. Otherwise, at least manufacturer.titles is present.

Some companies and brands are identidied within our database. In this case field is present. This is a permanent identifier that can be used to resolve ambiguity between manufacturers with similar names.

relatedBrands contains information about other brands that may be related to a product or appear on the packaging (for example, distributors or collaborations). This is an array of objects of the same structure as in manufacturer field. All companies or brands in relatedBrands field are identified (contain id field).

images field is an array of objects containing URLs of product images (or an empty array if the product has no images yet).

For many products metadata field may be available (non-null). It aggregates product metadata like weight, nutritional value for a food product or number of pages for a pringt book. The set of available metadata may vary depending on the product type. For detailed information please see Product metadata.

404 — Product not found

You’ll get this kind of response if there is no product with the requested barcode in our database. 404 responses do not reduce your account balance.

403 — Access denied

You can get 403 response for a couple of reasons:

  • Authorization header containing your JWT is missing, malformed or invalid.
    In this case you’ll see a message JWT is missing or invalid, check Authorization header in the description field of the error response. You could check the tutorial for more information on how get JWT and pass it correctly.

  • Your account email is not confirmed.
    We require that you confirm your email address by visiting a confirmation link in a welcome email sent to you after registration.
    In case of this error description field contains a message Your account is not confirmed, please check your email for confirmation link.

  • Your JWT was revoked (look for JWT revoked message in the description field).
    You can revoke your current JWT (and effectively deny access to anyone who tries to use it) in your account area. This error is what you’ll see if you make an API request using one of the revoked JWTs.

  • Your JWT is expired (look for JWT expired message in the description field).
    JWT expires after one year since it was generated. If you get this error, you need to generate new JWT in your account area and replace the old one with freshly generated JWT.

  • Your account balance is empty.
    In this case description field contains a message Your account balance is empty.

400 — Barcode is invalid

400 response code indicates that the barcode you passed in your API request is invalid for some reason (contains invalid charachters, too short or too long, etc). Detailed information is given in the description field of an error response.

Related topics: ProductResponse JSON schema · ProductResponse XML schema · Billing