[GET] Get Product IDs
Request Description
GET /v1/product
The request allows you to get a list of product identifiers that match the search criteria provided.
Connection Data
- Endpoints URL:
- Production environment: https://api.ecommerce.noventiq.com/v1/product
- Test environment: https://api.ecommerce.noventiq.com.demoslweb.com/v1/product
- Request Method: GET
- Authorization: token-based
If not transferred, the all products found will return in response.
- If not transferred or equal to 0, you will get the list that starts from the 1st product found
- For example, if 10 is transferred, you will get the list that starts from the 11th product found
If transferred, the IDs of the products that have an occurrence of the transferred string in at least one of the following parameters will return in response:
- Title (family_name)
- Subtitle (name)
- Description (description)
- SKU (variants.sku)
- Product identifiers inside your system (variants.vendor_code)
Not less than 3 characters.
Allows you to exclude child products from the response if the parent product contains enabled subscriptions with automatic renewal.
The product will be excluded from the request response if all the conditions are met:
- The product is a child product: the product identifier is present in the renew_settings.product_id_for_renew of another product.
- The parent product contains an enabled subscription with automatic renewal (renew_settings.renew_ar.enable:true).
- The product is simultaneously neither a parent product nor a child renewal product
Value options:
- 1 - child products are excluded from the response except cases when the parent product renews itself
- 0 - child products are not excluded from the response
When using the two filters: search_string and exclude_renew_ar_products = 1, the following will return in response:
- The parent products for which an occurrence of the string transferred in search_string is found
- The parent products for which no occurrence of the string transferred in search_string is found, but at least one child product in which there is an occurrence is bound to the product
Allows you to exclude from the response all the products that have prices equal to zero (e.g., due to the fact that a product is a trial one, a gift, or its price has not been set).
Value options:
- 1 - products having prices equal to zero are excluded from the response
- 0 - products having prices equal to zero are not excluded from the response
If the parameter is transferred, the response returns the products available for sale in at least one of the transferred currencies. Note that a product is considered available for sale in all the currencies allowed by the Agreement if its prices are set using one common price or the following pricing models: One price, Volume pricing.
- Format: sale_currency[]=[checkout currency], where [checkout currency] – is a currency code in ISO 4217 alpha-3 format, 3 characters, see the reference for value options. E.g.: sale_currency[]=USD
- Several parameters sale_currency containing different checkout currencies can be transferred in one request. In such a case they must be separated by &. E.g.: sale_currency[]=USD&sale_currency[]=EUR
You can enable sorting of identifiers by the date and time of their update (update_date) in response to the request
Value options:
- desc - sorting by update date in descending order (from latest to earliest), for example: 01.01.2022 00:00:00 > 01.01.2022 00:00:00
- asc - sorting by update date in ascending order (from earliest to latest), for example: 01.01.2022 00:00:00 > 01.01.2022 00:00:00
- Format:
Bearer [token]
- Replace [token] with the token value you get in response to the request sent to the Authentication API
Request Example
- /v1/product
All available products. The list is sorted by product ID - /v1/product?search_string=test
All the available products that have string "test" present in at least one of the parameters listed in the description of parameter search_string. The list is sorted by product ID - /v1/product?exclude_renew_ar_products=1
All the products available excluding the child products used to renew AR subscriptions. The list is sorted by product ID - /v1/product?sale_currency[]=USD&sale_currency[]=EUR
All available products that are allowed to be sold in at least one of the currencies: USD, EUR - /v1/product?limit=10
First 10 products found. The list is sorted by product ID - /v1/product?limit=10&offset=5
10 products, starting with the 6th up to the 15th. The list is sorted by product ID - /v1/product?offset=5
All products, starting with the 6th out of all the found ones. The list is sorted by product ID - /v1/product?sort_by_update_date=desc
All the products available. The list is sorted by product update date in descending order (update_date)
Additional Examples for Parameter exclude_renew_ar_products
Example for disabled AR subscription
- For product 001, the auto-renewable (AR) subscription has been disabled:
"renew_settings": { "renew_ar": { "enable": false }, "renew_pmr": false, "renew_email": false }
- In response to request /v1/product?exclude_renew_ar_products=1 product 001 returns
Example for product with AR subscription when child product has not been excluded from response
- For product 002, the auto-renewable (AR) subscription has been enabled. Product 002 is used to create subscriptions and renew them (i.e. the product is both parent and child for itself):
"renew_settings": { "product_id_for_renew": [002], "renew_ar": { "enable": true } }
- In response to request /v1/product?exclude_renew_ar_products=1 product 002 returns, since the exception is applied - product renews itself
Example for child product exclusion from response
- For product 003, the auto-renewable (AR) subscription has been enabled. Product 003 is parent, i.e. initiates subscription creation. Product 004 is used to renew the subscription:
"renew_settings": "renew_settings": { "product_id_for_renew": [004,004], "renew_ar": { "enable": true } }
- In response to request /v1/product?exclude_renew_ar_products=1 product 003 returns. Product 004 is excluded from the response because it is child
Example for enabled PMR subscription
- For product 006, the auto-renewable (AR) subscription has been disabled, but the PMR subscription has been enabled. Product 006 is parent, i.e. initiates subscription creation. Product 007 is used to renew the subscription:
"renew_settings": { "product_id_for_renew": [007, 007], "renew_ar": { "enable": false }, "renew_pmr": true }
- In response to request /v1/product?exclude_renew_ar_products=1 products 006 and 007 return, since AR subscriptions are disabled and no exception of child products is applied
Additional Examples for Parameter sale_currency
Let us assume you have products:
- Product 001 – has individual prices set in checkout currencies: AUD, CAD
- Product 002 – has one common price in base currency: EUR, thus, this product is available for sale in all the currencies established according to the Agreement
Currencies available under the Agreement: USD, EUR, AUD, CAD, GBP, NZD
Parameters in request |
Products in response |
sale_currency[]=AUD |
001, 002 |
sale_currency[]=EUR |
002 |
sale_currency[]=USD |
002 |
sale_currency[]=AUD&sale_currency[]=USD |
001, 002 |
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 ОК. Response body: list of found product IDs in JSON format.
Response example: products are found
{
"count_all": 51,
"limit": 51,
"offset": 0,
"product_ids": [
444841127,
444652444,
666435276
]
}
Response example: no products are found
{
"count_all": 0,
"limit": 0,
"offset": 0,
"product_ids": []
}
Response example: no products are found (invalid conditions for obtaining: offset>count_all)
{
"count_all": 108,
"limit": 0,
"offset": 150,
"product_ids": []
}
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. |
HTTP/1.1 500 Request Error | Internal Server Error. Please try again later or contact support. |
Additional Error Codes for HTTP 400
Error | Message | Description |
If at least one error from the list below is found, then it returns in response to a request, other errors are not validated. | ||
1025 | Failed to identify settings for obtaining product list. Please contact technical support. | During processing, we could not identify your account setting unambiguously. Please contact support team. |
If at least one error from the list below is found, then request validation is not interrupted. Several errors may return in response. |
||
1200 | Search is executed if string has at least three characters in it. |
The search_string, is transferred in the request, but its value is less than 3 characters. |
1210 | Invalid field value: [parameter name] |
The request is not valid, e.g., the parameter name is incorrect, the parameter value does not match with the data type provided, or the value format is incorrect. Moreover, the error will return if null is transferred in the parameter, and this value option is not set as valid in the parameter description. |
1220 | Failed to generate a response for product [id]. Please contact technical support. |
The product settings made on the our end do not allow adding product information in response to the request. Please contact support team. |
Additional Error Codes for HTTP 401
The errors are the same for all the APIs that use token authorization.
Example of Error Response
{
"errors": [{
"error": 1200,
"message": "Search is executed if string has at least three characters in it."
}
]
}