[PATCH] Modify Product — Noventiq Checkout

Noventiq CheckoutIntegrationProducts API

[PATCH] Modify Product

Request Description

PATCH /v1/product/[product id]

The request allows you to modify the properties of product.

Connection Data

Endpoint URL:
- Production environment: https://api.ecommerce.noventiq.com/v1/product
- Test environment: https://api.ecommerce.noventiq.com.demoslweb.com/v1/product
Request Method: PATCH
Format: JSON
Authorization: token-based

URL Parameters

[product id]

required

Product identifier
You can get it from:

Example: /v1/product/123456

Header Parameters

content-type

string

required

MIME-type

It must be equal to "application/json".

AuthorizationJWT

required

Authorization token

Format: Bearer [token]
Replace [token] with the token value you get in response to the request sent to the Authentication API

Body Parameters

[...]

The list of valid parameters is the same as in the request for creating products. The parameter requirements are the same, except:

family_name - optional parameter
name - optional parameter
variants - optional parameter

Data Update Peculiarities

For the following parameters, all nested elements are fully updated if the parameter is transferred in the request:

Prices - variants
Localization data - localization_values
Display settings - display_settings
Renewal settings - renew_settings
Additional products settings - cross_sell
TYPO settings - typo
Localization data for the TYPO - typo.localization_values
License data - license_data

For these parameters:

If the parameter is transferred, then all (not only transferred) corresponding nested data will be overwritten completely
If there is no parameter in the modify request, then the values filled out previously will not change

Examples:

During product creation, the localization_values parameter containing data for the cs_CZ locale is transferred
The localization_values parameter containing data only for the en_EN locale is transferred in the modify request
Result:
- Only data for en_EN will remain in the product
- ДData for cs_CZ will be deleted

In this example, to add a translation for another language to the existing one, you have to transfer the data in the request for all the locales for which there should be the translation (in the example given, these are cs_CZ and en_EN).

Request Example

{
 "family_name": "Demo Product",
 "name": "1 Pc / 1 year",
 "is_publish": true,
 "image_url": "https://my-shop.com/images/product-1234.png",
 "description": "<p><strong>Test product</strong></p>",
 "comment_for_manager": "There will be a full description later",
 "url_to_instructions": "https://www.google.com",
 "url_to_download": "https://www.google.com",
 "business_segment": "b2c",
 "available_for_sale": "all",
 "is_service": true,
 "license_type": "new",
 "licence_term": "P1Y",
 "renew_settings": {
  "product_id_for_renew": [
   4645130,
   4645131,
   4645131
  ],
  "renew_ar": {
   "enable": true,
   "required": false
  },
  "renew_pmr": true,
  "renew_email": false
 },
 "localization_values": {
  "en_EN": {
   "family_name": "Test product",
   "name": "1 PC/1 year",
   "description": "<p><strong>Test product</strong> for test purchase</p>",
   "comment_for_cart": "This is a test purchase.",
   "comment_for_product_top": "The license is valid for 1 year.",
   "comment_for_product_middle": "New version of the test product.",
   "comment_for_product_for_AR": "The license is renewed automatically.",
   "comment_for_product_for_MR": "You will need to manually renew your license after 1 year.",
   "comment_for_product_bottom": "This license is not for sale or activation outside of the country."
  },
  "cs_CZ": {
   "family_name": "Zkušební výrobek",
   "name": "1 ks / 1 rok",
   "description": "<p><strong>Testovací produkt</strong> pro zkušební nákup</p>",
   "comment_for_cart": "Jedná se o zkušební nákup.",
   "comment_for_product_top": "Licence je platná po dobu 1 roku.",
   "comment_for_product_middle": "Nová verze testovaného produktu.",
   "comment_for_product_for_AR": "Licence se obnovuje automaticky.",
   "comment_for_product_for_MR": "Budete muset ručně obnovit licenci po 1 roce.",
   "comment_for_product_bottom": "Tato licence není určena k prodeji nebo aktivaci mimo zemi."
  }
 },
 "display_settings": {
  "hide_name": true,
  "hide_item_quantity": true
 },
 "variants": [{
   "vendor_code": "1",
   "sku": "111",
   "from": 1,
   "to": 5,
   "price": {
    "USD": {
     "currency": "USD",
     "price": "99.99"
    },
    "EUR": {
     "currency": "USD",
     "price": "99.99"
    }
   }
  }, {
   "vendor_code": "1",
   "sku": "111",
   "from": 6,
   "price": {
    "USD": {
     "currency": "USD",
     "price": "80.99"
    },
    "EUR": {
     "currency": "USD",
     "price": "80.00"
    }
   }
  }
 ],
 "cross_sell": {
  "type": "add_to_basket",
  "status": true,
  "date_from": "2020-10-15 14:18:00",
  "date_to": "2020-10-25 14:18:00",
  "removal_available": true,
  "quantity_change_available": false,
  "product_id": [
   4645130,
   4645131
  ]
 },
 "typo": {
  "status": true,
  "date_from": "2020-10-15 14:18:40",
  "date_to": "2020-10-25 14:18:40",
  "localization_values": {
   "en_EN": {
    "comment_for_typo": "This is a test purchase."
   },
   "cs_CZ": {
    "comment_for_typo": "Jedná se o zkušební nákup."
   }
  },
  "product_id": [
   4645130,
   4645131
  ]
 },
 "license_data": {
  "en_EN": {
   "customer_notification": "Key: {KEY}"
  },
  "cs_CZ": {
   "customer_notification": "Klíč: {KEY}"
  }
 }
}

Data Deletion Peculiarities

If you want to delete any property values of a product when updating:

For the parameters listed above, complete replacement of previously transferred data with new values happens, if any of the parameters is present in the request. Moreover:

If you want to replace all old values with new ones, it is enough to simply transfer new values
If you need to remove renewal settings, transfer false in related parameters (renew_settings.renew_ar.enable, renew_settings.renew_pmr, renew_settings.renew_email). This will automatically unbind renewal products (renew_settings.product_id_for_renew). These renewal products will remain in the system
If you want to return default values to product display settings (display_settings), transfer the parameter having an empty value ({})
If you want to delete additional products settings / TYPO, transfer false in related objects (cross_sell.status, typo.status)
If you need to delete localized values (localization_values), transfer empty data arrays for a related language
You cannot delete all prices of a product

To delete the product description, the URL to instructions explainig how to install the product, the URL to product download link, etc., transfer the related parameters empty (""). Product image deletion is currently not supported. You have to contact our support team if you require this option
You cannot delete order fulfillment data (license_data); if you want to stop using individual values for products and return to the default settings, you have to contact our support team

Example of Request for Deleting Product Data

{
  "description": "",
  "comment_for_manager": "",
  "url_to_instructions": "",
  "url_to_download": "",
  "licence_term": "",
  "localization_values": {
    "en_EN": {}
  },
  "display_settings": {},
  "renew_settings": {
    "product_id_for_renew": [],
    "renew_ar": {
      "enable": false,
      "required": false
    },
    "renew_pmr": false,
    "renew_email": false
  },
  "typo": {
    "status": false
  },
  "cross_sell": {
    "status": false
  }
}

Response Description

In response to the request, you receive the server response code corresponding to the processing result. Depending on the code, the response body may contain additional parameters.

Successful Response

If processing is successful, the following will return in response server response code: HTTP/1.1 200 ОК.

Error Response

If an error occurs while processing the request, you receive a server response code corresponding to the result of processing.
Depending on the code, the response body may contain additional parameters.

HTTP Server Response Error Code

HTTP code	Description
HTTP/1.1 400 Bad Request	The request is not valid (error in parameters; necessary data is not transferred, etc.). An additional error code (one or more) will be transferred in the response bodу.
HTTP/1.1 401 Unauthorized	Unsuccessful authorization. An additional error code (one or more) will be transferred in the response bodу.
HTTP/1.1 404 Not found	Invalid request URL or no product having the identifier transferred is found. If no product is found, an additional additional error code will return in the response body.
HTTP/1.1 500 Request Error	Internal Server Error. Please try again later or contact support.

Additional Error Codes for HTTP 400

The errors are the same as the errors you get in response to the request for creating a product.

Additional Error Codes for HTTP 401

The errors are the same for all the APIs that use token authorization.

Additional Error Codes for HTTP 404

Error	Message	Description
11200	Product not found	No product with the identifier transferred is found, or you do not have the rights to get the data.

Body Parameters

errors

array [objects]

required

Error list

errors / [error object]

error

number

required

Error code

errors / [error object]

message

string

Error description

Example of Error Response

{
 "errors": [{
   "error": 1010,
   "message": "Invalid field value: name"
  }, {
   "error": 1010,
   "message": "Invalid field value: family_name"
  }
 ]
}