Knowledge Base
Noventiq Checkout
Up
Knowledge Base
Noventiq CheckoutIntegrationOrders API
[GET] Get Order Data

[GET] Get Order Data

Request description

GET /v1/order/[order id]

The request allows you to get order data.

This request can also be used to get payment data created via Noventiq Payments. 

Connection Data

URL Parameters

[order id]
required
Order identifier (Order ID)

You can get it from: Example: /v1/order/123456

Header Parameters

AuthorizationJWT
required
Authorization token
  • Format: Bearer [token]
  • Replace [token] with the token value you get in response to the request sent to the Authentication API

Request Example

GET https://api.ecommerce.noventiq.com/v1/order/123456

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 OК and the order data  in JSON format.

Response contains:

Body Parameters

order_id
number
required
Order identifier (Order ID)

(For payments in Noventiq Payments) Payment identifier
order_name
string
required
Extended order identifier
In such a format prefixes can be added to identifiers. For orders in Noventiq Checkout - this is the way order numbers are viewed by customers.

(For payments in Noventiq Payments) Extended payment identifier
status
string
required
Order status
More details on order statuses.

Value options:
  • not paid
  • paid
  • deleted
(For payments in Noventiq Payments) Payment status
external_id
string
Checkout page identifier
It is used if an order for a product with dynamic characteristics has been placed. You receive this identifier in response to the request used for generating a buy link to purchase a product with dynamic characteristics (buy_link). Otherwise, the parameter is transferred having an empty value ("").

(For payments in Noventiq Payments) Payment identifiers on your end
create_date
string
required
Order creation date
Format: YYYY-MM-DDThh:mm:ss±hh:mm.

(For payments in Noventiq Payments) Payment creation date
pay_date
string
Date and time of successful order payment completion
  • Format: YYYY-MM-DDThh:mm:ss±hh:mm
  • If no payment has been made, the parameter is transferred having an empty value ("")
(For payments in Noventiq Payments) Date and time of successful payment completion
currency
string
required
Currency code of order
  • Format: ISO 4217 alpha-3, 3 characters.
  • For the value options, see the reference guide.
(For payments in Noventiq Payments) Currency code of payment
order_detail_url
string
required
Link leading to the order page
When creating orders in the test environment - links will be intended for the test environment (links will have the .demoslweb.com suffix added).

(For payments in Noventiq Payments) Link leading to the payment form page
total_discount_amount
string
required
Total discount amount for all order items
  • Transferred in order currency
  • Calculated from price excluding VAT
  • Product quantity is included
  • Format: Number with 2 decimals, separator - dot, transferred as string
  • If no discount is applied to order products, parameter is transferred with value "0.00"
(For payments in Noventiq Payments) Not used, parameter is transferred with value (0.00).
total_vat_amount
string
required
TTotal VAT amount for all order items
  • Transferred in order currency
  • Product quantity is included
  • Format: Number with 2 decimals, separator - dot, transferred as string
  • If VAT percentage is equal to zero for all order products, parameter is transferred with value "0.00"
(For payments in Noventiq Payments) VAT amount
total_amount
string
required
Total order price amount
  • Transferred in order currency
  • Product quantity, discounts, VAT are included
  • Format: Number with 2 decimals, separator - dot, transferred as string
(For payments in Noventiq Payments) Payment amount including VAT
payment
object
required
Payment data
payment
/
payment_method
string
required
Payment method code
For the value options, see the reference guide.
payment
/
payment_system_name
string
required
Payment method name
This name is seen by customers on the checkout page when they place an order.
payment
/
card_last_4
string
Last 4 digits of card number

The value can be transferred if:
  • The customer has paid for their order with a card.
  • The order was created to renew an AR subscription (child) but the customer has not paid for it yet. In this case, the parameter value is taken from the parent order if it was paid with a card.
Otherwise, the parameter is transferred with an empty value (null).
payment
/
card_expiration_date
string
Card expiration date

The value can be transferred if:
  • The customer has paid for their order with a card.
  • The order was created to renew an AR subscription (child) but the customer has not paid for it yet. In this case, the parameter value is taken from the parent order if it was paid with a card.
  • Format: MM/YYYY. Example: 12/2026.
Otherwise, the parameter is transferred with an empty value ("").
payment
/
is_card_expired
boolean
Attribute indicating whether card expires before subscription expiration date.
The value can be transferred if:
  • The order contains a subscription (AR or PMR).
  • A card is used for payment and its expiration date is set (the payment.card_expiration_date parameter was transferred). If the order was created to renew a subscription (child order) and the customer has not paid for it yet, the parameter value is taken from the parent order.
The current subscription status does not affect the parameter.

Value options:
payment
/
is_installment_payment
boolean
required
Installment payment availability
More details on payment in installments. This parameter and all the other ones concerning installment payment include only the installments of Noventiq Checkout (installments of PSP are not included).

Value options:
  • true - no installments (one-time payment)
  • false - installments
(For payments in Noventiq Payments) It is not applicable
payment
/
installment_amount
string
required*
One installment amount.
  • * - Required, if payment.is_installment_payment is true, otherwise, it is not transferred
  • Format: Numeral with 2 decimal places, separator - point. Transferred as a string
  • The amount of the last installment may slightly differ from the remaining installment amounts
(For payments in Noventiq Payments) It is not applicable
payment
/
installment_currency
string
required*
Currency code of one installment payment amount.
(For payments in Noventiq Payments) It is not applicable
payment
/
installment_choice
number
required*
Number of installments

* - Required, if payment.is_installment_payment is true, otherwise, it is not transferred.

(For payments in Noventiq Payments) It is not applicable
customer
object
required
Customer data
customer
/
country
string
required
Customer's country code
  • Format: ISO 3166-1 alpha-2
  • For the value options, see the reference guide
customer
/
type
string
required
Customer type
Value options:
  • physical - individuals
  • juridical - companies
customer
/
email
string
required
Customer's email
customer
/
first_name
string
required
Customer's name
customer
/
last_name
string
required
Customer's last name
customer
/
phone
string
Customer's phone number

If the parameter contains no value on our end, it is transferred empty ("").
customer
/
vat_number
string
Taxpayer identification number
E.g., it is used to transfer:
  • DNI/CUIL or CUIT when payments are made in Argentine pesos
If the parameter contains no value on our end, it is transferred empty ("").
customer
/
company_name
string
Company name

If the parameter contains no value on our end, it is transferred empty ("").
customer
/
company_billing_address
string
Company's registered office address

If the parameter contains no value on our end, it is transferred empty ("").
customer
/
company_delivery_address
string
Company’s physical address

If the parameter contains no value on our end, it is transferred empty ("").
products
array [objects]
required
List of order products

(For payments in Noventiq Payments) Additional payment data
products / [object]
/
id
number
required
Product identifier

(For payments in Noventiq Payments) Technical values
products / [object]
/
vendor_code
string
Your product identifier

If the parameter contains no value on our end, it is transferred empty ("").

(For payments in Noventiq Payments) Technical values
products / [object]
/
sku
string
Your product SKU

If the parameter contains no value on our end, it is transferred empty ("").

(For payments in Noventiq Payments) Technical values
products / [object]
/
business_segment
string
Product sales business segment
Value options:
  • b2c - product is intended for individuals
  • b2b - product is intended for legal entities
  • mobile - mobile app
If the parameter contains no value on our end, it is transferred empty ("").

(For payments in Noventiq Payments) Technical values
products / [object]
/
name
string
required
Full names of products

(For payments in Noventiq Payments) Payment descriptions
products / [object]
/
price
string
required
Price per product unit
  • Transferred in order currency
  • No discount or VAT are included
  • Format: Number with 2 decimals, separator - dot, transferred as string
(For payments in Noventiq Payments) Payment amount excluding VAT
products / [object]
/
quantity
number
required
Product unit quantities

(For payments in Noventiq Payments) "1" is always transferred
products / [object]
/
discount_percent
string
Product discount percentage
If no discount is applied to product, parameter is transferred with empty value ("").

(For payments in Noventiq Payments) Parameter is not used. It is transferred with empty value ("").
products / [object]
/
discount_amount
string
Discount amount
  • Transferred in order currency
  • Calculated from price excluding VAT
  • Product quantity is included
  • Format: Number with 2 decimals, separator - dot, transferred as string
  • If no discount is applied to order products, parameter is transferred with empty value ""
(For payments in Noventiq Payments) It is not applicable.
products / [object]
/
vat_percent
string
required
VAT percentage
products / [object]
/
vat_amount
string
required
VAT amount
  • Transferred in order currency
  • Product quantity is included
  • Format: Number with 2 decimals, separator - dot, transferred as string
  • If VAT percentage is equal to zero, parameter is transferred with value "0.00"
products / [object]
/
amount
string
required
Product total price
  • Transferred in order currency
  • Product quantity, VAT, discount are included
  • Format: Number with 2 decimals, separator - dot, transferred as string
(For payments in Noventiq Payments) Payment amount including VAT, same value as in total_amount
products / [object]
/
margin
string
required
You profit margin from sales in order currency

Format: String contains numerals; value separating by point, with two decimal places.
products / [object]
/
activation_codes
array [strings]
Product license information, sent to customers
The parameter is transferred if a product exploits the Noventiq automatic fulfillment tools (electronic delivery option) to send its license information, or the license information of the product has already been sent and the data has been saved in Noventiq.

(For payments in Noventiq Payments) It is not applicable
products / [object]
/
subscription
object
Subscription data
This parameter is transferred if a subscription exists for a product: automatic renewal (AR / AR Trial) or pre-filled manual renewal (PMR).

Note that:
  • The subscription is created after the customer has paid for the initiating order. Therefore, if the customer gives their consent to the subscription, but has not yet paid for the order, the parameter does not exist
  • The parameter is always present in renewal orders (child orders)
Parameter is not used for Noventiq Payments.
products / [object] / subscription
/
id
string
required*
Subscription identifier
  • * - Required, if the products.subscription parameter is transferred
  • Format: NN_MM, where NN is an identifier of the order that initiates subscriptions (parent order)
products / [object] / subscription
/
previous_order_id
number
required*
ID of previous order within subscription
  • If a current order is a parent one and initiates a subscription, the parameter is transferred having value "null"
  • If a current order is a child one, this parameter transfers the identifier of a previous child order (or the identifier of a parent order in case it is the first renewal)
  • * - Required, if the products.subscription parameter was transferred
products / [object] / subscription
/
previous_order_item_id
number
required*
Order item ID of previous order within subscription
Order item ID is an additional internal ID that is assigned to a product within an order.
  • If the current order is a parent order (initiates the subscription), the parameter is transferred having an empty value (null)
  • If the current order is a child order, the parameter transfers the order item ID assigned to the product of the previous order created within the subscription
* - Required, if the subscription parameter was transferred.

Example:
  • A product being from a parent order triggers creation of a subscription. This product ID is 11111:
    • Order item ID 12345 gets assigned to the product within the order
    • Request response contains: "subscription.previous_order_item_id":null
  • During the first subscription renewal, a renewal order is created:
    • Product having ID 22222 is used to renew the subscription
    • Order item ID 54321 gets assigned to the product within this
    • Request response contains: "subscription.previous_order_item_id":12345
products / [object] / subscription
/
type
string
required*
Subscription type

* - Required, if the products.subscription parameter is transferred.

Value options:
  • AR - auto-renewable subscription (including AR Trial).
  • PMR - pre-filled manual renewal.
More details on subscription types.
products / [object] / subscription
/
is_conversion_from_trial
boolean
required*
Attribute indicating first renewal after free trial period
It indicates whether the order on which you received a webhook had been created or not to renew a subscription immediately after its free trial period expiration.

* - Required, if the products.subscription parameter is transferred.

Value options:
  • true - if all the conditions are met:
    • The order renews an AR subscription. (The order is a child order. The subscription.type parameter equals AR)
    • This is the first child order of this subscription
    • The subscription has a free trial period. (The customer purchased the parent product free of charge)
  • false - if the conditions for transferring true are not met.
products / [object] / subscription
/
status
string
required*
Subscription status

* - Required, if the products.subscription parameter is transferred.

Value options:
  • active - subscription is in progress and requires no payment
  • not paid - subscription is payment pending
  • cancelled - renewal is cancelled
More details on the statuses of auto-renewable subscriptions (AR). Pre-filled manual renewal (PMR) subscriptions exploit the same statuses, however, the following options are not available: subscription cancellation or subscription restoration.
products / [object] / subscription
/
period
string
required*
Product term within current subscription period
This is the validity period of the product from the last paid order created as part of the subscription. Please note that this period applies to the subscription as the whole and may not coincide with the term of the product in the order from the response to the request.

Example:
  • A subscription for the product having a 7-day term has been created:
    • When requesting data on the parent order, the response will contain products.subscription.period = P7D
  • A child order for the product having a 1-month term has been created:
    • When requesting data for both the child order and the parent order, the response will contain products.subscription.period = P7D. Since the child order has not yet been paid for and the subscription has not yet been renewed, the term from the current subscription period is transferred
  • A payment for the child order has been made:
    • When requesting data for both the child order and the parent order, the response will contain products.subscription.period = P1M since the child order has been paid for, the subscription has been extended and the current subscription period has been updated
Format:
  • * - Required, if the products.subscription parameter is transferred
  • ISO 8601 code: P[number][unit of measurement]
  • Supported units: Y - year, M - month, D - day
  • Example: "P1Y" matches "1 year"
products / [object] / subscription
/
expiration_date
string
required*
Subscription expiration date
products / [object] / subscription
/
next_charge_date
string
required*
Date of next attempt to pay for AR subscription
Only the date of the first payment attempt is transferred. The system ignores additional attempts in case of unsuccessful payment. If the date comes but the attempt is unsuccessful, or the system runs out of all the attempts to pay for a subscription (the subscription has not been renewed), the data transferred does not change. The system calculates a new date to pay for the next renewal after successful payment.
products / [object] / subscription
/
detail_url
string
required*
Link to manage auto-renewable subscriptions (AR, AR Trial)
This anchor link leads to the subscription section within the subscription order initiator page.

* -Required, if the products.subscription parameter is transferred, and the products.subscription.type parameter is equal to AR. Otherwise, the parameter is not transferred.

Note:
  • If the current order initiates the subscription, parameters order_detail_url and products.subscription.detail_url will contain the link leading to the same page
  • If the current order (child) renews the subscription, the url in order_detail_url leads to the order page of the renewal (current order), and the url in products.subscription.detail_url leads to the order page of the subscription initiator
  • If the order is created in the test environment, the link is intended for the test environment (link uses suffix .demoslweb.com)
products / [object]
/
return
object
Refund / return data
The parameter is transferred if a refund or a return is made. Otherwise, it is not transferred.
products / [object] / return
/
type
string
required*
Action type

* - Required, if the products.return parameter is transferred.

Value options:
  • returned - refund or replacement of license information
  • removed - removal of incorrect license information, e.g., when the customer receives invalid data instead of license information because of technical issues
products / [object] / return
/
date
required*
Date and time of event
  • * - Required, if the products.return parameter is transferred
  • Format: YYYY-MM-DDThh:mm:ss±hh:mm
products / [object] / return
/
reason
string
required*
Reason description for event

* - Required, if the products.return parameter is transferred.
additional_data
array [objects]
Additional parameters
More details on additional parameters. Please note that the time for storing additional parameters in orders is limited.

(For payments in Noventiq Payments) Values of the additional_data parameter in the payment creation request
additional_data / [object]
/
name
string
required*
Parameter name

* - Required, if the additional_data parameter is transferred.
additional_data / [object]
/
value
string
required*
Parameter value

* - Required, if the additional_data parameter is transferred.

Successful Response

{
  "order_id": 6666666,
  "order_name": "A0006666666",
  "status": "paid",
  "external_id": "TEST12025",
  "create_date": "2021-08-13T09:16:35+03:00",
  "pay_date": "2021-08-13T09:20:05+03:00",
  "currency": "EUR",
  "locale": "en_EN",
  "order_detail_url": "https://shop.com/order/status/6666666/1a97507",
  "total_discount_amount": "0.0",
  "total_vat_amount": "0.00",
  "total_amount": "200.00",
  "payment": {
    "payment_method": "CreditCard",
    "payment_system_name": "Bank Card",
    "card_last_4": "1234",
    "card_expiration_date": "12/2026",
    "is_card_expired": false,
    "is_installment_payment": false
  },
  "customer": {
    "country": "FR",
    "type": "physical",
    "email": "customer@gmail.com",
    "first_name": "Marcel",
    "last_name": "Laporte",
    "phone": "",
    "vat_number": "",
    "company_name": "",
    "company_billing_address": "",
    "company_delivery_address": ""
  },
  "products": [
    {
      "id": 111111,
      "vendor_code": "0001",
      "sku": "0001",
      "business_segment": "b2c",
      "name": "Demo",
      "price": "100.00",
      "quantity": 1,
      "discount_percent": "",
      "discount_amount": "",
      "vat_amount": "0.00",
      "amount": "100.00",
      "margin": "95.00",
      "activation_codes": [
        "XXX-XXX-YYYY"
      ],
      "subscription": {
        "id": "6666666_456660",
        "previous_order_id": null,
        "previous_order_item_id": null,
        "type": "AR",
        "status": "cancelled",
        "period": "P1Y",
        "expiration_date": "2022-08-13T23:59:00+03:00",
        "next_charge_date": "2022-07-24T23:59:00+03:00",
        "detail_url": "https://shop.com/order/status/6666666/1a97507#autorenewal"
      },
      "return": {
        "type": "returned",
        "reason": "test purchase",
        "date": "2022-08-14T09:16:35+03:00"
      }
    },
    {
      "id": 22222,
      "vendor_code": "0002",
      "sku": "0002",
      "business_segment": "b2c",
      "name": "Demo 2",
      "price": "100.00",
      "quantity": 1,
      "discount_percent": "",
      "discount_amount": "",
      "vat_amount": "0.00",
      "amount": "100.00",
      "margin": "95.00",
      "activation_codes": [
        "XXX-XXX-YYYY"
      ]
    }
  ],
  "additional_data": [
    {
      "name": "referer2",
      "value": "test"
    },
    {
      "name": "referer3",
      "value": "TEST12025"
    }
  ]
}

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 or no order having the identifier transferred is found. If no order is found, an additional additional error code will return in the response body. 
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
15000 Unable to identify your configuration for accessing this API. Please contact technical support. During processing, we could not identify your account setting unambiguously. Please contact support team.

Additional Error Codes for HTTP 401

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

Additional Error Codes for HTTP 404

Error Message Description
15020 Order not found. No order with the identifier transferred is found, or you do not have the rights to get the data. 

Body Parameters

errors
array [objects]
required
Error list
errors / [error object]
/
error
number
required
Error code
errors / [error object]
/
message
string
Error description

Example of Error Response

{
  "errors": [{
      "error": 15020,
      "message": "Order not found."
    }
  ]
}
Terms & Conditions
© 2024 Noventiq