SQUIZZ.com
Loading interface, please wait...
Interface taking a long time to load?
Check your internet connection is up, and you're using the latest app/browser version.

Platform API Endpoints: Import Organisation Data Images and Files

Within the SQUIZZ.com Application Programming Interface (API) it contains endpoints that allows one organisation using 3rd party software to import and store images in the SQUIZZ.com platform, for different kinds of associated data. This associated data could be products, categories or category trees. The "Import Organisation Data Image" endpoints can be used to automate a number of processes, including the sharing of image data between different organisations, and regularly keeping organisation data up to date. The data imported into the platform will be hosted on the platforms servers, and then be available to be shared with connected organisations and people, if given permission.
To use the API endpoint you will need to have knowledge in building software applications, and how to make requests over the internet to call RESTful web services, which the platform's API endpoint is based on.

Topics

  1. Prerequisites
  2. Web Service Endpoint: Import Organisation Product Image
  3. Web Service Endpoint: Import Organisation Category Image

Web Service Endpoint: Import Organisation Product Image

This endpoint allows a product image file to uploaded and imported against an organisation's product. Once imported tthe image can then be shown in places where product is shown within the SQUIZZ.com platform, including in product listings, within the Product Detail page, on the Basket Details page, in the Order Checkout page, and other locations. By having one or more images set for products makes it possible for people to understand how a product looks, increasing the chances of purhases and sales of products.

This endpoint depends upon products previously been imported against an organisation using the Import Organisation Data endpoint. Once a product exists against an organisation up to 5 images can be imported against it. One of those images can be set as the primary image of the product, and will shown by default in places where the product appears. The first image imported against a product will be set as the primary image by default, but any of the 5 can be set as the primary image. If a primary image is deleted then the next image with the lowest ordering field value will become the primary image.

For each image being imported through this API once the image passes validation checks it will be placed onto a transaction holding area. Up to 100 images may be placed into a single transaction. Upon when the last/100th image is uploaded using this endpoint it can be set to commit the transaction, this will cause all the images in the holding area to be committed against the products after trading tokens costs have been covered by the organisation. By uploading images in batch it reduces the amount of trading token transactions needing to occur, and reduces server resources. When a session is created or validated a successful endpoint response will return a transaction ID required for this endpoint to allow an image to upload. Once a images transaction has successfully committed, the transaction ID will change. The response of this endpoint will return the new transaction ID used to upload the next batch of 100 images.

The image being imported using this endpoint must be placed into the Body of the HTTP request within a multi-part form. The image must be either a PNG. GIF or JPEG file type, containing either a png, gif, giff, jpeg, or jpg extension. If it's a JPEG image then it must be saved in the RGB colour profile. Avoid uploading animated GIFs since only its first frame will be looked at, and may not appear as expected. The image uploaded must be under 2MB in size. If your images are above 2MB in size then we recommend using the SQUIZZ.com Connector software to manage images since it's Product Images data export can automatically resize images upon calling this endpoint.

Note that there are trading token costs to import the product image using this API endpoint, of which the organisation importing the data must have enough tokens to allow the image to import. See the Trading Tokens and Pricing Help page for data import costs.

HTTP Request

HTTP Method POST
HTTP URL https://api.squizz.com/rest/1/org/org/import_product_image/[session_id]
Headers  
Content-Type multipart/form-data
Body Parameters Data Type Mandatory Default Value Description
upload_file BINARY Yes   binary data of the image file.
key_product_id STRING Yes   Key identifier of the product that the image is to be assigned against.
key_image_id STRING Yes   Key identifier of the image that is unique from all other product images.
product_image_transaction_id STRING Yes   ID of the product image transaction that places the image in the same batch as other images with the same transaction ID.
commit_image_uploads ENUM (Y or N) No N If set to Y then the current image being uploaded and all other previously uploaded with the same transaction will be committed and applied against the products they are set to be assigned to.
is_primary ENUM (Y or N) No N If set to Y - Yes, then the image will be set as the primary image used to identify the product. Note that if no other images are assigned to the same product then by default the image will be set as the primary. If another image is set as the primary then lose its primary status.
title STRING No   Title of the image that labels the overall name of the image.
description STRING No   Description of the image that provides more information about the details of the image or associated characteristics.
ordering INTEGER No 0 Number that controls how the image is sorted when displayed within a list of other images assigned to the same product. The lower the number the higher it is placed in the list.

HTTP Request Raw Example:

POST https://api.squizz.com/rest/1/org/import_product_image/EG30432823ABJFDS23332 HTTP/1.1
Host: api.squizz.com
Content-Length: 115
Content-Type: multipart/form-data

org_id=039583957203259WER2484832&api_org_key=12345678901234567890&api_org_pw=exmample_api_password&create_session=Y

HTTP Response

Response Data Type JSON
Parameters Data Type Description
resultStatus INTEGER
  • Set to 1 of the image was successfully imported, either to the holding area, or if all images in the same transaction were committed
  • Set to 2 of the image failed to import
configs.result ENUM (SUCCESS or FAILURE) Either "SUCCESS" or "FAILURE". If successful then a API session was successfully created.
configs.result_code STRING

Status code of trying to import the product image. The following codes could be returned:

  • SERVER_SUCCESS
    The product image was successfully imported into the holding location, and the current and previously uploaded images were successsfully committed if the request was set to commit the images in the same transaction.
     
  • SERVER_ERROR_MISSING_REQUIRED_PARAMETER
    The body of the HTTP request is either missing a value for the keyImageID or keyProductID parameters in the multi-part form, or the parameters were not set.
     
  • SERVER_ERROR_UPLOAD_TRANSACTION_ID_INVALID
    The body of the HTTP request is either missing a value for the product_image_transaction_id parameter, or the ID doesn't match the current transaction ID that was either returned when a API session was first created, or had changed once images had been committed. Get the correct product_image_transaction_id from the response returned, or by calling the Validate Session API endpoint.
     
  • SERVER_ERROR_MAX_IMAGES_TO_COMMIT_EXCEEDED
    The image being uploaded is unable to be saved since the maximum number of images has already been uploaded to the holding location by previous requests. Make a request to upload a previously imported image and set the commit_image_uploads parameter to Y.
     
  • SERVER_ERROR_PRODUCT_NOT_FOUND
    The value set in the request's keyProductID parameter does not match any product previously imported against the organisation. Check that a product exists with the same keyProductID value.
     
  • SERVER_ERROR_IMAGE_NOT_FOUND
    The value set in the request's keyImageID parameter does not match any image previously imported against the organisation. This only occurs when the drop parameter is to 2 - update. Check that an image exists with the same keyImageID value, or otherwise set the drop value 1 - create, to allow a new image to be imported instead of just updated.
     
  • SERVER_ERROR_UNSUPPORTED_FILE_FORMAT
    The image file being imported has is in an image format that is not supported. Ensure that a jpeg, gif or png image is being uploaded with either the gif, giff, jpg, jpeg, or png file extension. For jpeg images ensure that the image's colour profile is set as RGB.
     
  • SERVER_ERROR_ORG_NOT_ENOUGH_CREDITS
    The organisation doesn't have enough trading tokens to cover the cost of importing the current product image, or for committing all the images in the current transaction. Additional trading tokens need to be purchased for the organisation, see Buy More Trading Tokens For An Organisation.
     
  • SERVER_ERROR_IMAGE_CANNOT_BE_RESIZED
    After the image was uploaded the endpoint was unable to resize the image into different sizes, required to optimise when being loaded within the platform. Check that the image is saved in the correct supported image format, jpeg, gif, or png. For jpeg images ensure its colour profile is saved as RGB. Also check that the image dimensions are not too big. Images should be under 2000px in width and 2000px in height.
     
  • SERVER_ERROR_NO_IMAGES_TO_COMMIT
    If the request has the commit_image_uploads parameter set to Y but no images have been imported and placed into the holding location. Ensure that you have placed an image within the request body's "upload file" parameter.
     
  • SERVER_ERROR_IMAGE_CANNOT_BE_SAVED
    If the request has the commit_image_uploads parameter set to Y but the images stored in the holding location were unable to be processed and committed against their categories then this error may occur. If this contunually occurs please raise an issue with the SQUIZZ.com feeds.
     
  • SERVER_ERROR_UNKNOWN
    An unspecified error occurred when calling the API. If this error continually occurs then raise a post within the feeds on the SQUIZZ.com platform.
configs.images_committed_count INTEGER Number of image records that were successfully committed in the one transaction against their products. This will be set to 0 unless the commit_image_uploads request parameter is to Y, and one or more images is successfully committed.
configs.product_image_upload_transaction_id STRING ID of either the current "product_image_upload_transaction_id", or if the commit_image_uploads request parameter is to Y, and one or more images is successfully committed in the same transaction, then this will contain the new transaction ID required for the next set of product images uploaded.
configs.api_version STRING Version of the API being used to handle the endpoint request.

HTTP Response Example:

{
  "resultStatus": "1",
  "version": "1.4",
  "configs": {
    "api_version": "1.0.0.0",
    "result": "SUCCESS",
    "result_code": "SERVER_SUCCESS",
    "images_committed_count": 12,
    "product_image_upload_transaction_id": "11EBD1E82B3826109F0B6AF3476460FC"
  },
  "message": ""
}

Web Service Endpoint: Import Organisation Category Image

This endpoint allows a category image file to uploaded and imported against an organisation's category. Once imported tthe image can then be shown in places where a category is shown within the SQUIZZ.com platform, including in category listings, and other locations. By having one or more images set for categories makes it easier for people to navigate through a category tree to find products, increasing the chances of purhases and sales of products.

This endpoint depends upon categories previously been imported against an organisation using the Import Organisation Data endpoint. Once a category exists against an organisation up to 5 images can be imported against it. One of those images can be set as the primary image of the category, and will shown by default in places where the category appears. The first image imported against a category will be set as the primary image by default, but any of the 5 can be set as the primary image. If a primary image is deleted then the next image with the lowest ordering field value will become the primary image.

For each image being imported through this API once the image passes validation checks it will be placed onto a transaction holding area. Up to 100 images may be placed into a single transaction. Upon when the last/100th image is uploaded using this endpoint it can be set to commit the transaction, this will cause all the images in the holding area to be committed against the categories after trading tokens costs have been covered by the organisation. By uploading images in batch it reduces the amount of trading token transactions needing to occur, and reduces server resources. When a session is created or validated a successful endpoint response will return a transaction ID required for this endpoint to allow an image to upload. Once a images transaction has successfully committed, the transaction ID will change. The response of this endpoint will return the new transaction ID used to upload the next batch of 100 images.

The image being imported using this endpoint must be placed into the Body of the HTTP request within a multi-part form. The image must be either a PNG. GIF or JPEG file type, containing either a png, gif, giff, jpeg, or jpg extension. If it's a JPEG image then it must be saved in the RGB colour profile. Avoid uploading animated GIFs since only its first frame will be looked at, and may not appear as expected. The image uploaded must be under 2MB in size. If your images are above 2MB in size then we recommend using the SQUIZZ.com Connector software to manage images since it's Category Images data export can automatically resize images upon calling this endpoint.

Note that there are trading token costs to import the category image using this API endpoint, of which the organisation importing the data must have enough tokens to allow the image to import. See the Trading Tokens and Pricing Help page for data import costs.

HTTP Request

HTTP Method POST
HTTP URL https://api.squizz.com/rest/1/org/org/import_category_image/[session_id]
Headers  
Content-Type multipart/form-data
Body Parameters Data Type Mandatory Default Value Description
upload_file BINARY Yes   binary data of the image file.
key_category_id STRING Yes   Key identifier of the category that the image is to be assigned against.
key_image_id STRING Yes   Key identifier of the image that is unique from all other category images.
category_image_transaction_id STRING Yes   ID of the category image transaction that places the image in the same batch as other images with the same transaction ID.
commit_image_uploads ENUM (Y or N) No N If set to Y then the current image being uploaded and all other previously uploaded with the same transaction will be committed and applied against the categories they are set to be assigned to.
is_primary ENUM (Y or N) No N If set to Y - Yes, then the image will be set as the primary image used to identify the category. Note that if no other images are assigned to the same category then by default the image will be set as the primary. If another image is set as the primary then lose its primary status.
title STRING No   Title of the image that labels the overall name of the image.
description STRING No   Description of the image that provides more information about the details of the image or associated characteristics.
ordering INTEGER No 0 Number that controls how the image is sorted when displayed within a list of other images assigned to the same category. The lower the number the higher it is placed in the list.

HTTP Request Raw Example:

POST https://api.squizz.com/rest/1/org/import_category_image/EG30432823ABJFDS23332 HTTP/1.1
Host: api.squizz.com
Content-Length: 115
Content-Type: multipart/form-data

org_id=039583957203259WER2484832&api_org_key=12345678901234567890&api_org_pw=exmample_api_password&create_session=Y

HTTP Response

Response Data Type JSON
Parameters Data Type Description
resultStatus INTEGER
  • Set to 1 of the image was successfully imported, either to the holding area, or if all images in the same transaction were committed
  • Set to 2 of the image failed to import
configs.result ENUM (SUCCESS or FAILURE) Either "SUCCESS" or "FAILURE". If successful then a API session was successfully created.
configs.result_code STRING

Status code of trying to import the category image. The following codes could be returned:

  • SERVER_SUCCESS
    The category image was successfully imported into the holding location, and the current and previously uploaded images were successsfully committed if the request was set to commit the images in the same transaction.
  • SERVER_ERROR_MISSING_REQUIRED_PARAMETER
    The body of the HTTP request is either missing a value for the keyImageID or keyCategoryID parameters in the multi-part form, or the parameters were not set.
  • SERVER_ERROR_UPLOAD_TRANSACTION_ID_INVALID
    The body of the HTTP request is either missing a value for the category_image_transaction_id parameter, or the ID doesn't match the current transaction ID that was either returned when a API session was first created, or had changed once images had been committed previously. Get the correct category_image_transaction_id from the response returned, or by calling the Validate Session API endpoint.
  • SERVER_ERROR_MAX_IMAGES_TO_COMMIT_EXCEEDED
    The image being uploaded is unable to be saved since the maximum number of images has already been uploaded to the holding location by previous requests. Make a request to upload a previously imported image and set the commit_image_uploads parameter to Y.
     
  • SERVER_ERROR_CATEGORY_NOT_FOUND
    The value set in the request's keyCategoryID parameter does not match any category previously imported against the organisation. Check that a category exists with the same keyCategoryID value.
  • SERVER_ERROR_IMAGE_NOT_FOUND
    The value set in the request's keyImageID parameter does not match any image previously imported against the organisation. This only occurs when the drop parameter is to 2 - update. Check that an image exists with the same keyImageID value, or otherwise set the drop value 1 - create, to allow a new image to be imported instead of just updated.
     
  • SERVER_ERROR_UNSUPPORTED_FILE_FORMAT
    The image file being imported has is in an image format that is not supported. Ensure that a jpeg, gif or png image is being uploaded with either the gif, giff, jpg, jpeg, or png file extension. For jpeg images ensure that the image's colour profile is set as RGB.
     
  • SERVER_ERROR_ORG_NOT_ENOUGH_CREDITS
    The organisation doesn't have enough trading tokens to cover the cost of importing the current category image, or for committing all the images in the current transaction. Additional trading tokens need to be purchased for the organisation, see Buy More Trading Tokens For An Organisation.
     
  • SERVER_ERROR_IMAGE_CANNOT_BE_RESIZED
    After the image was uploaded the endpoint was unable to resize the image into different sizes, required to optimise when being loaded within the platform. Check that the image is saved in the correct supported image format, jpeg, gif, or png. For jpeg images ensure its colour profile is saved as RGB. Also check that the image dimensions are not too big. Images should be under 2000px in width and 2000px in height.
     
  • SERVER_ERROR_NO_IMAGES_TO_COMMIT
    If the request has the commit_image_uploads parameter set to Y but no images have been imported and placed into the holding location. Ensure that you have placed an image within the request body's "upload file" parameter.
     
  • SERVER_ERROR_IMAGE_CANNOT_BE_SAVED
    If the request has the commit_image_uploads parameter set to Y but the images stored in the holding location were unable to be processed and committed against their product then this error may occur. If this contunually occurs please raise an issue with the SQUIZZ.com feeds.
     
  • SERVER_ERROR_UNKNOWN
    An unspecified error occurred when calling the API. If this error continually occurs then raise a post within the feeds on the SQUIZZ.com platform.
configs.images_committed_count INTEGER Number of image records that were successfully committed in the one transaction against their categories. This will be set to 0 unless the commit_image_uploads request parameter is to Y, and one or more images is successfully committed.
configs.category_image_upload_transaction_id STRING ID of either the current "category_image_upload_transaction_id", or if the commit_image_uploads request parameter is to Y, and one or more images is successfully committed in the same transaction, then this will contain the new transaction ID required for the next set of category images uploaded.
configs.api_version STRING Version of the API being used to handle the endpoint request.

HTTP Response Example:

{
  "resultStatus": "1",
  "version": "1.4",
  "configs": {
    "api_version": "1.0.0.0",
    "result": "SUCCESS",
    "result_code": "SERVER_SUCCESS",
    "images_committed_count": 12,
    "category_image_upload_transaction_id": "11EBD1E82B3826109F0B6AF3476460FC"
  },
  "message": ""
}