Brand API

The Brand API allows you to create, update, delete, and retrieve optical brands with advanced filtering, search, and pagination. Brands are associated with stores and can be searched and sorted by various criteria. The API supports bulk deletion operations and ensures brands are properly scoped to their respective stores.

Endpoint Details

Base URL: https://joptic.jethings.com

Required Headers

x-store-id: <store_id>
Authorization: Bearer <token>

Create Brand

Endpoint

Endpoint: POST /brand
Content-Type: application/json

Request Structure

The request body contains the brand name to create a new brand.

Request Body

{
  "brandName": "Acme Optics"
}

Request Body Fields

Field	Type	Required	Description
`brandName`	string	✅ Yes	Name of the brand to create

Create Brand Examples

Example 1: Create a New Brand

curl -X POST https://joptic.jethings.com/brand \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "brandName": "Acme Optics"
  }'

Success Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Optics",
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:00:00.000Z"
}

Update Brand

Endpoint

Endpoint: PUT /brand/:id
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
`id`	string	✅ Yes	UUID of the brand to update

Request Structure

The request body contains optional fields to update the brand. Only provided fields will be updated.

Request Body

{
  "brandName": "Updated Brand Name"
}

Request Body Fields

Field	Type	Required	Description
`brandName`	string	No	New name for the brand (max 255 characters)

The brandName field is optional. If not provided, the brand name will remain unchanged. Only fields that are explicitly provided will be updated.

Update Brand Examples

Example 1: Update Brand Name

curl -X PUT https://joptic.jethings.com/brand/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "brandName": "Updated Acme Optics"
  }'

Success Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Updated Acme Optics",
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T11:30:00.000Z"
}

Delete Brands

Endpoint

Endpoint: DELETE /brand
Content-Type: application/json

Request Structure

The request body contains an array of brand IDs to delete. This endpoint performs a bulk delete operation, removing the brand-store relationships (soft delete by setting isActive to false).

Request Body

{
  "ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001"
  ]
}

Request Body Fields

Field	Type	Required	Description
`ids`	string[]	✅ Yes	Array of brand UUIDs to delete (must not be empty)

This operation performs a soft delete by deactivating the brand-store relationship. Brands are not permanently deleted from the database, but they will no longer appear in GET requests for the store.

Delete Brands Examples

Example 1: Delete Single Brand

curl -X DELETE https://joptic.jethings.com/brand \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["550e8400-e29b-41d4-a716-446655440000"]
  }'

Success Response:

{
  "message": "Successfully deleted 1 brand(s)",
  "deletedCount": 1
}

Example 2: Bulk Delete Multiple Brands

curl -X DELETE https://joptic.jethings.com/brand \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "660e8400-e29b-41d4-a716-446655440001",
      "770e8400-e29b-41d4-a716-446655440002"
    ]
  }'

Success Response:

{
  "message": "Successfully deleted 3 brand(s)",
  "deletedCount": 3
}

Get All Brands

Endpoint

Endpoint: GET /brand

Query Parameters

Parameter	Type	Required	Default	Description
`search`	string	No	-	Search brands by name (partial match)
`page`	number	No	1	Page number for pagination
`limit`	number	No	10	Number of records per page
`sortBy`	string	No	createdAt	Sort field: “name”, “createdAt”, or “updatedAt”
`sortOrder`	string	No	desc	Sort order: “asc” or “desc”

The storeId is automatically extracted from the x-store-id header and does not need to be provided as a query parameter.

Sort Options

The sortBy parameter accepts the following values:

"name" - Sort by brand name alphabetically
"createdAt" - Sort by creation date (default)
"updatedAt" - Sort by last update date

Get Brands Examples

Example 1: Get All Brands (Default Pagination)

curl -X GET "https://joptic.jethings.com/brand" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Success Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Optics",
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:00:00.000Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Vision Pro",
      "createdAt": "2024-01-14T09:00:00.000Z",
      "updatedAt": "2024-01-14T09:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

Example 2: Search Brands with Filters

curl -X GET "https://joptic.jethings.com/brand?search=Acme&page=1&limit=20&sortBy=name&sortOrder=asc" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Example 3: Get Brands Sorted by Update Date

curl -X GET "https://joptic.jethings.com/brand?sortBy=updatedAt&sortOrder=desc" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Response Structures

Create Brand Response

{
  "id": "string (UUID)",
  "name": "string",
  "createdAt": "ISO date string",
  "updatedAt": "ISO date string"
}

Update Brand Response

{
  "id": "string (UUID)",
  "name": "string",
  "createdAt": "ISO date string",
  "updatedAt": "ISO date string"
}

Delete Brands Response

{
  "message": "string",
  "deletedCount": "number"
}

Get Brands Response

{
  "data": [
    {
      "id": "string (UUID)",
      "name": "string",
      "createdAt": "ISO date string",
      "updatedAt": "ISO date string"
    }
  ],
  "pagination": {
    "page": "number",
    "limit": "number",
    "total": "number",
    "totalPages": "number",
    "hasNext": "boolean",
    "hasPrev": "boolean"
  }
}

Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "brandName should not be empty",
  "error": "Bad Request"
}

Or for delete operations:

{
  "statusCode": 400,
  "message": "No brand IDs provided",
  "error": "Bad Request"
}

404 Not Found

{
  "statusCode": 404,
  "message": "Brand not found",
  "error": "Not Found"
}

Or for delete operations:

{
  "statusCode": 404,
  "message": "No valid brands found to delete",
  "error": "Not Found"
}

403 Forbidden

{
  "statusCode": 403,
  "message": "You do not have access to this store",
  "error": "Forbidden"
}

500 Internal Server Error

{
  "statusCode": 500,
  "message": "Failed to create brand",
  "error": "Internal Server Error"
}

Important Notes

Store Association

Brand-Store Relationship

Brands are associated with stores through brandStoreRelation
Only brands with active store relations are returned in GET requests
The storeId parameter filters brands for the specified store
Brands must have isActive: true in the store relation to appear in results
When creating a brand, it’s automatically associated with the store via x-store-id header

Store Access

Requires user to have access to the store
Store access is validated via x-store-id header
Missing or invalid store access raises ForbiddenException
Update and delete operations verify that the brand belongs to the specified store

Update Operations

Only brands that belong to the store (via active brandStoreRelation) can be updated
The brand must exist and have an active relationship with the store
If brand doesn’t exist or doesn’t belong to the store, a NotFoundException is raised
Only provided fields in the request body will be updated
The updatedAt timestamp is automatically updated

Delete Operations

Delete operations perform a soft delete by setting isActive: false in brandStoreRelation
Only brands that belong to the store can be deleted
Invalid or non-existent brand IDs are filtered out before deletion
The response includes the count of successfully deleted brands
If no valid brands are found, a NotFoundException is raised

Search Functionality

Partial Match

Search uses LIKE query with wildcards
%searchTerm%

Case Insensitive

Search is case-insensitive
Matches “acme”, “Acme”, “ACME”

Pagination

Default Behavior
Custom Pagination

{
  page: 1,
  limit: 10,
  sortBy: "createdAt",
  sortOrder: "desc"
}

Returns 10 most recent brands by default

{
  page: 2,
  limit: 50,
  sortBy: "name",
  sortOrder: "asc"
}

Customize page size and sorting

Sorting Options

The API supports sorting by:

Name (sortBy=name) - Alphabetical sorting
Created At (sortBy=createdAt) - Creation timestamp (default)
Updated At (sortBy=updatedAt) - Last update timestamp

Both ascending (asc) and descending (desc) orders are supported.

Pagination Metadata

The pagination object includes:

page - Current page number
limit - Number of items per page
total - Total number of brands matching the query
totalPages - Total number of pages
hasNext - Boolean indicating if there’s a next page
hasPrev - Boolean indicating if there’s a previous page

Summary

Authenticate

Obtain JWT token and ensure store access

Create Brand

POST request with brand name to create a new brand (automatically associated with store)

Retrieve Brands

GET request with optional filters, search, and pagination

Update Brand

PUT request with brand ID and optional brandName to update brand details

Delete Brands

DELETE request with array of brand IDs to bulk delete brands (soft delete)

Handle Response

Process brand data, pagination metadata, or deletion confirmation

This API provides comprehensive brand management for optical stores, including brand creation, updates, bulk deletion, flexible querying with search and filtering, and pagination capabilities.

Item API

Create and manage optical items

Customer API

Create and manage optical customers

J-optic

​Brand API

​Endpoint Details

​Required Headers

​Create Brand

​Endpoint

​Request Structure

​Request Body

​Request Body Fields

​Create Brand Examples

​Example 1: Create a New Brand

​Update Brand

​Endpoint

​Path Parameters

​Request Structure

​Request Body

​Request Body Fields

​Update Brand Examples

​Example 1: Update Brand Name

​Delete Brands

​Endpoint

​Request Structure

​Request Body

​Request Body Fields

​Delete Brands Examples

​Example 1: Delete Single Brand

​Example 2: Bulk Delete Multiple Brands

​Get All Brands

​Endpoint

​Query Parameters

​Sort Options

​Get Brands Examples

​Example 1: Get All Brands (Default Pagination)

​Example 2: Search Brands with Filters

​Example 3: Get Brands Sorted by Update Date

​Response Structures

​Create Brand Response

​Update Brand Response

​Delete Brands Response

​Get Brands Response

​Error Responses

​400 Bad Request

​404 Not Found

​403 Forbidden

​500 Internal Server Error

​Important Notes

​Store Association

​Search Functionality

Partial Match

Case Insensitive

​Pagination

​Sorting Options

​Pagination Metadata

​Summary

Item API

Customer API

Brand API

Endpoint Details

Required Headers

Create Brand

Endpoint

Request Structure

Request Body

Request Body Fields

Create Brand Examples

Example 1: Create a New Brand

Update Brand

Endpoint

Path Parameters

Request Structure

Request Body

Request Body Fields

Update Brand Examples

Example 1: Update Brand Name

Delete Brands

Endpoint

Request Structure

Request Body

Request Body Fields

Delete Brands Examples

Example 1: Delete Single Brand

Example 2: Bulk Delete Multiple Brands

Get All Brands

Endpoint

Query Parameters

Sort Options

Get Brands Examples

Example 1: Get All Brands (Default Pagination)

Example 2: Search Brands with Filters

Example 3: Get Brands Sorted by Update Date

Response Structures

Create Brand Response

Update Brand Response

Delete Brands Response

Get Brands Response

Error Responses

400 Bad Request

404 Not Found

403 Forbidden

500 Internal Server Error

Important Notes

Store Association

Search Functionality

Pagination

Sorting Options

Pagination Metadata

Summary