[GET] Get Product IDs — Noventiq Checkout

Noventiq CheckoutIntegrationProducts API

[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.demonqweb.com/v1/product
Request Method: GET
Authorization: token-based

URL Parameters

limit

number

Product quantity that should return in response
If not transferred, the all products found will return in response.

offset

number

Offset: by how many products you want to shift result outputting

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

search_string

string

Search keyword string
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)

Please note: The localized values of the similar parameters that are transferred via the localization_values parameter are not included in the search.

Not less than 3 characters.

exclude_renew_ar_products

number

Exclude child products from the response
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

See the additional examples.

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

It is 0 by default.

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

exclude_zero_price_products

number

Exclude from the response all the products that have prices equal to zero
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

It is 0 by default.

sale_currency

string

Search products by checkout currency
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

See additional examples of how the search by checkout currency works.

sort_by_update_date

string

Sort by update_date
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

If not transferred, the list will be sorted by product ID, for example, 100 > 99.

Header Parameters

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

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.

Body Parameters

count_all

number

required

Number of products found

limit

number

required

Product quantity in response

offset

string

required

Offset
Starting product position followed by products that return in response.

product_ids

array [numbers]

required

Array of product IDs
The array may return empty if no products are found, e.g.:

No products created
Offset (offset) is greater than available product quantity (count_all)

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.

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": 1200,
   "message": "Search is executed if string has at least three characters in it."
  }
 ]
}