[GET] Get Product IDs

GET /v1/product

The request allows you to get a list of product identifiers that match the search criteria provided.

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: 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.
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
  • /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)
  • 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
  • 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
  • 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
  • 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

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

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.

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.

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)
{
 "count_all": 51,
 "limit": 51,
 "offset": 0,
 "product_ids": [
  444841127,
  444652444,
  666435276
 ]
}
{
 "count_all": 0,
 "limit": 0,
 "offset": 0,
 "product_ids": []
}
{
 "count_all": 108,
 "limit": 0,
 "offset": 150,
 "product_ids": []
}

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 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.
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.

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

errors
array [objects]
required
Error list
errors / [error object]
/
error
number
required
Error code
errors / [error object]
/
message
string
Error description
{
 "errors": [{
   "error": 1200,
   "message": "Search is executed if string has at least three characters in it."
  }
 ]
}