General

Objects

Codes

Product - POST

Stability: 2 - Stable

A product is primarily a merchant object, which represents an item for sale on the Shopwave platform. A product can be placed into a basket and be sold with associated transactions. Products can have associated stock detail per store, which are tracked and can be reported on.

This API POST call allows you to create and update each of these product objects with full detail.

The endpoint you need to use for this is:

/product

Request

Headers

Key	Details	Example
Authorization*	{token_type} {access_token}	Bearer c3499c2729730a7f807efb8676a92dcb6f8a3f8f
Method*	POST	POST
x-accept-version	{recommended_latest_version_number}	2

* Required header

Body

NOTE: To update just supply the product id. Instances cannot be updated, they are stored for historic references. To change a price, remove an instance entry completely and replace with a new entry, which will mark the previous entry as deleted.

Key	Details	Data Type
products[{productId}].id	unique product Id	Int
products[{productId}].barcode	The unique barcode for the product.	String
products[{productId}].name	A name which is able to identify the product.	String
products[{productId}].details	Extra details which are important for the product.	String
products[{productId}].tags	Tags (comma separated), which are associated with the product.	String
products[{productId}].activeDate	The date at which the product became active. If this is null then the product is not currently active.	DateTime
products[{productId}].deleteDate	The date at which the product was deleted. If this is null then the product is not deleted.	DateTime
products[{productId}].images	An array of product image filename strings.	Array
products[{productId}].categories	An array of product category IDs.	Array
products[{productId}].timestamp	The date at which the product was added.	DateTime
products[{productId}].totalStock	No. of all stock for the given storeId, if this product is inventory managed for this storeId.	Int
products[{productId}].stockSold	No. of stock sold for the given storeId, if this product is inventory managed for this storeId.	Int
products[{productId}].stockLeft	No. of stock remaining for the given storeId, if this product is inventory managed for this storeId.	Int
products[{productId}].instances[...].id	Unique Product Instance Id	Int
products[{productId}].instances[...].price	Price for this instance of the product.	String
products[{productId}].instances[...].taxPercentage	Tax percentage for this instance of the product.	String
products[{productId}].instances[...].timestamp	The date at which the instance was added.	DateTime
products[{productId}].instances[...].name	The overriding name for this instance.	String
products[{productId}].instances[...].activeDate	The date at which the instance became active. If this is null then the instance is not currently active.	DateTime
products[{productId}].instances[...].tags	Tags (comma separated), which are associated with the instance.	String

{
    "products": {
        "0": {
            "id": 135592,
            "barcode": "4280380013331",
            "name": "Classic Beef Burger",
            "details": "Our burgers are handmade just for you, flame-grilled to order, to create the best tasting burger!",
            "tags": "",
            "unit": 0,
            "timestamp": "2023-03-28T12:58:27.000Z",
            "activeDate": "2023-01-16T12:51:51.000Z",
            "deleteDate": null,
            "images": [
                "9cfadc9f6d2393ab8d62f5154ffc95155cdc0105.jpg"
            ],
            "categories": [
                11949
            ],
            "instances": {
                "0": {
                    "id": 531661,
                    "price": "1600.0",
                    "taxPercentage": "0.0000",
                    "timestamp": "0000-00-00 00:00:00",
                    "size": null,
                    "name": null,
                    "activeDate": "2022-10-19T11:19:00.000Z",
                    "tags": "London Take Out"
                },
                "1": {
                    "id": 534915,
                    "price": "1000.0",
                    "taxPercentage": "0.2000",
                    "timestamp": "0000-00-00 00:00:00",
                    "size": null,
                    "name": null,
                    "activeDate": null,
                    "tags": "London Staff Prices"
                },
                "2": {
                    "id": 534916,
                    "price": "1250.0",
                    "taxPercentage": "0.2000",
                    "timestamp": "0000-00-00 00:00:00",
                    "size": null,
                    "name": "",
                    "activeDate": "2023-03-28T13:58:00.000Z",
                    "tags": "London Eat In"
                },
                "3": {
                    "id": 534927,
                    "price": "977.8",
                    "taxPercentage": "0.1250",
                    "timestamp": "0000-00-00 00:00:00",
                    "size": null,
                    "name": "Le Burger",
                    "activeDate": "2023-03-28T13:58:00.000Z",
                    "tags": "EU Kiosk"
                }
            }
        }
    }
}

Response

Headers

Key	Details	Data Type	Example
statusCode	Very important to check this for any error. 201 for success.	int	201

Body

Key	Details	Data Type
products[{productId}].id	unique product Id	Int
products[{productId}].barcode	The unique barcode for the product.	String
products[{productId}].name	A name which is able to identify the product.	String
products[{productId}].details	Extra details which are important for the product.	String
products[{productId}].tags	Tags (comma separated), which are associated with the product.	String
products[{productId}].activeDate	The date at which the product became active. If this is null then the product is not currently active.	DateTime
products[{productId}].deleteDate	The date at which the product was deleted. If this is null then the product is not deleted.	DateTime
products[{productId}].images	An array of product image URL strings.	Array
products[{productId}].categories	An array of product category objects containing IDs and names.	Array
products[{productId}].timestamp	The date at which the product was added.	DateTime
products[{productId}].totalStock	No. of all stock for the given storeId, if this product is inventory managed for this storeId.	Int
products[{productId}].stockSold	No. of stock sold for the given storeId, if this product is inventory managed for this storeId.	Int
products[{productId}].stockLeft	No. of stock remaining for the given storeId, if this product is inventory managed for this storeId.	Int
products[{productId}].instances[...].id	Unique Product Instance Id	Int
products[{productId}].instances[...].price	Price for this instance of the product.	String
products[{productId}].instances[...].taxPercentage	Tax percentage for this instance of the product.	String
products[{productId}].instances[...].timestamp	The date at which the instance was added.	DateTime
products[{productId}].instances[...].name	The overriding name for this instance.	String
products[{productId}].instances[...].activeDate	The date at which the instance became active. If this is null then the instance is not currently active.	DateTime
products[{productId}].instances[...].tags	Tags (comma separated), which are associated with the instance.	String

{
    "products": {
        "135592": {
            "id": 135592,
            "barcode": "4280380013331",
            "name": "Classic Beef Burger",
            "details": "Our burgers are handmade just for you, flame-grilled to order, to create the best tasting burger!",
            "tags": "",
            "unit": 0,
            "timestamp": "2023-03-28T12:58:27.000Z",
            "activeDate": "2023-01-16T12:51:51.000Z",
            "deleteDate": null,
            "images": [
                "http://static.merchantstack.com/images/merchant/4511/product/9cfadc9f6d2393ab8d62f5154ffc95155cdc0105.jpg"
            ],
            "categories": {
                "11949": "Mains"
            },
            "instances": {
                "531661": {
                    "id": 531661,
                    "price": "1600.0",
                    "taxPercentage": "0.000",
                    "timestamp": "0000-00-00 00:00:00",
                    "size": null,
                    "name": null,
                    "activeDate": "2022-10-19T11:19:00.000Z",
                    "tags": "London Take Out"
                },
                "534915": {
                    "id": 534915,
                    "price": "1000.0",
                    "taxPercentage": "0.200",
                    "timestamp": "0000-00-00 00:00:00",
                    "size": null,
                    "name": null,
                    "activeDate": null,
                    "tags": "London Staff Prices"
                },
                "534916": {
                    "id": 534916,
                    "price": "1250.0",
                    "taxPercentage": "0.200",
                    "timestamp": "0000-00-00 00:00:00",
                    "size": null,
                    "name": "",
                    "activeDate": "2023-03-28T13:58:00.000Z",
                    "tags": "London Eat In"
                },
                "534927": {
                    "id": 534927,
                    "price": "977.8",
                    "taxPercentage": "0.125",
                    "timestamp": "0000-00-00 00:00:00",
                    "size": null,
                    "name": "Le Burger",
                    "activeDate": "2023-03-28T13:58:00.000Z",
                    "tags": "EU Kiosk"
                }
            }
        }
    },
    "api": {
        "message": {
            "success": {
                "202": {
                    "id": 202,
                    "title": "Token is valid",
                    "details": "Token is validated and found valid."
                },
                "203": {
                    "id": 203,
                    "title": "Request Processed Successfully",
                    "details": "The request has been successfully completed."
                }
            }
        },
        "codeBaseVersion": 2,
        "executionTime_milliSeconds": 9
    }
}

Status Codes

Error

Please check the live API calls for more details on the API messages.

ID	Status Code	Title	Details
908	401	Expired Token	Token expired or invalid. Please renew your token
911	401	Authorization Header Invalid	The authorization header is invalid. The correct format is Authorization: {token_type} {accessToken}
919	429	Cannot handle too many request	There is a limit for every object you can send to our server and you are exceding that.
913	400	Required parameter or object missing in request	One or more of the required parameters or object formation is missing in your request. Please refer the documentation
904	401	Access Denied	Access denied for the request
912	403	Resource Not Allowed For Specified User	The user does not own this resource and its forbidden
899	500	Unknown Error	Something went wrong. Please contact the site administrator

Success

Please check the live API calls for more details on the API messages.

ID	Status Code	Title	Details
202	200	Token is valid	Token is validated and found valid.
206	201	Resource Created	Your resource is created partially or fully. Please check further message or process log

Request
- Headers
- Body
Response
- Headers
- Body
Status Codes
- Error
- Success
Top