Skip to main content
Skip table of contents

[POST] Generate checkout link

CODE 
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:

content-type

string

required

MIME-type.
It must be equal to "application/json".

required

Authorization token.

  • Format: Bearer [token]

  • Where [token] is substituted by the token value obtained through the authentication API

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

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

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.

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.

string

Product SKU on your end
Recommended to be used to transfer the product article according to the your price list.

string

Product ID on your end

string

required

Product name

string

Product name for documents
When transferred, it is used in an invoice instead of the product name from parameter products.name.

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

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

number

required

Product quantity
The customer will not be able to change this quantity.

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.

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.

boolean

Technical field

object

Additional parameters for product
This is non-customer facing service data that does not affect the checkout process. The transferred values are saved for the order item.

You can transfer several additional parameter values within the additional_data object.

string

Additional parameter value

  • Replace [name] with the parameter name:

    • Must be unique within one additional_data object

    • Only Latin letters and numbers are allowed

    • Must not exceed 255 characters

  • The value can contain HTML tags, the value size is not limited.

You can transfer several additional parameter values within the additional_data object.

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.

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"

string

Product name for subscription renewal (child)
The default value is set in the original product.

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

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.

string

Customer type

Value options:

  • physical - individuals

  • juridical - companies

string

Customer's email

Must not exceed 72 characters.

string

Customer's name

Must not exceed 255 characters.

string

Customer's last name

Must not exceed 255 characters.

string

Customer's phone number

Must not exceed 64 characters.

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.

string

customer / [object]

Company name

Must not exceed 255 characters.

string

Legal address

Must not exceed 255 characters.

string

Actual address

Must not exceed 255 characters.

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

object

Additional parameters for order
This is non-customer facing service data that does not affect the checkout process. The transferred values are saved in the order. More details on how to use additional parameters. Please note that the storage period of additional parameters in the order is limited.

You can transfer several additional parameter values within the additional_data object.

string

Additional parameter value
One or several nested parameters with values can be transferred inside additional_data.

  • Replace [name] with the parameter name:

    • Must be unique within one additional_data object

    • Only Latin letters and numbers are allowed

    • Must not exceed 255 characters

    • If the name is referer1, referer2, ... etc. up to referer12, you can transfer the values of these additional parameters to the web service to generate a license

  • The value can contain HTML tags, the value size is not limited.

You can transfer several additional parameter values within the additional_data object.

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.

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.

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

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.

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.

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

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.

string

Your up-sell product SKU

Must not exceed 40 characters.

string

Your up-sell product ID

Must not exceed 255 characters.

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.

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.

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.

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

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

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.

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.

string

required*

Validity term of up-sell product initiating subscription (parent)

The fill-in instructions are the same as for parameter products.subscription.period.

string

Renewal product (child) name extending up-sell product subscription

The fill-in instructions are the same as for parameter products.subscription.name.

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.

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.

When this parameter is transferred and the customer selects one of the up-sell products, the values from upsell.products.additional_data replace the values from additional_data and products.additional_data (for the corresponding product) if the parameter names are identical. And if the names are different, the values get added to the existing additional parameters of the product and the order. See the detailed description and example of use.

string

Additional parameter value for order with up-sell product
One or more nested parameters with values can be transferred within additional_data.

The format is similar to the values transferred in additional_data.

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.

The list of allowed parameters is the same as for parameter upsell.

CODE 
{
  "currency": "EUR",
  "products": [
    {
      "id": 111111,
      "name": "Base version for 3 year",
      "price": "30.00",
      "quantity": 10
    }
  ]
}
CODE 
{
  "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,
      "additional_data": {
        "referer7": "product=demo&project=test&upsell",
        "referer8": "testA1",
        "demo": "testB1"
      },
      "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=demo&project=test&upsell",
          "referer8": "testA1",
          "demo": "testB1"
  }
}

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

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.

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

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

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

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

array [objects]

required

Error list.

number

required

Error code.

string

required

Error description.

CODE 
{
 "errors": [{
   "error": 3010,
   "message": "Invalid field value: currency."
  }, {
   "error": 3010,
   "message": "Invalid field value: name."
  }
 ]
}

Noventiq Checkout

Support

merchants.help@noventiq.com

Our resources

https://ecommerce.noventiq.com/

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close