Product Type API

Audience: Frontend engineers managing product types and their required variants.

Base URL: https://jethings-backend.fly.dev
Content-Type: application/json

Conventions

All responses are JSON.
Errors follow standard HTTP status codes with { message: string } body.
Unless noted, successful responses are 200 OK.
All endpoints require authentication via Bearer token.

Get All Product Types

GET /product-types Requires Authentication: Bearer token in Authorization header Retrieve all product types in the system with support for pagination, search, and filtering.

Query Parameters

Parameter	Type	Required	Default	Description
`page`	`number`	No	`1`	Page number for pagination
`limit`	`number`	No	`10`	Number of records per page (max: 100)
`search`	`string`	No	-	Search across nameEn, nameFr, nameAr, code, and description
`isActive`	`boolean`	No	-	Filter by active status (`true` or `false`)
`sortBy`	`string`	No	`createdAt`	Sort field: `createdAt`, `updatedAt`, `nameEn`, or `code`
`sortOrder`	`string`	No	`desc`	Sort order: `asc` or `desc`

Success Response

{
  "data": [
    {
      "id": "pt_123456",
      "code": "CLOTHING",
      "nameEn": "Clothing",
      "nameFr": "Vêtements",
      "nameAr": "ملابس",
      "description": "All types of clothing items",
      "icon": "https://example.com/icons/clothing.png",
      "isActive": true,
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

Response Fields

Field	Type	Description
`data`	`array`	Array of product type objects
`data[].id`	`string`	Product type unique identifier
`data[].code`	`string`	Product type code
`data[].nameEn`	`string`	Product type name in English
`data[].nameFr`	`string`	Product type name in French
`data[].nameAr`	`string`	Product type name in Arabic
`data[].description`	`string \| undefined`	Product type description
`data[].icon`	`string \| undefined`	Icon URL for the product type
`data[].isActive`	`boolean`	Whether the product type is active
`data[].createdAt`	`string`	Creation timestamp (ISO 8601)
`data[].updatedAt`	`string`	Last update timestamp (ISO 8601)
`pagination`	`object`	Pagination metadata
`pagination.page`	`number`	Current page number
`pagination.limit`	`number`	Number of items per page
`pagination.total`	`number`	Total number of product types
`pagination.totalPages`	`number`	Total number of pages
`pagination.hasNext`	`boolean`	Whether there is a next page
`pagination.hasPrev`	`boolean`	Whether there is a previous page

Possible Errors

401 Unauthorized: Missing or invalid authentication token
500 Internal Server Error: Server error

Example Requests

Basic Request (Default Pagination)

curl -X GET "https://jethings-backend.fly.dev/product-types" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

With Pagination

curl -X GET "https://jethings-backend.fly.dev/product-types?page=2&limit=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

With Search

curl -X GET "https://jethings-backend.fly.dev/product-types?search=clothing" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Filter by Active Status

curl -X GET "https://jethings-backend.fly.dev/product-types?isActive=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

With Sorting

curl -X GET "https://jethings-backend.fly.dev/product-types?sortBy=nameEn&sortOrder=asc" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Combined Filters

curl -X GET "https://jethings-backend.fly.dev/product-types?page=1&limit=10&search=lens&isActive=true&sortBy=code&sortOrder=asc" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Get Product Type Required Variants

GET /product-types/:productTypeId/required-variants Requires Authentication: Bearer token in Authorization header Retrieve all required variants associated with a specific product type.

Path Parameters

Parameter	Type	Required	Description
`productTypeId`	`string`	Yes	Product type ID (UUID format)

Success Response

{
  "productTypeId": "pt_123456",
  "requiredVariants": [
    {
      "id": "rv_123456",
      "variantName": "Size",
      "allowedValues": ["S", "M", "L", "XL"]
    },
    {
      "id": "rv_789012",
      "variantName": "Color",
      "allowedValues": ["Red", "Blue", "Green"]
    }
  ]
}

Response Fields

Field	Type	Description
`productTypeId`	`string`	The product type ID
`requiredVariants`	`array`	Array of required variant objects
`requiredVariants[].id`	`string`	Required variant unique identifier
`requiredVariants[].variantName`	`string \| null`	Name of the variant (e.g., “Size”, “Color”)
`requiredVariants[].allowedValues`	`string[] \| null`	Array of allowed values for this variant

Possible Errors

401 Unauthorized: Missing or invalid authentication token
404 Not Found: Product type not found
500 Internal Server Error: Server error

Example Request

curl -X GET "https://jethings-backend.fly.dev/product-types/pt_123456/required-variants" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Create Product Type with Variants

POST /product-types Requires Authentication: Bearer token in Authorization header Create a new product type along with its required variants in a single transaction.

Request Body

{
  "code": "CLOTHING",
  "nameEn": "Clothing",
  "nameFr": "Vêtements",
  "nameAr": "ملابس",
  "description": "All types of clothing items",
  "icon": "https://example.com/icons/clothing.png",
  "requiredVariants": [
    {
      "variantName": "Size",
      "allowedValues": ["S", "M", "L", "XL", "XXL"]
    },
    {
      "variantName": "Color",
      "allowedValues": ["Red", "Blue", "Green", "Black"]
    }
  ]
}

Request Body Fields

Field	Type	Required	Description
`code`	`string`	Yes	Product type code (unique identifier)
`nameEn`	`string`	Yes	Product type name in English
`nameFr`	`string`	Yes	Product type name in French
`nameAr`	`string`	Yes	Product type name in Arabic
`description`	`string`	No	Product type description
`icon`	`string`	No	Icon URL for the product type
`requiredVariants`	`array`	No	Array of required variants to create

Required Variant Object

Field	Type	Required	Description
`variantName`	`string`	Yes	Name of the variant (e.g., “Size”, “Color”, “Material”)
`allowedValues`	`string[]`	No	Array of allowed values for this variant. If not provided, the variant accepts any value.

Success Response

{
  "productType": {
    "id": "pt_123456",
    "code": "CLOTHING",
    "nameEn": "Clothing",
    "nameFr": "Vêtements",
    "nameAr": "ملابس",
    "description": "All types of clothing items",
    "icon": "https://example.com/icons/clothing.png",
    "isActive": true,
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  },
  "requiredVariants": [
    {
      "id": "rv_123456",
      "variantName": "Size",
      "allowedValues": ["S", "M", "L", "XL", "XXL"]
    },
    {
      "id": "rv_789012",
      "variantName": "Color",
      "allowedValues": ["Red", "Blue", "Green", "Black"]
    }
  ]
}

Response Fields

Field	Type	Description
`productType`	`object`	The created product type object
`requiredVariants`	`array`	Array of created required variant objects

Possible Errors

400 Bad Request: Invalid request data or validation errors
401 Unauthorized: Missing or invalid authentication token
409 Conflict: Product type code already exists
500 Internal Server Error: Server error

Example Request

curl -X POST "https://jethings-backend.fly.dev/product-types" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "code": "CLOTHING",
    "nameEn": "Clothing",
    "nameFr": "Vêtements",
    "nameAr": "ملابس",
    "description": "All types of clothing items",
    "icon": "https://example.com/icons/clothing.png",
    "requiredVariants": [
      {
        "variantName": "Size",
        "allowedValues": ["S", "M", "L", "XL", "XXL"]
      },
      {
        "variantName": "Color",
        "allowedValues": ["Red", "Blue", "Green", "Black"]
      }
    ]
  }'

Add Required Variants to Product Type

POST /product-types/:productTypeId/required-variants Requires Authentication: Bearer token in Authorization header Add one or more required variants to an existing product type.

Path Parameters

Parameter	Type	Required	Description
`productTypeId`	`string`	Yes	Product type ID (UUID format)

Request Body

{
  "requiredVariants": [
    {
      "variantName": "Material",
      "allowedValues": ["Cotton", "Polyester", "Wool"]
    },
    {
      "variantName": "Pattern",
      "allowedValues": null
    }
  ]
}

Request Body Fields

Field	Type	Required	Description
`requiredVariants`	`array`	Yes	Array of required variants to add

Required Variant Object

Field	Type	Required	Description
`variantName`	`string`	Yes	Name of the variant (e.g., “Size”, “Color”, “Material”)
`allowedValues`	`string[]`	No	Array of allowed values for this variant. If `null` or not provided, the variant accepts any value.

Success Response

{
  "productTypeId": "pt_123456",
  "requiredVariants": [
    {
      "id": "rv_345678",
      "variantName": "Material",
      "allowedValues": ["Cotton", "Polyester", "Wool"]
    },
    {
      "id": "rv_901234",
      "variantName": "Pattern",
      "allowedValues": null
    }
  ]
}

Response Fields

Field	Type	Description
`productTypeId`	`string`	The product type ID
`requiredVariants`	`array`	Array of created required variant objects
`requiredVariants[].id`	`string`	Required variant unique identifier
`requiredVariants[].variantName`	`string \| null`	Name of the variant
`requiredVariants[].allowedValues`	`string[] \| null`	Array of allowed values (null if unrestricted)

Possible Errors

400 Bad Request: Invalid request data or validation errors
401 Unauthorized: Missing or invalid authentication token
404 Not Found: Product type not found
500 Internal Server Error: Server error

Example Request

curl -X POST "https://jethings-backend.fly.dev/product-types/pt_123456/required-variants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "requiredVariants": [
      {
        "variantName": "Material",
        "allowedValues": ["Cotton", "Polyester", "Wool"]
      },
      {
        "variantName": "Pattern",
        "allowedValues": null
      }
    ]
  }'

DTOs Overview

GetProductTypesDto (Query Parameters)

{
  page?: number;           // Default: 1
  limit?: number;          // Default: 10, Max: 100
  search?: string;         // Search across nameEn, nameFr, nameAr, code, description
  isActive?: boolean;      // Filter by active status
  sortBy?: 'createdAt' | 'updatedAt' | 'nameEn' | 'code';  // Default: 'createdAt'
  sortOrder?: 'asc' | 'desc';  // Default: 'desc'
}

PaginatedProductTypesResponseDto

{
  data: ProductTypeResponseDto[];
  pagination: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNext: boolean;
    hasPrev: boolean;
  };
}

ProductTypeResponseDto

{
  id: string;
  code: string;
  nameEn: string;
  nameFr: string;
  nameAr: string;
  description?: string;
  icon?: string;
  isActive: boolean;
  createdAt: Date;
  updatedAt: Date;
}

CreateProductTypeWithVariantsDto

{
  code: string;
  nameEn: string;
  nameFr: string;
  nameAr: string;
  description?: string;
  icon?: string;
  requiredVariants?: CreateRequiredVariantDto[];
}

AddRequiredVariantToProductTypeDto

{
  requiredVariants: CreateRequiredVariantDto[];
}

CreateRequiredVariantDto

{
  variantName: string;
  allowedValues?: string[] | null;
}

RequiredVariantResponse

{
  id: string;
  variantName: string | null;
  allowedValues: string[] | null;
}

Business Logic

Product Type Creation Flow

User creates a product type with multilingual names (English, French, Arabic)
Product type is created with isActive: true by default
Required variants can be created in the same transaction
Each required variant can have optional allowed values to restrict input

Required Variants

Required variants define what attributes must be specified when creating products of this type
Examples: Size, Color, Material, Pattern, etc.
allowedValues can be:
- An array of specific values (e.g., ["S", "M", "L"]) - restricts to these values only
- null or omitted - allows any value to be entered
Variants are linked to product types through a many-to-many relationship

Transaction Safety

Creating a product type with variants uses a database transaction
If any variant creation fails, the entire operation is rolled back
Adding variants to an existing product type also uses transactions for consistency

Use Cases

Clothing: Size, Color, Material
Electronics: Model, Storage Capacity, Color
Food Items: Weight, Unit, Expiry Date
Custom Products: Any custom attributes defined by the business

Error Responses

Common Error Codes

400 Bad Request: Invalid request data or validation errors
401 Unauthorized: Missing or invalid authentication token
404 Not Found: Product type not found
409 Conflict: Product type code already exists
500 Internal Server Error: Server error

Error Response Format

{
  "message": "Error description",
  "statusCode": 400
}

Example Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

404 Not Found

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

409 Conflict

{
  "statusCode": 409,
  "message": "Product type with code 'CLOTHING' already exists",
  "error": "Conflict"
}

​Product Type API

​Conventions

​Get All Product Types

​Query Parameters

​Success Response

​Response Fields

​Possible Errors

​Example Requests

​Basic Request (Default Pagination)

​With Pagination

​With Search

​Filter by Active Status

​With Sorting

​Combined Filters

​Get Product Type Required Variants

​Path Parameters

​Success Response

​Response Fields

​Possible Errors

​Example Request

​Create Product Type with Variants

​Request Body

​Request Body Fields

​Required Variant Object

​Success Response

​Response Fields

​Possible Errors

​Example Request

​Add Required Variants to Product Type

​Path Parameters

​Request Body

​Request Body Fields

​Required Variant Object

​Success Response

​Response Fields

​Possible Errors

​Example Request

​DTOs Overview

​GetProductTypesDto (Query Parameters)

​PaginatedProductTypesResponseDto

​ProductTypeResponseDto

​CreateProductTypeWithVariantsDto

​AddRequiredVariantToProductTypeDto

​CreateRequiredVariantDto

​RequiredVariantResponse

​Business Logic

​Product Type Creation Flow

​Required Variants

​Transaction Safety

​Use Cases

​Error Responses

​Common Error Codes

​Error Response Format

​Example Error Responses

​400 Bad Request

​404 Not Found

​409 Conflict

Product Type API

Conventions

Get All Product Types

Query Parameters

Success Response

Response Fields

Possible Errors

Example Requests

Basic Request (Default Pagination)

With Pagination

With Search

Filter by Active Status

With Sorting

Combined Filters

Get Product Type Required Variants

Path Parameters

Success Response

Response Fields

Possible Errors

Example Request

Create Product Type with Variants

Request Body

Request Body Fields

Required Variant Object

Success Response

Response Fields

Possible Errors

Example Request

Add Required Variants to Product Type

Path Parameters

Request Body

Request Body Fields

Required Variant Object

Success Response

Response Fields

Possible Errors

Example Request

DTOs Overview

GetProductTypesDto (Query Parameters)

PaginatedProductTypesResponseDto

ProductTypeResponseDto

CreateProductTypeWithVariantsDto

AddRequiredVariantToProductTypeDto

CreateRequiredVariantDto

RequiredVariantResponse

Business Logic

Product Type Creation Flow

Required Variants

Transaction Safety

Use Cases

Error Responses

Common Error Codes

Error Response Format

Example Error Responses

400 Bad Request

404 Not Found

409 Conflict