Skip to main content

Get Product Unit

Retrieve product unit details or list multiple units based on query parameters.

🔍 Available Endpoints​

Get Single Unit​

GET /api/v1/units/{unitId}

List Units​

GET /api/v1/units

📝 Query Parameters​

List Endpoint Parameters​

  • productId - Filter by parent product ID
  • externalId - Filter by external identifier
  • productVariantId - Filter by variant ID
  • productExternalId - Filter by product external ID
  • disabled - Filter by disabled status
  • userGroupId - Filter by user group ID
  • page - Page number (default: 1)
  • limit - Items per page (default: 20)

📘 Parameter Interpretation​

  • Use comma-separated values for multiple tags
  • Pagination uses zero-based indexing
  • Maximum limit value is 100
  • Boolean parameters accept true or false

📤 Request Format​

Single Unit Request​

GET /api/v1/units/UNIT-123
Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

List Units Request​

GET /api/v1/units?productId=PROD-123&disabled=false&limit=10
Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

📥 Response Format​

Single Unit Response​

HTTP/1.1 200 OK
Content-Type: application/json

{
    "externalId": "UNIT123",
    "productId": "123e4567-e89b-12d3-a456-426614174000",
    "productVariantId": "123e4567-e89b-12d3-a456-426614174000",
    "productExternalId": "PROD-EXT-123",
    "description": "Demo unit for display",
    "images": [
        "https://example.com/unit1.webp",
        "https://example.com/unit2.webp"
    ],
    "organizationId": "123e4567-e89b-12d3-a456-426614174000",
    "disabled": false,
    "userGroupId": "123e4567-e89b-12d3-a456-426614174000",
    "extraFields": {
        "location": "Store A",
        "condition": "New"
    }
}

List Units Response​

HTTP/1.1 200 OK
Content-Type: application/json

{
    "items": [
        {
            "externalId": "UNIT123",
            "productId": "123e4567-e89b-12d3-a456-426614174000",
            "productVariantId": "123e4567-e89b-12d3-a456-426614174000",
            "productExternalId": "PROD-EXT-123",
            "description": "Demo unit for display",
            "images": [
                "https://example.com/unit1.webp",
                "https://example.com/unit2.webp"
            ],
            "organizationId": "123e4567-e89b-12d3-a456-426614174000",
            "disabled": false,
            "userGroupId": "123e4567-e89b-12d3-a456-426614174000",
            "extraFields": {
                "location": "Store A",
                "condition": "New"
            }
        }
    ],
    "pagination": {
        "total": 45,
        "pages": 5,
        "current": 1,
        "limit": 10
    }
}

Error Responses​

Unit Not Found (404 Not Found)​

{
    "statusCode": 404,
    "message": "Product unit not found"
}

Invalid Parameters (400 Bad Request)​

{
    "statusCode": 400,
    "message": "Invalid query parameters",
    "errors": [
        {
            "field": "limit",
            "message": "Must be between 1 and 100"
        }
    ]
}

🔒 Required Permissions​

  • units:read
  • units:list (for listing endpoint)

💡 Tips​

  • Use specific unit IDs when possible
  • Implement pagination for large datasets
  • Use filters to minimize response size
  • Cache responses when appropriate
  • Include only needed query parameters