[GET] Get order data

Request description

CODE

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

Endpoint URL:
- Production environment: https://api.ecommerce.noventiq.com/v1/order
- Test environment: https://api.ecommerce.noventiq.com.demonqweb.com/v1/order
Request Method: GET
Authorization: token-based

URL Parameters

[order id]

required

Order identifier (Order ID)

You can get it from:

Webhooks (order_id)
Response to a request for getting a list of orders (ids)
Requests for getting product licenses

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

CODE

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:

Order data
Payment data
Customer data
Product data, including:
- (Optional) Subscription data
- (Optional) Installment data
- (Optional) Refund data
(Optional) Order additional parameters

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

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

true - bank card expires before subscription does (payment.card_expiration_date < subscription.expiration_date).
For example:
- Card expiration date (payment.card_expiration_date) = 09/2026 (i.e. card is valid until 30.09.2026)
- Subscription expiration date (subscription.expiration_date) = 15.10.2026
- Since Card expiration date < Subscription expiration date, then subscription.is_card_expired transfers true
false - bank card expires after subscription does (payment.card_expiration_date ≥ subscription.expiration_date)
For example:
- Card expiration date (payment.card_expiration_date) = 10/2026 (i.e. card is valid until 31.10.2026)
- Subscription expiration date (subscription.expiration_date) = 15.10.2026
- Since Card expiration date > Subscription expiration date, then subscription.is_card_expired transfers false

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.

* - Required, if payment.is_installment_payment is true, otherwise, it is not transferred
Always equals the value of the currency parameter

(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

* - Required, if the products.subscription parameter is transferred
Format: YYYY-MM-DDThh:mm:ss±hh:mm

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.

* - Required, if the products.subscription parameter was transferred and the subscription.type parameter equals AR
Format: YYYY-MM-DDThh:mm:ss±hh:mm

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

CODE

{
  "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

CODE

{
  "errors": [{
      "error": 15020,
      "message": "Order not found."
    }
  ]
}

Noventiq Checkout

Support	merchants.help@noventiq.com
Our resources	https://ecommerce.noventiq.com/