Skip to main content
Send every request to https://dash.joinmarkt.com with:
The key must be allowed to access {storeId}. Category scopes also require the key owner to have manageCategories on that store. Successful list, get, create, and update responses are the JSON objects below. They are not wrapped in a data envelope. Errors use this shape:
These apply to every method on this page:
  • 401 Unauthorized, code UNAUTHORIZED — missing bearer token, unknown key, revoked key, or the account deletion has completed.
  • 401 API key expired, code UNAUTHORIZED.
  • 403 Forbidden, code FORBIDDEN — the key cannot access this store, the scope is missing, or the owner lacks manageCategories.
  • 429 Too many requests, code RATE_LIMITED — more than 120 requests in 60 seconds.
  • 500 code INTERNAL_ERROR, plus errorId. error is the fallback named on that method.
{categoryId} in a path is the category id, or a public id CAT- plus five groups of four characters from 23456789ABCDEFGHJKMNPQRSTUVWXYZ (for example CAT-2345-6789-ABCD-EFGH-JKMN). An unknown public id is looked up as a normal id and then follows the not-found errors below. A JSON body must be an object. storeId inside the body is removed before validation. The store in the path is the one that is written. Fields other than name, description, and image are dropped.

​
List categories

Scope: category:read Query:
  • page — integer, minimum 1, default 1
  • limit — integer, 1–100, default 50
An invalid page or limit returns 400 with code BAD_REQUEST. The error text is the Zod issues joined with ; . Categories are ordered by createdAt descending. A page past the end returns an empty categories array and the real total.
productCount is the number of products in the category. Unexpected failures return 500 Failed to list categories.

​
Create a category

Scope: category:create · 201 Body:
  • name — required string, trimmed, 1–200 characters. Unique per store
  • description — optional string, max 5000 characters, or null. An empty string is stored as null
  • image — optional string, max 500 characters, or null. An empty string is stored as null
productCount on create is 0. Errors:
  • 400 code BAD_REQUEST — invalid JSON (Invalid JSON), a body that is not an object (JSON body must be an object), or Zod validation (name: … style, joined with ; )
  • 400 code category_name_duplicate — Category name already exists for this store
  • 400 code category_validation — the category record fails the same name, description, and image checks after the merchant schema
  • 500 Failed to create category

​
Get a category

Scope: category:read The response uses the same fields as a category in List categories. productCount is the current number of products in the category. Errors:
  • 404 Category not found, code NOT_FOUND — unknown id, or the category belongs to another store
  • 500 Failed to load category

​
Update a category (PATCH)

Scope: category:update · 200 Same fields as create. Every field is optional. Omitted fields stay as they are. null clears description or image. An empty string is stored as an empty string. Create is the only write that stores an empty description or image as null.
The response uses the same fields as get. productCount is the count loaded before the update. Errors:
  • 400 code BAD_REQUEST — invalid JSON, a non-object body, or Zod validation
  • 400 code category_name_duplicate — Category name already exists for this store
  • 400 code category_validation — the saved name, description, or image fails validation
  • 404 Category not found, code NOT_FOUND
  • 500 Failed to update category

​
Update a category (PUT)

Scope: category:update · 200 PUT calls the same update as PATCH. Send the same partial object. Omitted fields stay as they are.
The response and errors match Update a category (PATCH), including 500 Failed to update category.

​
Delete a category

Scope: category:delete · 200 No body. Delete succeeds only when the category has no products.
Errors:
  • 400 code category_has_products — Cannot delete category with products. Please remove products first.
  • 404 Category not found, code NOT_FOUND
  • 500 Failed to delete category