Skip to main content

Products API

The Products API provides endpoints for managing your product catalog.

Endpoints Overview​

MethodEndpointDescription
GET/api/v1/ProductsList products
POST/api/v1/ProductsCreate product
GET/api/v1/Products/{guid}Get product
PUT/api/v1/Products/{guid}Update product
POST/api/v1/Products/{productId}/variantsCreate variant
GET/api/v1/Products/{productId}/variants/{variantId}Get variant
PATCH/api/v1/Products/{productId}/variants/{variantId}Update variant
DELETE/api/v1/Products/{productId}/variants/{variantId}Delete variant
PATCH/api/v1/Products/settingsUpdate product settings

List Products​

Get a paginated list of products.

GET /api/v1/Products

Query Parameters​

ParameterTypeDescription
PageintegerPage number (default: 1)
PageSizeintegerItems per page (max: 100)
$orderbystringSort order
$filterstringFilter expression
$searchstringSearch text

Example Request​

GET /api/v1/Products?Page=1&PageSize=25&$search=shirt

Response​

{
  "data": [
    {
      "guid": "product-uuid",
      "name": "Blue T-Shirt",
      "sku": "TSHIRT-BLUE-001",
      "price": 29.99,
      "weight": 0.3,
      "dimensions": {
        "length": 30,
        "width": 25,
        "height": 2
      },
      "variantCount": 3
    }
  ],
  "page": 1,
  "pageSize": 25,
  "totalCount": 150,
  "success": true
}

Create Product​

Create a new product.

POST /api/v1/Products

Request Body​

{
  "name": "Blue T-Shirt",
  "sku": "TSHIRT-BLUE-001",
  "description": "Comfortable cotton t-shirt",
  "price": 29.99,
  "cost": 12.00,
  "weight": 0.3,
  "dimensions": {
    "length": 30,
    "width": 25,
    "height": 2
  },
  "barcode": "1234567890123"
}

Response​

{
  "data": {
    "guid": "product-uuid",
    "name": "Blue T-Shirt",
    "sku": "TSHIRT-BLUE-001"
  },
  "success": true
}

Get Product​

Retrieve a specific product.

GET /api/v1/Products/{guid}

Path Parameters​

ParameterTypeDescription
guiduuidProduct identifier

Response​

{
  "data": {
    "guid": "product-uuid",
    "name": "Blue T-Shirt",
    "sku": "TSHIRT-BLUE-001",
    "description": "Comfortable cotton t-shirt",
    "price": 29.99,
    "cost": 12.00,
    "weight": 0.3,
    "dimensions": {
      "length": 30,
      "width": 25,
      "height": 2
    },
    "barcode": "1234567890123",
    "variants": [
      {
        "guid": "variant-uuid",
        "name": "Small",
        "sku": "TSHIRT-BLUE-001-S"
      }
    ],
    "createdAt": "2024-01-15T10:00:00Z"
  },
  "success": true
}

Update Product​

Update an existing product.

PUT /api/v1/Products/{guid}

Request Body​

{
  "name": "Blue Cotton T-Shirt",
  "price": 34.99,
  "description": "Premium comfortable cotton t-shirt"
}

Response​

{
  "data": {
    "guid": "product-uuid",
    "name": "Blue Cotton T-Shirt"
  },
  "success": true
}

Create Variant​

Add a variant to a product.

POST /api/v1/Products/{productId}/variants

Request Body​

{
  "name": "Medium",
  "sku": "TSHIRT-BLUE-001-M",
  "priceDifference": 0,
  "weight": 0.35,
  "dimensions": {
    "length": 32,
    "width": 27,
    "height": 2
  }
}

Response​

{
  "data": {
    "guid": "variant-uuid",
    "name": "Medium",
    "sku": "TSHIRT-BLUE-001-M"
  },
  "success": true
}

Get Variant​

Retrieve a specific variant.

GET /api/v1/Products/{productId}/variants/{variantId}

Response​

{
  "data": {
    "guid": "variant-uuid",
    "name": "Medium",
    "sku": "TSHIRT-BLUE-001-M",
    "priceDifference": 0,
    "weight": 0.35,
    "dimensions": {
      "length": 32,
      "width": 27,
      "height": 2
    }
  },
  "success": true
}

Update Variant​

Update an existing variant.

PATCH /api/v1/Products/{productId}/variants/{variantId}

Request Body​

{
  "name": "Medium (Updated)",
  "weight": 0.36
}

Response​

{
  "data": {
    "guid": "variant-uuid",
    "name": "Medium (Updated)"
  },
  "success": true
}

Delete Variant​

Remove a variant from a product.

DELETE /api/v1/Products/{productId}/variants/{variantId}

Response​

{
  "success": true
}

Update Product Settings​

Update product-related settings.

PATCH /api/v1/Products/settings

Request Body​

{
  "autoGenerateSku": true,
  "defaultUnit": "cm",
  "defaultWeightUnit": "kg"
}

Response​

{
  "success": true
}

Error Responses​

404 Not Found​

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Product not found"
  }
}

409 Conflict​

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "SKU already exists"
  }
}