[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:
- Authorization data (token)
- Dynamic products properties
- (Optional) Subscription data
- (Optional) Customer data
- (Optional) Order additional parameters
- (Optional) Data for up-sell offers when visiting checkout page
- (Optional) Data for up-sell offers when leaving checkout page
Connection Data
- Endpoint URL:
- Production environment: https://api.ecommerce.noventiq.com/v1/generate_buy_link
- Test environment: https://api.ecommerce.noventiq.com.demoslweb.com/v1/generate_buy_link
- Request Method: POST
- Format: JSON
- Authorization: token-based
Authorization token.
- Format:
Bearer [token]
- Where [token] is substituted by the token value obtained through the authentication API
Checkout currency code
The available currencies are configured upon in accordance with the agreement.
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
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.
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
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:
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
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.
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.
Product SKU on your end
Recommended to be used to transfer the product article according to the your price list.
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
Product ID on your end
- Must not exceed 255 characters
- The default value is set in the original product
Product name for documents
When transferred, it is used in an invoice instead of the product name from parameter products.name.
When transferred, it is used in an invoice instead of the product name from parameter products.name.
Price per product unit
It is used to calculate the total price of the product at checkout.
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
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
Product quantity
The customer will not be able to change this quantity.
The customer will not be able to change this quantity.
Product delivery method
Value options:
Value options:
- true - physical delivery
- false - electronic delivery (license information is sent to the customer's email)
Forbid installment payment for products
Value options:
The possibility of payment in installments is configured for the entire checkout page as an individual feature. More details on this option.
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
The possibility of payment in installments is configured for the entire checkout page as an individual feature. More details on this option.
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)
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"
Product name for subscription renewal (child)
The default value is set in the original product.
The default value is set in the original product.
Price per renewal product item (child)
Learn more about calculating the final price for renewal.
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 data
If the field is transferred, then the customer data will be pre-filled in the cart. The customer can change these values.
If the field is transferred, then the customer data will be pre-filled in the cart. The customer can change these values.
Customer type
Value options:
Value options:
- physical - individuals
- juridical - companies
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.
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.
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 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.
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.
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.
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.
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.
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
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.
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
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.
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.
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.
When displayed, the image can be scaled according to the dimensions provided by the design.
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'
When displayed, the image can be scaled according to the dimensions provided by the design.
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.
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
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
Your up-sell product SKU
Must not exceed 40 characters.
Must not exceed 40 characters.
Your up-sell product ID
Must not exceed 255 characters.
Must not exceed 255 characters.
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:
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:
- The product name transferred in upsell.products.name_for_upsell will be seen to the customer in the up-sell offer. For more details, see the description of the up-sell offer template
- The product having the name transferred in upsell.products.name will be added to the checkout page, if the customer decides to select this product from the up-sell offer
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.
This name will be displayed for the product in the up-sell offer. See parameter upsell.products.name.
* Required if upsell has been transferred.
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.
When transferred, it is used in an invoice instead of the product name from parameter upsell.products.name.
Price per up-sell product item
It is used in up-sell offers and on checkout pages when calculating the product price
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
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.
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
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.
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.
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.
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.
Validity term of up-sell product initiating subscription (parent)
The fill-in instructions are the same as for parameter products.subscription.period.
The fill-in instructions are the same as for parameter products.subscription.period.
Renewal product (child) name extending up-sell product subscription
The fill-in instructions are the same as for parameter products.subscription.name.
The fill-in instructions are the same as for parameter products.subscription.name.
Price per renewal product item (child) extending up-sell product subscription
The fill-in instructions are the same as for parameter products.subscription.price.
The fill-in instructions are the same as for parameter products.subscription.price.
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 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.
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
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.
Referer7 value for orders containing up-sell products
- For the rules of usage, see the description of upsell.products.additional_data
- Must not exceed 255 characters
Referer8 value for orders containing up-sell products
- For the rules of usage, see the description of upsell.products.additional_data
- Must not exceed 255 characters
Referer9 value for orders containing up-sell products
- For the rules of usage, see the description of upsell.products.additional_data
- Must not exceed 255 characters
Referer10 value for orders containing up-sell products
- For the rules of usage, see the description of upsell.products.additional_data
- Must not exceed 255 characters
Referer11 value for orders containing up-sell products
- For the rules of usage, see the description of upsell.products.additional_data
- Must not exceed 255 characters
Referer12 value for orders containing up-sell products
- For the rules of usage, see the description of upsell.products.additional_data
- Must not exceed 255 characters
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:
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)
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.
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
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.
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.
Example of Error Response
{
"errors": [{
"error": 3010,
"message": "Invalid field value: currency."
}, {
"error": 3010,
"message": "Invalid field value: name."
}
]
}