Skip to main content
POST
/
ecommerce
/
v2
/
apps
/
{app_id}
/
batch
/
categories
/
upsert
curl -X POST "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/batch/categories/upsert" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      {
        "name": "Pizzas",
        "description": "All our artisan pizzas",
        "image": "https://example.com/images/pizzas.jpg",
        "order": 1,
        "status": true,
        "branch": "BRANCH-DOWNTOWN"
      },
      {
        "name": "Beverages",
        "description": "Hot and cold beverages",
        "order": 2,
        "branch": "BRANCH-DOWNTOWN"
      },
      {
        "name": "Desserts",
        "order": 3
      }
    ]
  }'

{
  "message": "Batch upsert process initiated successfully",
  "count": 3,
  "jobs": 1
}
You can create or update categories in bulk by name. If a category with the same name already exists in the same store and branch, it is updated; otherwise, it is created.
​
app_id
string
required
Your store ID in Jelou Shop.
​
resources
object[]
required
List of categories to create or update (max. 500 per request).
The branch must be created before assigning it to a category. Use the Create branches endpoint to register it first.
curl -X POST "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/batch/categories/upsert" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      {
        "name": "Pizzas",
        "description": "All our artisan pizzas",
        "image": "https://example.com/images/pizzas.jpg",
        "order": 1,
        "status": true,
        "branch": "BRANCH-DOWNTOWN"
      },
      {
        "name": "Beverages",
        "description": "Hot and cold beverages",
        "order": 2,
        "branch": "BRANCH-DOWNTOWN"
      },
      {
        "name": "Desserts",
        "order": 3
      }
    ]
  }'

{
  "message": "Batch upsert process initiated successfully",
  "count": 3,
  "jobs": 1
}

​
Behavior

The endpoint returns 202 Accepted immediately. Categories are processed in the background.
Categories are identified by their name within the same store and branch. If one with that name already exists, it is updated instead of creating a new one.
If the branch code does not match any branch in the store, the category is created without an assigned branch.
If an image URL is provided, it is downloaded and stored in the background after the category is created. The URL must be public; private/internal URLs are rejected.
Use parent_id to nest categories. The parent must exist in the same store before the batch is processed. To build a new hierarchy, create the parent categories first, then send the children referencing their parent_id.
When order is greater than 0, it must be unique within the same level (app + parent category + branch). If two categories in the same batch share an order at the same level, or it clashes with an existing category, the request fails with 422. An order of 0 or null is treated as “unordered” and skips the uniqueness check.

​
Validation errors

FieldMessage
resourcesThe resources field is required.
resourcesAt least one category is required.
resourcesCannot process more than 500 categories at once.
resources.*.nameEach category must have a name.
resources.*.imageCategory image must be a valid URL.
resources.*.orderCategory order must be an integer. / Category order cannot be negative. / Category order cannot exceed 999999.
resources.*.orderOrder is duplicated within this batch for the same parent/branch. / Order is already assigned to another category.
resources.*.statusCategory status must be a boolean.
resources.*.parent_idParent category id must be an integer. / The parent category does not exist for this app.
resourcesThis app already has categories. Adding new categories would exceed the limit of .

​
Limits

  • Maximum 500 categories per request.
  • Total categories per store limit (configurable; defaults to 500). If the batch exceeds the remaining limit, the request fails with 422.
  • All categories are validated before processing.
Replace {app_id} with your store ID and YOUR_API_KEY with your API key.