Add Product

Adding or Updating a Product

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

Overview

Call name: add-product
Endpoint URL: https://{API hostname}/internal/add-product
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 or updating an existing product in the Spaaza system. When creating a new product, it will be automatically assigned to the default category (ID 1). When updating an existing product, only the provided fields will be updated.

Version-specific information

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

Version	Change details
N/A	N/A

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 belongs to
name	(string, mandatory, max=255) The name of the product
price	(decimal, optional) The price of the product
owner_code	(string, mandatory, max=64) A unique identifier for the product within the chain
description	(string, optional, max=512) A description of the product
brand	(string, optional, max=64) The brand name of the product
manufacturer	(string, optional, max=64) The name of the organisation that manufactured or produced the product
private_label	(boolean, optional) Whether this product belongs to the chain's private-label collection. Defaults to `false`
listing_source	(string, optional, max=64) Freeform source that listed the product, such as head office, distribution centre, or local store
season	(string, optional, max=64) The season identifier for the product
category	(string, optional, max=1024) The category string for the product
web_url	(string, optional, max=512) URL to the product's web page
image_url	(string, optional, max=512) URL to the product's image
cost_price	(decimal, optional) The cost price of the product
is_promotional	(boolean, optional) Whether the product is on promotion
unit	(string, optional) The unit the product is sold in, such as "item", "g", or "kg"
update_if_exists	(boolean, optional) If true, updates an existing product with matching owner_code. If false, throws an error if the product exists

Sample request

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

{
    "chain_id": 123,
    "name": "Men's Merino Aran Jumper",
    "description": "The Aran Jumper is a style of jumper that takes its name from the Aran Islands off the west coast of Ireland.",
    "price": 99.95,
    "cost_price": 79.95,
    "owner_code": "00024003",
    "brand": "Aran Brands Inc.",
    "manufacturer": "Aran Knitwear Co.",
    "private_label": false,
    "listing_source": "head office",
    "image_url": "https://www.spaaza.com/images/arran.jpg",
    "webshop_url": "https://www.shop.spaaza.com/images/arran.jpg",
    "season": "Winter",
    "category": "sweater > Aran > mens",
    "is_promotional": false,
    "unit": "item"
}

Sample response

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "product": {
            "brand": "Aran Brands Inc.",
            "category": "sweater > Aran > mens",
            "cost_price": 79.95,
            "created_date": "2025-01-24T12:00:00+00:00",
            "description": "The Aran Jumper is a style of jumper that takes its name from the Aran Islands off the west coast of Ireland.",
            "id": 456,
            "image_url": "https://www.spaaza.com/images/arran.jpg",
            "last_modified_date": "2025-01-24T12:00:00+00:00",
            "listing_source": "head office",
            "manufacturer": "Aran Knitwear Co.",
            "name": "Men's Merino Aran Jumper",
            "owner_code": "00024003",
            "price": 99.95,
            "private_label": false,
            "season": "Winter",
            "unit": "item",
            "webshop_url": "https://www.shop.spaaza.com/images/arran.jpg"
        },
        "result_type": "add-product"
    }
}

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, name, 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
154	chain_id_invalid The supplied chain_id is not valid	400
156	product_price_missing or blank The price is required and cannot be blank	400
157	product_price_not_decimal The price must be a valid decimal number	400
230	entity_not_found The specified chain was not found	400
260	product_season_too_long The product_season must be 64 characters or less	400
316	parameter_supplied_not_boolean A boolean parameter (is_promotional, private_label) has a non-boolean value	400
330	server_error Unexpected server error	500
405	input_invalid Product already exists with the same owner code	400

Adding or Updating a Product​

Contents​

Overview​

Version-specific information​

Permissions and Authentication​

Headers​

HTTP Parameters​

Sample request​

Sample response​

Possible error responses​