Product Categories Endpoints

Product Categories API endpoints.

---

Overview

Method	Endpoint	Description
GET	/api/v1/product-categories/external-category-mappings	List External Category Mappings
POST	/api/v1/product-categories/external-category-mappings	Create External Category Mapping
POST	/api/v1/product-categories/external-category-mappings/bulk	Bulk Upsert External Category Mappings
POST	/api/v1/product-categories/external-category-mappings/preview	Preview Mapping
DELETE	/api/v1/product-categories/external-category-mappings/{mapping_id}	Delete External Category Mapping
GET	/api/v1/product-categories/product-families	List Product Families
POST	/api/v1/product-categories/product-families	Create Product Family
PATCH	/api/v1/product-categories/product-families/{family_id}	Update Product Family
GET	/api/v1/product-categories/product-type-records	List Product Types
POST	/api/v1/product-categories/product-type-records	Create Product Type
PATCH	/api/v1/product-categories/product-type-records/{type_id}	Update Product Type
GET	/api/v1/product-categories/unmapped-external-values	List Unmapped External Values
GET	/api/v1/product-categories/unmapped-external-values/{unmapped_value_id}/products	List Products For Unmapped Value

---

API Reference

Sartiq Backend Server - Product Categories 0.1.0

product-categories

---

GET /api/v1/product-categories/product-placements

List Product Placements

Description

List all valid ProductPlacement enum values with display labels.

Discovery endpoint used by FE rule editors to populate the PLACEMENT selector for GuidelinesShotTypeRule rows without hardcoding the enum. Static — no DB hit.

Responses

200 OK

application/json

{
    "data": [
        {
            "value": "upper_body",
            "label": "string"
        }
    ],
    "count": 0
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "data": {
            "items": {
                "$ref": "#/components/schemas/ProductPlacementOption"
            },
            "type": "array",
            "title": "Data"
        },
        "count": {
            "type": "integer",
            "title": "Count"
        }
    },
    "type": "object",
    "required": [
        "data",
        "count"
    ],
    "title": "ProductPlacementsPublic",
    "description": "Collection wrapper for ProductPlacement enum values.\n\nMirrors the ``ProductFamiliesPublic`` / ``ProductTypesPublic``\nshape so frontends can reuse the same handling code."
}

---

GET /api/v1/product-categories/product-families

List Product Families

Description

List all product families.

Responses

200 OK

application/json

{
    "data": [
        {
            "id": "839bf21b-f35c-481b-96b5-799c6cfe473f",
            "slug": "string",
            "name": "string"
        }
    ],
    "count": 0
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "data": {
            "items": {
                "$ref": "#/components/schemas/ProductFamilyPublic"
            },
            "type": "array",
            "title": "Data"
        },
        "count": {
            "type": "integer",
            "title": "Count"
        }
    },
    "type": "object",
    "required": [
        "data",
        "count"
    ],
    "title": "ProductFamiliesPublic"
}

---

POST /api/v1/product-categories/product-families

Create Product Family

Description

Create a new product family (admin only).

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No

Request body

application/json

{
    "slug": "string",
    "name": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "slug": {
            "type": "string",
            "maxLength": 50,
            "title": "Slug"
        },
        "name": {
            "type": "string",
            "maxLength": 100,
            "title": "Name"
        }
    },
    "type": "object",
    "required": [
        "slug",
        "name"
    ],
    "title": "ProductFamilyCreate"
}

Responses

201 Created422 Unprocessable Entity

application/json

{
    "id": "5919b0d7-5208-4a55-bb3c-cf5e7b4cdc3e",
    "slug": "string",
    "name": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "slug": {
            "type": "string",
            "title": "Slug"
        },
        "name": {
            "type": "string",
            "title": "Name"
        }
    },
    "type": "object",
    "required": [
        "id",
        "slug",
        "name"
    ],
    "title": "ProductFamilyPublic"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

PATCH /api/v1/product-categories/product-families/{family_id}

Update Product Family

Description

Update a product family (admin only).

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
family_id	path	string		No

Request body

application/json

{
    "name": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "name": {
            "anyOf": [
                {
                    "type": "string",
                    "maxLength": 100
                },
                {
                    "type": "null"
                }
            ],
            "title": "Name"
        }
    },
    "type": "object",
    "title": "ProductFamilyUpdate"
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "id": "0c87e7cf-9855-49f6-a77c-69eeeb1f2a7b",
    "slug": "string",
    "name": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "slug": {
            "type": "string",
            "title": "Slug"
        },
        "name": {
            "type": "string",
            "title": "Name"
        }
    },
    "type": "object",
    "required": [
        "id",
        "slug",
        "name"
    ],
    "title": "ProductFamilyPublic"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /api/v1/product-categories/product-type-records

List Product Types

Description

List all product types, optionally filtered by family slug.

Input parameters

Parameter	In	Type	Default	Nullable	Description
family_slug	query			No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "data": [
        {
            "id": "b0221cb8-0d01-4568-b32b-6f1d99dd7374",
            "slug": "string",
            "name": "string",
            "family": {
                "id": "16086db3-03de-4f8b-a13e-f0a6aa20421c",
                "slug": "string",
                "name": "string"
            },
            "placement": null,
            "layer_order": null,
            "zone": "head"
        }
    ],
    "count": 0
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "data": {
            "items": {
                "$ref": "#/components/schemas/ProductTypePublic"
            },
            "type": "array",
            "title": "Data"
        },
        "count": {
            "type": "integer",
            "title": "Count"
        }
    },
    "type": "object",
    "required": [
        "data",
        "count"
    ],
    "title": "ProductTypesPublic"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

POST /api/v1/product-categories/product-type-records

Create Product Type

Description

Create a new product type (admin only).

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No

Request body

application/json

{
    "slug": "string",
    "name": "string",
    "family_id": "c0e2699e-b033-4fe6-ba2b-cfe6b21e719d",
    "placement": null,
    "layer_order": null,
    "zone": "head"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "slug": {
            "type": "string",
            "maxLength": 50,
            "title": "Slug"
        },
        "name": {
            "type": "string",
            "maxLength": 100,
            "title": "Name"
        },
        "family_id": {
            "type": "string",
            "format": "uuid",
            "title": "Family Id"
        },
        "placement": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/ProductPlacement",
                    "maxLength": 20
                },
                {
                    "type": "null"
                }
            ]
        },
        "layer_order": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Layer Order"
        },
        "zone": {
            "$ref": "#/components/schemas/ProductZone",
            "default": "upperbody"
        }
    },
    "type": "object",
    "required": [
        "slug",
        "name",
        "family_id"
    ],
    "title": "ProductTypeCreate"
}

Responses

201 Created422 Unprocessable Entity

application/json

{
    "id": "c45d0f03-cb36-4da6-8f2c-ee883d150cd1",
    "slug": "string",
    "name": "string",
    "family": {
        "id": "2cc54698-140a-4b79-82a7-8e35797c7f63",
        "slug": "string",
        "name": "string"
    },
    "placement": null,
    "layer_order": null,
    "zone": "head"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "slug": {
            "type": "string",
            "title": "Slug"
        },
        "name": {
            "type": "string",
            "title": "Name"
        },
        "family": {
            "$ref": "#/components/schemas/ProductFamilyPublic"
        },
        "placement": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/ProductPlacement"
                },
                {
                    "type": "null"
                }
            ]
        },
        "layer_order": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Layer Order"
        },
        "zone": {
            "$ref": "#/components/schemas/ProductZone"
        }
    },
    "type": "object",
    "required": [
        "id",
        "slug",
        "name",
        "family",
        "zone"
    ],
    "title": "ProductTypePublic"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

PATCH /api/v1/product-categories/product-type-records/{type_id}

Update Product Type

Description

Update a product type (admin only).

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
type_id	path	string		No

Request body

application/json

{
    "name": null,
    "family_id": null,
    "placement": null,
    "layer_order": null,
    "zone": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "name": {
            "anyOf": [
                {
                    "type": "string",
                    "maxLength": 100
                },
                {
                    "type": "null"
                }
            ],
            "title": "Name"
        },
        "family_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Family Id"
        },
        "placement": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/ProductPlacement",
                    "maxLength": 20
                },
                {
                    "type": "null"
                }
            ]
        },
        "layer_order": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Layer Order"
        },
        "zone": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/ProductZone"
                },
                {
                    "type": "null"
                }
            ]
        }
    },
    "type": "object",
    "title": "ProductTypeUpdate"
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "id": "4eb830d0-7e2e-47d8-a59a-af1f6213dbb6",
    "slug": "string",
    "name": "string",
    "family": {
        "id": "bde8154c-f3ef-4f00-9602-6e98acc23ddb",
        "slug": "string",
        "name": "string"
    },
    "placement": null,
    "layer_order": null,
    "zone": "head"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "slug": {
            "type": "string",
            "title": "Slug"
        },
        "name": {
            "type": "string",
            "title": "Name"
        },
        "family": {
            "$ref": "#/components/schemas/ProductFamilyPublic"
        },
        "placement": {
            "anyOf": [
                {
                    "$ref": "#/components/schemas/ProductPlacement"
                },
                {
                    "type": "null"
                }
            ]
        },
        "layer_order": {
            "anyOf": [
                {
                    "type": "integer"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Layer Order"
        },
        "zone": {
            "$ref": "#/components/schemas/ProductZone"
        }
    },
    "type": "object",
    "required": [
        "id",
        "slug",
        "name",
        "family",
        "zone"
    ],
    "title": "ProductTypePublic"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /api/v1/product-categories/external-category-mappings

List External Category Mappings

Description

List external category mappings, optionally filtered by brand and/or mapping type (admin only).

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
brand	query			No
mapping_type	query			No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "data": [
        {
            "id": "2f960e02-6e8f-4d6d-a690-2ea0e675e695",
            "brand": "string",
            "mapping_type": "construction_type",
            "external_value": "string",
            "product_type_id": null,
            "gender": null,
            "age_class": null
        }
    ],
    "count": 0
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "data": {
            "items": {
                "$ref": "#/components/schemas/ExternalCategoryMappingPublic"
            },
            "type": "array",
            "title": "Data"
        },
        "count": {
            "type": "integer",
            "title": "Count"
        }
    },
    "type": "object",
    "required": [
        "data",
        "count"
    ],
    "title": "ExternalCategoryMappingsPublic"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

POST /api/v1/product-categories/external-category-mappings

Create External Category Mapping

Description

Create a new external category mapping (admin only).

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No

Request body

application/json

{
    "brand": "string",
    "mapping_type": "construction_type",
    "external_value": "string",
    "product_type_id": null,
    "gender": null,
    "age_class": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "brand": {
            "type": "string",
            "maxLength": 50,
            "title": "Brand"
        },
        "mapping_type": {
            "$ref": "#/components/schemas/MappingType"
        },
        "external_value": {
            "type": "string",
            "maxLength": 255,
            "title": "External Value"
        },
        "product_type_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Product Type Id"
        },
        "gender": {
            "anyOf": [
                {
                    "type": "string",
                    "enum": [
                        "MALE",
                        "FEMALE",
                        "UNISEX"
                    ]
                },
                {
                    "type": "null"
                }
            ],
            "title": "Gender"
        },
        "age_class": {
            "anyOf": [
                {
                    "type": "string",
                    "enum": [
                        "newborn_0_3y",
                        "child_3_7y",
                        "teen_8_14y",
                        "adult"
                    ]
                },
                {
                    "type": "null"
                }
            ],
            "title": "Age Class"
        }
    },
    "type": "object",
    "required": [
        "brand",
        "mapping_type",
        "external_value"
    ],
    "title": "ExternalCategoryMappingCreate"
}

Responses

201 Created422 Unprocessable Entity

application/json

{
    "id": "4e6ed727-f9cf-40db-9ce7-d41ff27f99e0",
    "brand": "string",
    "mapping_type": "construction_type",
    "external_value": "string",
    "product_type_id": null,
    "gender": null,
    "age_class": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "brand": {
            "type": "string",
            "title": "Brand"
        },
        "mapping_type": {
            "$ref": "#/components/schemas/MappingType"
        },
        "external_value": {
            "type": "string",
            "title": "External Value"
        },
        "product_type_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Product Type Id"
        },
        "gender": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Gender"
        },
        "age_class": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Age Class"
        }
    },
    "type": "object",
    "required": [
        "id",
        "brand",
        "mapping_type",
        "external_value"
    ],
    "title": "ExternalCategoryMappingPublic"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

POST /api/v1/product-categories/external-category-mappings/bulk

Bulk Upsert External Category Mappings

Description

Bulk upsert external category mappings (admin only).

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No

Request body

application/json

[
    {
        "brand": "string",
        "mapping_type": "construction_type",
        "external_value": "string",
        "product_type_id": null,
        "gender": null,
        "age_class": null
    }
]

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "items": {
        "$ref": "#/components/schemas/ExternalCategoryMappingCreate"
    },
    "type": "array",
    "title": "Body"
}

Responses

201 Created422 Unprocessable Entity

application/json

{
    "data": [
        {
            "id": "697fd138-4c53-474c-9470-d264fdb69354",
            "brand": "string",
            "mapping_type": "construction_type",
            "external_value": "string",
            "product_type_id": null,
            "gender": null,
            "age_class": null
        }
    ],
    "count": 0
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "data": {
            "items": {
                "$ref": "#/components/schemas/ExternalCategoryMappingPublic"
            },
            "type": "array",
            "title": "Data"
        },
        "count": {
            "type": "integer",
            "title": "Count"
        }
    },
    "type": "object",
    "required": [
        "data",
        "count"
    ],
    "title": "ExternalCategoryMappingsPublic"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

DELETE /api/v1/product-categories/external-category-mappings/{mapping_id}

Delete External Category Mapping

Description

Delete an external category mapping (admin only).

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
mapping_id	path	string		No

Responses

204 No Content422 Unprocessable Entity

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /api/v1/product-categories/unmapped-external-values

List Unmapped External Values

Description

List unmapped external values with product counts (admin only).

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
brand	query			No
field_name	query			No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "data": [
        {
            "id": "42fa7510-7af5-4163-85fb-cb636753e7cc",
            "brand": "string",
            "mapping_type": "construction_type",
            "external_value": "string",
            "field_name": "string",
            "occurrence_count": 0,
            "product_count": 0,
            "created_at": "2022-04-13T15:42:05.901Z"
        }
    ],
    "count": 0
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "data": {
            "items": {
                "$ref": "#/components/schemas/UnmappedExternalValuePublic"
            },
            "type": "array",
            "title": "Data"
        },
        "count": {
            "type": "integer",
            "title": "Count"
        }
    },
    "type": "object",
    "required": [
        "data",
        "count"
    ],
    "title": "UnmappedExternalValuesPublic"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /api/v1/product-categories/unmapped-external-values/{unmapped_value_id}/products

List Products For Unmapped Value

Description

List products linked to a specific unmapped external value (admin only).

Returns lightweight product summaries including brand_metadata (raw OVS data) so the UI can display the source fields that caused the unmapped hit.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
unmapped_value_id	path	string		No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "data": [
        {
            "id": "6b9360ff-0efb-4c14-abef-66636aa9ef67",
            "sku": null,
            "name": "string",
            "brand": null,
            "cover_image_url": null,
            "product_family": null,
            "product_type": null,
            "gender": null,
            "age_class": null,
            "brand_metadata": null
        }
    ],
    "count": 0
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "data": {
            "items": {
                "$ref": "#/components/schemas/UnmappedProductSummary"
            },
            "type": "array",
            "title": "Data"
        },
        "count": {
            "type": "integer",
            "title": "Count"
        }
    },
    "type": "object",
    "required": [
        "data",
        "count"
    ],
    "title": "UnmappedProductsPublic"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /api/v1/product-categories/unmapped-products

List Unmapped Products

Description

List products that have unmapped external values, ordered by count descending (admin only).

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
brand	query			No
limit	query	integer	50	No
skip	query	integer	0	No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "data": [
        {
            "id": "9cf2dd7d-9635-490a-8f74-29e25fecfd47",
            "sku": null,
            "name": "string",
            "brand": null,
            "cover_image_url": null,
            "product_family": null,
            "product_type": null,
            "gender": null,
            "age_class": null,
            "unmapped_value_count": 0
        }
    ],
    "count": 0
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "data": {
            "items": {
                "$ref": "#/components/schemas/UnmappedProductListItem"
            },
            "type": "array",
            "title": "Data"
        },
        "count": {
            "type": "integer",
            "title": "Count"
        }
    },
    "type": "object",
    "required": [
        "data",
        "count"
    ],
    "title": "UnmappedProductListPublic"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /api/v1/product-categories/unmapped-products/{product_id}

Get Unmapped Product Detail

Description

Get a product with all its unmapped external values (admin only).

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
product_id	path	string		No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "product": {
        "id": "2ec2cff2-21e4-46b0-b52b-0954d8793454",
        "sku": null,
        "name": "string",
        "brand": null,
        "cover_image_url": null,
        "product_family": null,
        "product_type": null,
        "gender": null,
        "age_class": null,
        "brand_metadata": null
    },
    "unmapped_values": [
        {
            "id": "648a6bf3-6076-4f69-8c0d-3829055606fa",
            "brand": "string",
            "mapping_type": "construction_type",
            "external_value": "string",
            "field_name": "string",
            "occurrence_count": 0,
            "created_at": "2022-04-13T15:42:05.901Z"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "product": {
            "$ref": "#/components/schemas/UnmappedProductSummary"
        },
        "unmapped_values": {
            "items": {
                "$ref": "#/components/schemas/UnmappedValueForProduct"
            },
            "type": "array",
            "title": "Unmapped Values"
        }
    },
    "type": "object",
    "required": [
        "product",
        "unmapped_values"
    ],
    "title": "UnmappedProductDetailPublic",
    "description": "Product detail with all its unmapped values."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

POST /api/v1/product-categories/unmapped-products/reimport-all

Reimport All Unmapped Products

Description

Re-import all products that have unmapped values from OVS (admin only).

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No

Responses

200 OK

application/json

{
    "total": 0,
    "succeeded": 0,
    "failed": 0,
    "results": [
        {
            "product_id": "704c6cbe-a14d-4d05-83aa-385d7d231153",
            "sku": null,
            "status": "string",
            "message": "string"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "total": {
            "type": "integer",
            "title": "Total"
        },
        "succeeded": {
            "type": "integer",
            "title": "Succeeded"
        },
        "failed": {
            "type": "integer",
            "title": "Failed"
        },
        "results": {
            "items": {
                "$ref": "#/components/schemas/ReimportResultPublic"
            },
            "type": "array",
            "title": "Results"
        }
    },
    "type": "object",
    "required": [
        "total",
        "succeeded",
        "failed",
        "results"
    ],
    "title": "BulkReimportResultPublic"
}

---

POST /api/v1/product-categories/unmapped-products/{product_id}/reimport

Reimport Product

Description

Re-import a single product from OVS, clearing old unmapped entries (admin only).

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
product_id	path	string		No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "product_id": "721f6947-3fb7-435e-9656-e94d9f13b0de",
    "sku": null,
    "status": "string",
    "message": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "product_id": {
            "type": "string",
            "format": "uuid",
            "title": "Product Id"
        },
        "sku": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Sku"
        },
        "status": {
            "type": "string",
            "title": "Status"
        },
        "message": {
            "type": "string",
            "title": "Message"
        }
    },
    "type": "object",
    "required": [
        "product_id",
        "status",
        "message"
    ],
    "title": "ReimportResultPublic"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

POST /api/v1/product-categories/external-category-mappings/preview

Preview Mapping

Description

Dry-run a candidate mapping against a product without saving anything.

Shows what the product's classification fields would become if this mapping were created. Useful for the admin UI to let operators verify before committing.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No

Request body

application/json

{
    "brand": "string",
    "mapping_type": "construction_type",
    "external_value": "string",
    "product_type_id": null,
    "gender": null,
    "age_class": null,
    "product_id": "91b378b3-717a-4971-b78f-aaea15f0bb01"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "brand": {
            "type": "string",
            "maxLength": 50,
            "title": "Brand"
        },
        "mapping_type": {
            "$ref": "#/components/schemas/MappingType"
        },
        "external_value": {
            "type": "string",
            "maxLength": 255,
            "title": "External Value"
        },
        "product_type_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Product Type Id"
        },
        "gender": {
            "anyOf": [
                {
                    "type": "string",
                    "enum": [
                        "MALE",
                        "FEMALE",
                        "UNISEX"
                    ]
                },
                {
                    "type": "null"
                }
            ],
            "title": "Gender"
        },
        "age_class": {
            "anyOf": [
                {
                    "type": "string",
                    "enum": [
                        "newborn_0_3y",
                        "child_3_7y",
                        "teen_8_14y",
                        "adult"
                    ]
                },
                {
                    "type": "null"
                }
            ],
            "title": "Age Class"
        },
        "product_id": {
            "type": "string",
            "format": "uuid",
            "title": "Product Id"
        }
    },
    "type": "object",
    "required": [
        "brand",
        "mapping_type",
        "external_value",
        "product_id"
    ],
    "title": "MappingPreviewRequest",
    "description": "Dry-run a candidate mapping against a specific product."
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "product_id": "f632f393-d268-4a66-a73e-74f6fc8de07d",
    "before_product_type": null,
    "before_product_family": null,
    "before_gender": null,
    "before_age_class": null,
    "after_product_type": null,
    "after_product_family": null,
    "after_gender": null,
    "after_age_class": null,
    "changes": [
        "string"
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "product_id": {
            "type": "string",
            "format": "uuid",
            "title": "Product Id"
        },
        "before_product_type": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Before Product Type"
        },
        "before_product_family": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Before Product Family"
        },
        "before_gender": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Before Gender"
        },
        "before_age_class": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Before Age Class"
        },
        "after_product_type": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "After Product Type"
        },
        "after_product_family": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "After Product Family"
        },
        "after_gender": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "After Gender"
        },
        "after_age_class": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "After Age Class"
        },
        "changes": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Changes"
        }
    },
    "type": "object",
    "required": [
        "product_id",
        "changes"
    ],
    "title": "MappingPreviewResult",
    "description": "What the product would look like after applying the mapping."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

Schemas

BulkReimportResultPublic

Name	Type	Description
failed	integer
results	Array<ReimportResultPublic>
succeeded	integer
total	integer

ExternalCategoryMappingCreate

Name	Type	Description
age_class
brand	string
external_value	string
gender
mapping_type	MappingType
product_type_id

ExternalCategoryMappingPublic

Name	Type	Description
age_class
brand	string
external_value	string
gender
id	string(uuid)
mapping_type	MappingType
product_type_id

ExternalCategoryMappingsPublic

Name	Type	Description
count	integer
data	Array<ExternalCategoryMappingPublic>

HTTPValidationError

Name	Type	Description
detail	Array<ValidationError>

MappingPreviewRequest

Name	Type	Description
age_class
brand	string
external_value	string
gender
mapping_type	MappingType
product_id	string(uuid)
product_type_id

MappingPreviewResult

Name	Type	Description
after_age_class
after_gender
after_product_family
after_product_type
before_age_class
before_gender
before_product_family
before_product_type
changes	Array<string>
product_id	string(uuid)

MappingType

Type: string

ProductFamiliesPublic

Name	Type	Description
count	integer
data	Array<ProductFamilyPublic>

ProductFamilyCreate

Name	Type	Description
name	string
slug	string

ProductFamilyPublic

Name	Type	Description
id	string(uuid)
name	string
slug	string

ProductFamilyUpdate

Name	Type	Description
name

ProductPlacement

Type: string

ProductPlacementOption

Name	Type	Description
label	string
value	ProductPlacement

ProductPlacementsPublic

Name	Type	Description
count	integer
data	Array<ProductPlacementOption>

ProductTypeCreate

Name	Type	Description
family_id	string(uuid)
layer_order
name	string
placement
slug	string
zone	ProductZone

ProductTypePublic

Name	Type	Description
family	ProductFamilyPublic
id	string(uuid)
layer_order
name	string
placement
slug	string
zone	ProductZone

ProductTypesPublic

Name	Type	Description
count	integer
data	Array<ProductTypePublic>

ProductTypeUpdate

Name	Type	Description
family_id
layer_order
name
placement
zone

ProductZone

Type: string

ReimportResultPublic

Name	Type	Description
message	string
product_id	string(uuid)
sku
status	string

UnmappedExternalValuePublic

Name	Type	Description
brand	string
created_at	string(date-time)
external_value	string
field_name	string
id	string(uuid)
mapping_type	MappingType
occurrence_count	integer
product_count	integer

UnmappedExternalValuesPublic

Name	Type	Description
count	integer
data	Array<UnmappedExternalValuePublic>

UnmappedProductDetailPublic

Name	Type	Description
product	UnmappedProductSummary
unmapped_values	Array<UnmappedValueForProduct>

UnmappedProductListItem

Name	Type	Description
age_class
brand
cover_image_url
gender
id	string(uuid)
name	string
product_family
product_type
sku
unmapped_value_count	integer

UnmappedProductListPublic

Name	Type	Description
count	integer
data	Array<UnmappedProductListItem>

UnmappedProductsPublic

Name	Type	Description
count	integer
data	Array<UnmappedProductSummary>

UnmappedProductSummary

Name	Type	Description
age_class
brand
brand_metadata
cover_image_url
gender
id	string(uuid)
name	string
product_family
product_type
sku

UnmappedValueForProduct

Name	Type	Description
brand	string
created_at	string(date-time)
external_value	string
field_name	string
id	string(uuid)
mapping_type	MappingType
occurrence_count	integer

ValidationError

Name	Type	Description
ctx
input
loc	Array<>
msg	string
type	string

Security schemes

Name	Type	Scheme	Description
OAuth2PasswordBearer	oauth2