Skip to main content

Create Product Unit

Create a new product unit in the system. Product units represent individual instances of products that can be tracked and managed independently.

📝 Request Structure​

Required Fields​

  • Either productId OR productExternalId must be provided (not both)
    • productId: Internal product ID
    • productExternalId: External product ID

Optional Fields​

  • description - Description of the product unit
  • externalId - External identifier for the product unit
  • productVariantId - ID of a specific product variant
  • extraFields - Additional fields as key-value pairs
  • images - Array of image URLs for the product unit
  • disabled - Whether the unit is disabled (default: false)
  • tags - Tags associated with the product unit
  • userGroupId - UUID of the user group to associate with the unit

📘 Field Interpretation​

  • URLs in images must be valid HTTPS URLs
  • externalId must follow title string format
  • tags must be an array of title strings
  • userGroupId must be a valid UUID
  • disabled defaults to false if not provided
  • extraFields accepts any key-value pairs

📤 Request Format​

POST /api/v1/units
Content-Type: application/json
Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

{
    "productId": "PROD-12345",
    "description": "A high-quality wireless mouse",
    "externalId": "EXT-UNIT-12345",
    "productVariantId": "VARIANT-001",
    "images": [
        "https://example.com/image1.jpg",
        "https://example.com/image2.jpg"
    ],
    "disabled": false,
    "tags": ["electronics", "wireless", "mouse"],
    "extraFields": {
        "color": "red",
        "size": "L"
    },
    "userGroupId": "550e8400-e29b-41d4-a716-446655440000"
}

📥 Response Format​

Success Response​

HTTP/1.1 201 Created
Content-Type: application/json

{
    "externalId": "EXT-UNIT-12345",
    "productId": "PROD-12345",
    "productVariantId": "VARIANT-001",
    "productExternalId": null,
    "description": "A high-quality wireless mouse",
    "images": [
        "https://example.com/image1.jpg",
        "https://example.com/image2.jpg"
    ],
    "organizationId": "123e4567-e89b-12d3-a456-426614174000",
    "disabled": false,
    "userGroupId": "550e8400-e29b-41d4-a716-446655440000",
    "extraFields": {
        "color": "red",
        "size": "L"
    }
}

Error Responses​

Invalid Request (400 Bad Request)​

{
    "statusCode": 400,
    "message": "Invalid input",
    "errors": [
        {
            "field": "productId",
            "message": "Either productId or productExternalId must be provided"
        }
    ]
}

Authentication Error (401 Unauthorized)​

{
    "statusCode": 401,
    "message": "Invalid or missing authorization credentials"
}

Product Not Found (404 Not Found)​

{
    "statusCode": 404,
    "message": "Referenced product does not exist"
}

🔒 Required Permissions​

  • units:create
  • products:read (for product validation)

💡 Tips​

  • Provide either productId or productExternalId, not both
  • Ensure all image URLs use HTTPS protocol
  • Use meaningful external IDs for better tracking
  • Include relevant tags for easier filtering
  • Validate UUID format for userGroupId
  • Keep descriptions concise but informative