E-commerce Product Catalog API (v2.0.

0)
Download OpenAPI specification: Download

ShopSphere Support: api-support@shopsphere.example.com

URL: https://shopsphere.example.com/developer/support | License: MIT License

API for managing products, categories, inventory, and pricing for an e-commerce platform.

Products

Manage products in the catalog.

List all products

AUTHORIZATIONS: apiKeyAuth

QUERY PARAMETERS

categoryId string <uuid>

Filter by category ID

inStock boolean
Filter by stock availability

searchTerm string
Search term for product name or description

limit integer [ 1 .. 100 ]

Default: 25
Maximum number of products to return

offset integer >= 0

Default: 0
Number of products to skip for pagination

Responses

200 A list of products.

 default An unexpected error occurred.

GET /products

Response samples

200 default

Content type
application/json

Copy Expand all Collapse all

[
- {
"id": "prod_123xyz",
"sku": "TSHIRT-BLK-L",
"name": "Men's Premium T-Shirt",
"description": "A comfortable and stylish t-shirt made from 100% cotton.",
+ "price": { … },
"categoryId": "cat_abc789",
"brand": "ShopSphere Basics",
+ "images": [ … ],
+ "attributes": [ … ],
+ "inventory": { … },
"isActive": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]

Add a new product

AUTHORIZATIONS: apiKeyAuth

REQUEST BODY SCHEMA: application/json

Product to add to the catalog

sku
string
required

name string
required
 description string

price
object (PriceInput)
required

categoryId string or null <uuid>

brand string or null

images Array of strings <url>

attributes Array of objects (ProductAttribute)

initialInventory object (UpdateInventory)

isActive boolean
Default: true

Responses

201 Product created successfully.

400 Invalid request payload or parameters.

default An unexpected error occurred.

POST /products

Request samples

Payload

Content type
application/json

Copy Expand all Collapse all

{
"sku": "string",
"name": "string",
"description": "string",
 - "price": {
"amount": 0,
"currency": "string",
"saleAmount": 0
},
"categoryId": "337f5e5d-288b-40d5-be14-901cc3acacc0",
"brand": "string",
- "images": [
"string"
],
- "attributes": [
+ { … }
],
- "initialInventory": {
"quantity": 0,
"lowStockThreshold": 0
},
"isActive": true
}

Response samples

201 400 default

Content type
application/json

Copy Expand all Collapse all

{
"id": "prod_123xyz",
"sku": "TSHIRT-BLK-L",
"name": "Men's Premium T-Shirt",
"description": "A comfortable and stylish t-shirt made from 100% cotton.",
- "price": {
"amount": 29.99,
"currency": "USD",
"saleAmount": 24.99
},
"categoryId": "cat_abc789",
"brand": "ShopSphere Basics",
- "images": [
"https://cdn.example.com/image1.jpg",
"https://cdn.example.com/image2.jpg"
],
- "attributes": [
+ { … }
],
 - "inventory": {
"quantity": 150,
"isInStock": true,
"lowStockThreshold": 10,
"lastStockUpdate": "2019-08-24T14:15:22Z"
},
"isActive": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Get product details by ID

AUTHORIZATIONS: apiKeyAuth

PATH PARAMETERS

productId string
required
Example: prod_123xyz
ID of the product to retrieve

Responses

200 Detailed information about the product.

404 The requested resource was not found.

default An unexpected error occurred.

GET /products/{productId}

Response samples

200 404 default

Content type
application/json

Copy Expand all Collapse all

 {
"id": "prod_123xyz",
"sku": "TSHIRT-BLK-L",
"name": "Men's Premium T-Shirt",
"description": "A comfortable and stylish t-shirt made from 100% cotton.",
- "price": {
"amount": 29.99,
"currency": "USD",
"saleAmount": 24.99
},
"categoryId": "cat_abc789",
"brand": "ShopSphere Basics",
- "images": [
"https://cdn.example.com/image1.jpg",
"https://cdn.example.com/image2.jpg"
],
- "attributes": [
+ { … }
],
- "inventory": {
"quantity": 150,
"isInStock": true,
"lowStockThreshold": 10,
"lastStockUpdate": "2019-08-24T14:15:22Z"
},
"isActive": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Update an existing product

AUTHORIZATIONS: apiKeyAuth

PATH PARAMETERS

productId string
required
Example: prod_123xyz
ID of the product to update

REQUEST BODY SCHEMA: application/json

Product data to update

sku string

name string
 description string

price object (PriceInput)

categoryId string or null <uuid>

brand string or null

images Array of strings <url>

attributes Array of objects (ProductAttribute)

isActive boolean

Responses

200 Product updated successfully.

400 Invalid request payload or parameters.

404 The requested resource was not found.

default An unexpected error occurred.

PUT /products/{productId}

Request samples

Payload

Content type
application/json

Copy Expand all Collapse all

{
"sku": "string",
"name": "string",
"description": "string",
- "price": {
"amount": 0,
"currency": "string",
"saleAmount": 0
},
 "categoryId": "337f5e5d-288b-40d5-be14-901cc3acacc0",
"brand": "string",
- "images": [
"string"
],
- "attributes": [
+ { … }
],
"isActive": true
}

Response samples

200 400 404 default

Content type
application/json

Copy Expand all Collapse all

{
"id": "prod_123xyz",
"sku": "TSHIRT-BLK-L",
"name": "Men's Premium T-Shirt",
"description": "A comfortable and stylish t-shirt made from 100% cotton.",
- "price": {
"amount": 29.99,
"currency": "USD",
"saleAmount": 24.99
},
"categoryId": "cat_abc789",
"brand": "ShopSphere Basics",
- "images": [
"https://cdn.example.com/image1.jpg",
"https://cdn.example.com/image2.jpg"
],
- "attributes": [
+ { … }
],
- "inventory": {
"quantity": 150,
"isInStock": true,
"lowStockThreshold": 10,
"lastStockUpdate": "2019-08-24T14:15:22Z"
},
"isActive": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
Delete a product
AUTHORIZATIONS: apiKeyAuth

PATH PARAMETERS

productId string
required
Example: prod_123xyz
ID of the product to delete

Responses

— 204 Product deleted successfully.

404 The requested resource was not found.

default An unexpected error occurred.

DELETE /products/{productId}

Response samples

404 default

Content type
application/json

Copy Expand all Collapse all

{
"code": "PRODUCT_NOT_FOUND",
"message": "The requested product could not be found.",
- "details": {
"productId": "prod_invalid"
}
}
Categories

Manage product categories.

List all product categories

AUTHORIZATIONS: apiKeyAuth

Responses

200 A list of product categories.

default An unexpected error occurred.

GET /categories

Response samples

200 default

Content type
application/json

Copy Expand all Collapse all

[
- {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Apparel",
"description": "Clothing items for men, women, and children.",
"parentCategoryId": "acdf37b5-b785-42a1-be6f-0a9504c832f1",
"imageUrl": "string",
"isActive": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
Create a new category
AUTHORIZATIONS: apiKeyAuth

REQUEST BODY SCHEMA: application/json

Category to create

name
string
required

description string or null

parentCategoryId string or null <uuid>

imageUrl string or null <url>

isActive boolean
Default: true

Responses

201 Category created successfully.

400 Invalid request payload or parameters.

default An unexpected error occurred.

POST /categories

Request samples

Payload

Content type
application/json

Copy
{
"name": "string",
"description": "string",
"parentCategoryId": "acdf37b5-b785-42a1-be6f-0a9504c832f1",
 "imageUrl": "string",
"isActive": true
}

Response samples

201 400 default

Content type
application/json

Copy
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Apparel",
"description": "Clothing items for men, women, and children.",
"parentCategoryId": "acdf37b5-b785-42a1-be6f-0a9504c832f1",
"imageUrl": "string",
"isActive": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Get category details by ID

AUTHORIZATIONS: apiKeyAuth

PATH PARAMETERS

categoryId string <uuid>

required
ID of the category to retrieve

Responses

200 Detailed information about the category.

404 The requested resource was not found.

default An unexpected error occurred.

 GET /categories/{categoryId}

Response samples

200 404 default

Content type
application/json

Copy
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Apparel",
"description": "Clothing items for men, women, and children.",
"parentCategoryId": "acdf37b5-b785-42a1-be6f-0a9504c832f1",
"imageUrl": "string",
"isActive": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Update an existing category

AUTHORIZATIONS: apiKeyAuth

PATH PARAMETERS

categoryId string <uuid>

required
ID of the category to update

REQUEST BODY SCHEMA: application/json

Category data to update

name string

description string or null

parentCategoryId string or null <uuid>

imageUrl string or null <url>

isActive boolean
Responses

200 Category updated successfully.

400 Invalid request payload or parameters.

404 The requested resource was not found.

default An unexpected error occurred.

PUT /categories/{categoryId}

Request samples

Payload

Content type
application/json

Copy
{
"name": "string",
"description": "string",
"parentCategoryId": "acdf37b5-b785-42a1-be6f-0a9504c832f1",
"imageUrl": "string",
"isActive": true
}

Response samples

200 400 404 default

Content type
application/json

Copy
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Apparel",
"description": "Clothing items for men, women, and children.",
"parentCategoryId": "acdf37b5-b785-42a1-be6f-0a9504c832f1",
"imageUrl": "string",
"isActive": true,
"createdAt": "2019-08-24T14:15:22Z",
 "updatedAt": "2019-08-24T14:15:22Z"
}

Delete a category
AUTHORIZATIONS: apiKeyAuth

PATH PARAMETERS

categoryId string <uuid>

required
ID of the category to delete

Responses

— 204 Category deleted successfully.

404 The requested resource was not found.

409 The request could not be completed due to a conflict with the current state of the resource.

default An unexpected error occurred.

DELETE /categories/{categoryId}

Response samples

404 409 default

Content type
application/json

Copy Expand all Collapse all

{
"code": "PRODUCT_NOT_FOUND",
"message": "The requested product could not be found.",
- "details": {
"productId": "prod_invalid"
}
}
Inventory

Manage product inventory levels.

Get inventory status for a product

AUTHORIZATIONS: apiKeyAuth

PATH PARAMETERS

productId string
required
Example: prod_123xyz
ID of the product

Responses

200 Inventory status.

404 The requested resource was not found.

default An unexpected error occurred.

GET /products/{productId}/inventory

Response samples

200 404 default

Content type
application/json

Copy
{
"quantity": 150,
"isInStock": true,
 "lowStockThreshold": 10,
"lastStockUpdate": "2019-08-24T14:15:22Z"
}

Update inventory for a product

AUTHORIZATIONS: apiKeyAuth

PATH PARAMETERS

productId string
required
Example: prod_123xyz
ID of the product

REQUEST BODY SCHEMA: application/json

Inventory update details

quantity integer <int32>

required
The new total quantity for the product.

lowStockThreshold integer or null <int32>

Responses

200 Inventory updated successfully.

400 Invalid request payload or parameters.

404 The requested resource was not found.

default An unexpected error occurred.

PUT /products/{productId}/inventory

Request samples

Payload

Content type
application/json
 Copy
{
"quantity": 0,
"lowStockThreshold": 0
}

Response samples

200 400 404 default

Content type
application/json

Copy
{
"quantity": 150,
"isInStock": true,
"lowStockThreshold": 10,
"lastStockUpdate": "2019-08-24T14:15:22Z"
}