Add Product Variant

Adding or Updating a Product Variant

Contents

• Overview
• Version-specific information
• Permissions and Authentication
• Headers
• HTTP Parameters
• Sample request
• Sample response
• Possible error responses

Overview

• Call name: add-product-variant
• Endpoint URL: https://{API hostname}/internal/add-product-variant
• Request methods: POST
• Request Content-Type: application/json or application/x-www-form-urlencoded
• Response Content-Type: application/json
• Auth required: yes

This endpoint allows creating a new product variant or updating an existing one in the Spaaza system. A product variant represents a specific variation of a product (e.g., different size, color) and can have its own barcodes, price, and other attributes.

Version-specific information

The following version-specific changes apply to this endpoint. See the versioning page for more details.

Version	Change details
2025-03	Added ability to update barcodes when update_if_exists=true

Permissions and Authentication

This API call requires admin authentication:

• The performing user must be logged in and have WRITE access to the specified chain
• User and privileged authentication methods are not permitted for this endpoint

Headers

Standard headers are used for this endpoint. No special headers are required.

HTTP Parameters

The following HTTP parameters can be passed to the API:

Parameter	Description
chain_id	(integer, mandatory) The ID of the chain this product variant belongs to
product_id	(integer, conditional) The ID of the parent product. Either product_id or product_owner_code must be provided
product_owner_code	(string, conditional, max=255) The owner code of the parent product. Either product_id or product_owner_code must be provided
id	(integer, optional) Product variant ID. When supplied with update_if_exists=true, identifies the variant to update
owner_code	(string, optional, max=255) Owner code for the product variant. Used to identify the variant when update_if_exists=true, and saved on create when provided
barcodes	(array, mandatory when update_if_exists=false) Array of barcode strings for the product variant. When update_if_exists=true and the variant exists, this will replace any existing barcodes
update_if_exists	(boolean, optional) If true, updates an existing variant with matching owner_code, including replacing barcodes if provided. If false, throws an error if the variant exists
colour	(string, optional, max=256) The color of the product variant
size	(string, optional, max=100) The size of the product variant
name	(string, optional, max=255) The name of the product variant
price	(decimal, optional) The price of the product variant. Maximum 7 digits before decimal, 2 after
cost_price	(decimal, optional) The cost price of the product variant. Maximum 7 digits before decimal, 2 after
is_promotional	(boolean, optional) Whether the product variant is on promotion
image_url	(string, optional, max=512) URL to the product variant's image
web_url	(string, optional, max=512) URL to the product variant's web page

Sample request

POST /internal/add-product-variant HTTP/1.1
Content-Type: application/json

{
    "chain_id": 123,
    "product_id": 456,
    "owner_code": "variant-456-s",
    "colour": "navy",
    "price": 99.95,
    "cost_price": 79.95,
    "image_url": "https://www.spaaza.com/images/navy_arran.jpg",
    "web_url": "https://www.shop.spaaza.com/images/navy_arran.jpg",
    "size": "S",
    "barcodes": ["2000042436019", "2000042436018"],
    "is_promotional": false
}

Sample response

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "product_variant": {
            "barcodes": [
                {
                    "barcode": "2000042436019",
                    "created_date": "2025-01-24T12:00:00+00:00",
                    "deleted": false,
                    "id": 3,
                    "last_modified_date": "2025-01-24T12:00:00+00:00",
                    "product_variant_id": 3
                }
            ],
            "colour": "navy",
            "condition": "new",
            "cost_price": 79.95,
            "currency_id": 2,
            "id": 3,
            "image_url": null,
            "name": null,
            "price": 99.95,
            "product_id": 456,
            "published_expiry_date": "2025-02-23T12:00:00+00:00",
            "published_status": 1,
            "size": "S",
            "web_url": null
        },
        "result_type": "add-product-variant"
    }
}

Possible error responses

Code	Name and Description	HTTP Status Code
6	no_valid_session The user needs to be logged in and a valid session key needs to be sent	401
52	missing_necessary_parameters Required parameters (chain_id, product_id/owner_code) missing	400
68	permission_denied_or_non_existent This user has insufficient permissions for this object or the object does not exist	403
82	chain_id_required A valid chain_id must be supplied	404
90	product_id_not_found No record has been found for that product_id	404
230	entity_not_found The specified chain was not found	400
316	parameter_supplied_not_boolean The is_promotional parameter must be a boolean value	400
330	server_error Unexpected server error	500
405	input_invalid Product variant already exists with the same owner code	400