Knowledge Base
Noventiq Checkout
Up
Knowledge Base
Noventiq CheckoutIntegrationDynamic Product Checkout API
[POST] Generate Checkout Link

[POST] Generate Checkout Link

Request Description

POST /v1/generate_buy_link

The request allows getting a link using which:

  • The customer gets redirected to the checkout page.
  • All products having dynamic information and transferred in the request are added to the cart.
  • Customer data required for placing an order is overwritten with the data transferred in the request.

Request contains:

Connection Data

Header Parameters

content-type
string
required
MIME-type.
It must be equal to "application/json".
AuthorizationJWT
required
Authorization token.
  • Format: Bearer [token]
  • Where [token] is substituted by the token value obtained through the authentication API

Body Parameters

currency
string
required
Checkout currency code
The available currencies are configured upon in accordance with the agreement.
  • Format: ISO 4217 alpha-3, 3 characters
  • For the value options, see the reference guide
market_id
number
required*
Your checkout page ID
If the checkout page ID is transferred and selling though this checkout page in the corresponding currency is allowed, a checkout link is generated for the checkout page.
  • * - Required if you have several checkout pages using the same checkout currency, otherwise you may not transfer it
  • Contact our support team to find out your checkout page ID
products
array [objects]
required
List of dynamic products
Each object in an array corresponds to one product to be added to a checkout page.

For each of the products, you transfer:
  • The identifier of the original product from which the default settings will be taken
  • The property values (name, price, etc.) that will override the properties of the original product on the checkout page
You can transfer several objects inside the array to add several products to the checkout page at once via a single checkout link. In this case, each product uses its own (separate) original product.
products / [object]
/
id
number
required
Original product ID
You received this ID when configured original product. If the request contains several products, then their id must not match. It means that one request cannot contain two products having dynamic information and being based on the same original product.
products / [object]
/
sku
string
Product SKU on your end
Recommended to be used to transfer the product article according to the your price list.
  • Must not exceed 40 characters
  • The default value is set in the original product
products / [object]
/
vendor_code
string
Product ID on your end
  • Must not exceed 255 characters
  • The default value is set in the original product
products / [object]
/
name
string
required
Product name
products / [object]
/
name_for_invoice
string
Product name for documents
When transferred, it is used in an invoice instead of the product name from parameter products.name.
products / [object]
/
price
string
required
Price per product unit
It is used to calculate the total price of the product at checkout.
  • Format: Numeral with 2 decimal places, separator – dot, transferred as a string
  • The price may be equal to zero if the product is a gift, learn more on how to add a gift to the order correctly
  • Sale of products having free trial periods and zero prices is currently not available through this API
products / [object]
/
discount_percent
number
Product discount percentage
  • Format: Numeral, up to 6 decimal places, separator - dot
  • The value must meet the following condition: 0 < discount_percent ≤ 100
  • The price may be equal to 100% if the product is a gift, learn more on how to add a gift to the order correctly
products / [object]
/
quantity
number
required
Product quantity
The customer will not be able to change this quantity.
products / [object]
/
is_delivery_needed
boolean
Product delivery method

Value options:
  • true - physical delivery
  • false - electronic delivery (license information is sent to the customer's email)
The default value is set in the original product.
products / [object]
/
is_installments_unavailable
boolean
Forbid installment payment for products

Value options:
  • true - product cannot be paid in installments If installment payment is forbidden for at least one product in the request, it will not be offered for the order
  • false - product can be paid in installments
It is false by default.

The possibility of payment in installments is configured for the entire checkout page as an individual feature. More details on this option.
products / [object]
/
is_service
boolean
Technical field
products / [object]
/
subscription
object
Subscription settings (AR)
  • If the parameter has been transferred and the auto-renewal option has been preset for the original product, an auto-renewable subscription will be available for the dynamic product in the cart on the checkout page
  • If the parameter has not been transferred, the auto-renewal option will not be available for the product in the cart on the checkout page (even if the auto-renewal option has been preset for the original product)
More details on how auto-renewal works with dynamic products.
products / [object] / subscription
/
period
string
required*
Validity term, for the product that initiates the subscription (parent).
  • * - Required, if subscription parameter is transferred
  • Format: ISO 8601 code: P[date][unit of measure]
  • Units of measure supported: Y - year, M - month, D - day
    E.g., "P1Y" is "1 year"
products / [object] / subscription
/
name
string
Product name for subscription renewal (child)
The default value is set in the original product.
products / [object] / subscription
/
price
string
Price per renewal product item (child)
Learn more about calculating the final price for renewal.
  • Format: Numeral with 2 decimal places, separator - dot. Transferred as a string
  • The default value is set in the original product
customer
object
Customer data
If the field is transferred, then the customer data will be pre-filled in the cart. The customer can change these values.
customer / [object]
/
type
string
Customer type

Value options:
  • physical - individuals
  • juridical - companies
customer / [object]
/
email
string
Customer's email

Must not exceed 72 characters.
customer / [object]
/
first_name
string
Customer's name

Must not exceed 255 characters.
customer / [object]
/
last_name
string
Customer's last name

Must not exceed 255 characters.
customer / [object]
/
phone
string
Customer's phone number

Must not exceed 64 characters.
customer / [object]
/
vat_number
string
Customer's taxpayer identification number
Also used to fill in the INN field for sales in Russia. The number will be prefilled only if a checkout page has one field for entering the Taxpayer Identification Number of the customer (field display depends on checkout currency). Otherwise, the customer must fill in the Taxpayer Identification Number themselves.

Must not exceed 255 characters.
company_name
string
customer / [object]
Company name

Must not exceed 255 characters.
customer / [object]
/
company_billing_address
string
Legal address

Must not exceed 255 characters.
customer / [object]
/
company_delivery_address
string
Actual address

Must not exceed 255 characters.
customer / [object]
/
country
string
Customer's country code
  • Format: ISO 3166-1
  • If a country code is transferred, and it is true to the request currency, then the country will be automatically selected in the cart
  • If the country is not true to the request currency (currency), but is available in the cart, then the country field has a higher priority, the currency in the cart will be set according to the country code transferred, see examples further
additional_data
object
Additional parameters
The values that will be saved to the order as referrers can be transferred. It is saved and further used. More details on additional parameters. Please note that the time for storing additional parameters in orders is limited.
additional_data
/
referer7
string
Referer7 value

Must not exceed 255 characters.
additional_data
/
referer8
string
Referer8 value

Must not exceed 255 characters.
additional_data
/
referer9
string
Referer9 value

Must not exceed 255 characters.
additional_data
/
referer10
string
Referer10 value

Must not exceed 255 characters.
additional_data
/
referer11
string
Referer11 value

Must not exceed 255 characters.
additional_data
/
referer12
string
Referer12 value

Must not exceed 255 characters.
upsell
object
Data for up-sell offers when visiting checkout page
Use this parameter to suggest customers to replace one of their products in a checkout page with a better one. This offer will be displayed to the customer as soon as they go to the checkout page using a checkout link.

More details on how up-sell offers work for dynamic products.
upsell / object
/
product_id
number
required*
Product IDs for which up-sell offers are to be displayed
One of such products is selected and added to the checkout page (products) by the customer. After is has been added, an up-sell offer is shown to the customer to suggest them to replace their product with a different one.
  • * Required if upsell has been transferred
  • The ID transferred in this parameter must be the same as one of the IDs of the original product products.id
See additional guide and examples for filling.
upsell / object
/
name
string
required
Up-sell offer title
It is displayed to the customer in an up-sell offer. This can be, for example, the name of the product for which a replacement product is suggested in the up-sell offer. For more details, see the description of the up-sell offer template.
  • * Required if upsell has been transferred
  • Must not exceed 255 characters
upsell / object
/
description
string
Up-sell offer description
It is displayed to the customer next to the up-sell offer title, if the parameter has been transferred. For more details, see the description of the up-sell offer template.
upsell / object
/
picture_url
string
Up-sell offer image URL
An up-sell offer may contain an image. It is located on your end and uploaded into the window of an up-sell offer when opened. Currently, this feature is only available for customized up-sell offer templates. If you want to use a customized offer template, write to ecommerce@noventiq.com describing the changes you require to be made to the default template.
  • Image URL requirements:
    • A valid URL leading to the image file located on your end in open access (no authorization required)
    • Only https protocol is allowed
    • Must not exceed 255 characters
  • Acceptable image formats: *.gif, *.jpg, *,jpeg, *.png
  • mimeTypes: 'image/gif', 'image/jpg', 'image/jpeg', 'image/pjpeg', 'image/png', 'image/x-png'
If for some reason it was not possible to get an image, it will not be displayed. There are no error messages or image placeholders facing the customer.

When displayed, the image can be scaled according to the dimensions provided by the design.
upsell / object
/
products
array [objects]
required*
List of up-sell products
These are the products that will be suggested to the customer in an up-sell offer. If the customer selects one of them, this product will be added to the checkout page. The product for which the up-sell offer (upsell.product_id), has popped up will be removed from the checkout.

Each object in the array corresponds to one product to be displayed in the up-sell offer.
  • * Required if upsell has been transferred
  • 1 to 3 products must be transferred in the array
upsell / object / products / object
/
id
number
required*
Original up-sell product ID
  • * Required if upsell has been transferred
  • May be the same as the ID of the product on the checkout page for which an up-sell offer is displayed (upsell.product_id)
  • Must differ from the rest product IDs present on the checkout page and transferred in the array of products, except for the product for which the up-sell offer is displayed upsell.product_id
  • You can use the same original product for all replacement products transferred in the array of upsell.products
See additional guide and examples for filling.
upsell / object / products / object
/
sku
string
Your up-sell product SKU

Must not exceed 40 characters.
upsell / object / products / object
/
vendor_code
string
Your up-sell product ID

Must not exceed 255 characters.
upsell / object / products / object
/
name
string
required*
Up-sell product name at checkout
This name will be displayed for the product on the checkout page after the customer selects it in the up-sell offer.

* Required if upsell has been transferred.

Note that using parameters upsell.products.name and upsell.products.name_for_upsell, you can set 2 different names for the same product: You can use this capability, for example, to display products having short titles in an up-sell offer.
upsell / object / products / object
/
name_for_upsell
string
required*
Up-sell product name
This name will be displayed for the product in the up-sell offer. See parameter upsell.products.name.

* Required if upsell has been transferred.
upsell / object / products / object
/
name_for_invoice
string
Up-sell product name for closing documents
When transferred, it is used in an invoice instead of the product name from parameter upsell.products.name.
upsell / object / products / object
/
price
string
required*
Price per up-sell product item
It is used in up-sell offers and on checkout pages when calculating the product price
  • * Required if upsell has been transferred
  • Format: Numeral with 2 decimal places, separator - dot. Transferred as a string
  • Include the VAT amount into the price amount, if your Agreement allows for it. For more details, see the description of presets
  • If you want to give a discount on a product to the customer, transfer the discounted price in this parameter
  • Price must be greater than zero
upsell / object / products / object
/
benefit
string
Up-sell total benefit (saving)
It is displayed to the customer only in up-sell offers. This value is informational. It does not affect the price of a product in the up-sell offer or at checkout. For more details, see the description of the up-sell offer template.
  • Format: Numeral with 2 decimal places, separator - dot. Transferred as a string
  • The full price value must be transferred. We do not recalculate this value in any way, as well as when the product quantity and VAT are included
upsell / object / products / object
/
quantity
number
required*
Up-sell product quantity
It is used in the up-sell offer and on the checkout page when calculating the product price. The customer will not be able to modify this quantity.

* Required if upsell has been transferred.
upsell / object / products / object
/
subscription
object
Set up auto-renewable (AR) subscriptions for up-sell products
Transfer this parameter to make auto-renewable subscriptions be available for up-sell products.

The nested parameters and fill-in instructions are the same as for parameter products.subscription.
upsell / object / products / object / subscription
/
period
string
required*
Validity term of up-sell product initiating subscription (parent)

The fill-in instructions are the same as for parameter products.subscription.period.
upsell / object / products / object / subscription
/
name
string
Renewal product (child) name extending up-sell product subscription

The fill-in instructions are the same as for parameter products.subscription.name.
upsell / object / products / object / subscription
/
price
string
Price per renewal product item (child) extending up-sell product subscription

The fill-in instructions are the same as for parameter products.subscription.price.
upsell / object / products / object
/
additional_data
object
Additional parameters for orders containing up-sell products
This is non-customer facing service data. It does not affect the checkout process. More details on how to use additional parameters.

If this parameter has been transferred, and the customer has selected one of the products suggested by the up-sell offer, then:
  • If in parameters additional_data and upsell.products.additional_data (for the product selected), the referrer having the same name is transferred, its value in upsell.products.additional_data will be replaced with the value in additional_data
  • If in parameter upsell.products.additional_data (for the product selected), the referrer having the name that differs from the name of the referrer in additional_data, the referrer from upsell.products.additional_data will be added to the ones existing in additional_data
  • If in parameter additional_data the referrer is transferred and it has the name that does not exist in upsell.products.additional_data (for the product selected), the referrer value in additional_data will remain unchanged
For more details, see the description of additional parameters and the example of how to use them when replacing checkout products with up-sell products.

If parameter upsell.products.additional_data is not transferred and the customer selects one of the products suggested by the up-sell offer, data from additional_data is used.
upsell / object / products / object / additional_data
/
referer7
string
Referer7 value for orders containing up-sell products
upsell / object / products / object / additional_data
/
referer8
string
Referer8 value for orders containing up-sell products
upsell / object / products / object / additional_data
/
referer9
string
Referer9 value for orders containing up-sell products
upsell / object / products / object / additional_data
/
referer10
string
Referer10 value for orders containing up-sell products
upsell / object / products / object / additional_data
/
referer11
string
Referer11 value for orders containing up-sell products
upsell / object / products / object / additional_data
/
referer12
string
Referer12 value for orders containing up-sell products
upsell_exit
/
upsell_exit
object
Data for up-sell offers when leaving checkout page
Use this parameter to suggest customers to replace one of their products in a checkout page with a better one. This offer will be displayed to the customer if:
  • The mouse cursor goes beyond the active area of the browser window in which the checkout page is open
  • The customer did not replace the product they had added to the checkout page with the product from the previously shown up-sell offer (upsell)
More details on how up-sell offers work for dynamic products.
upsell_exit-params
/
[...]
The list of allowed parameters is the same as for parameter upsell.

Request Example (required parameters only)

{
  "currency": "EUR",
  "products": [
    {
      "id": 111111,
      "name": "Base version for 3 year",
      "price": "30.00",
      "quantity": 10
    }
  ]
}

Request Example (all parameters)

{
  "currency": "EUR",
  "products": [
    {
      "id": 111111,
      "vendor_code": "API-1",
      "sku": "L1-1",
      "name": "Base version for 3 year",
      "name_for_invoice": "Program 1 v1, 3",
      "price": "100.00",
      "discount_percent": 10,
      "quantity": 1,
      "is_delivery_needed": false,
      "is_installments_unavailable": false,
      "subscription": {
        "period": "P1Y",
        "name": "Renewal for 1 year",
        "price": "30"
      }
    }
  ],
  "customer": {
    "type": "juridical",
    "email": "test@test.com",
    "first_name": "Marcel",
    "last_name": "Laporte",
    "phone": "7999991111",
    "vat_number": "12345654321",
    "company_name": "Company name",
    "company_billing_address": "Trocadéro, Avenue Anatole-France, 5",
    "company_delivery_address": "Trocadéro, Avenue Anatole-France, 5",
    "country": "FR"
  },
  "additional_data": {
    "referer7": "product=test&project=test",
    "referer8": "testA",
    "referer9": "testB",
    "referer10": "testC",
    "referer11": "testD",
    "referer12": "testF"
  }
}

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 ОК and json with a checkout link.

Body Parameters

buy_link
string
Checkout link.
  • Format: https://[checkout page domain]/basket/flash/[dynamic checkout page ID]
  • When working in the test environment, a checkout link intended for the test environment will return in response (such links will have the .demoslweb.ru suffix added)
  • In case, when following the link, an empty checkout page opens (no product has been added), then this problem occurs if the original product is not available for sale on the our end. Review the original product id in the request
external_id
string
required
Dynamic checkout page ID
This identifier is generated when each request is processed; i.e. you get a unique identifier in response every time. If your end customer places an order using the checkout link received in response to a request, the system saves the identifier into the order. Later, you can get it from the order data, e.g. in webhooks or through the Orders API.

Example of Successful Response

{
 "buy_link": "https://cart.checkout.noventiq.com/basket/flash/123456",
 "external_id": "123456"
}

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
110 JSON is not valid. The request cannot be processed. Request field structure is not valid. Check the fields in the request body against the JSON format
111 Invalid data format (Content-type). The request cannot be processed. Invalid request header. Content-type must be equal to application/json
3120 Unable to define cart settings for this currency. Please contact technical support. Failed to identify a cart or a product for the sale currency transferred (currency)
3125 Sales through this cart are impossible with this currency. Please contact technical support. Failed to identify a cart or a product for the sale currency transferred (currency) and checkout page (market_id)
If at least one error from the list below is found, then the request checking is not interrupted. Several errors may return in response
3010 Invalid field value: [parameter name] The request is not valid, e.g., the required field is not filled out, the field name is incorrect, the field 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 field, and this value option is not set as valid in the field description
3020 Order price cannot be equal to zero. Change product price (price, discount_percent) or add product having non-zero price. The discounted product is equal to zero (products.price = 0 or products.discount_percent = 100), but there is no other product in the request that has a value greater than zero
3030 Incorrect discount value. Discount_percent value must be strictly greater than zero and less than or equal to 100. Invalid discount value (products.discount_percent). The value must meet the following requirements: 0 discount_percent <= 100
3040 Purchase of this original product subscription is impossible. Change original product (id) or delete subscription data (subscription). The request contains the data for the subscription (products.subscription), but the settings required are not made for the original product
3050 Purchase of this original product is impossible. Change original product (id). The request contains the original product (products.id), that cannot be found on the our side
3060 Email field is filled out incorrectly. Expected format: [name]@[domain].[zone] Invalid email address is transferred (customer.email)
3070 Single request must contain products with different products.id values. More than one product is transferred with the same id. (products.id)
3210 Unable to show up-sell offer. The product id upsell.product_id must match at least one product in the cart (products.id). The request contains the up-sell offer data (upsell), but the product ID for which you want to show the up-sell offer (upsell.product_id) does not exist among the products to be added to the checkout page (products)
3220 Unable to show up-sell offer. The replacement product id (upsell.products.id) must not match the id of the product in the cart which is not upsell.product_id. The request contains the up-sell offer data (upsell), but there is some product that is already present on the checkout page (products) in the list of replacement products (upsell.products), and this product is not the one for which the up-sell offer is displayed (upsell.product_id)
3230 Unable to show up-sell offer. The cost of a replacement product cannot be zero. The product price in the up-sell offer (upsell) is incorrect. The price of a replacement product cannot be equal to zero
3240 Unable to show up-sell offer. The number of replacement products must be 3 or less. The number of products to be offered as replacements in the up-sell offer (upsell.products) is incorrect. The number of products inside the array must be from 1 to 3
3310 Unable to show up-sell offer. The product id upsell_exit.product_id must match at least one product in the cart (products.id). The request contains the up-sell offer data (upsell_exit), but the product ID for which you want to show the up-sell offer (upsell_exit.product_id) does not exist among the products to be added to the checkout page (products)
3320 Unable to show up-sell offer. The replacement product id (upsell_exit.products.id) must not match the id of the product in the cart which is not upsell.product_id. The request contains the up-sell offer data (upsell_exit), but there is some product that is already present on the checkout page (products) in the list of replacement products (upsell.products), and this product is not the one for which the up-sell offer is displayed (upsell.product_id)
3330 Unable to show up-sell offer. The cost of a replacement product cannot be zero (upsell_exit.products.price). The product price in the up-sell offer (upsell_exit) is incorrect. The price of a replacement product cannot be equal to zero
3340 Unable to show up-sell offer. The number of replacement products must be 3 or less (upsell_exit.products). The number of products to be offered as replacements in the up-sell offer (upsell.products) is incorrect. The number of products inside the array must be from 1 to 3

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
required
Error description.

Example of Error Response

{
 "errors": [{
   "error": 3010,
   "message": "Invalid field value: currency."
  }, {
   "error": 3010,
   "message": "Invalid field value: name."
  }
 ]
}
Terms & Conditions
© 2024 Noventiq