Knowledge Base
Noventiq Checkout
Up
Knowledge Base
Noventiq CheckoutIntegrationSubscriptions API
[GET] Get Subscription Data

[GET] Get Subscription Data (AR/PMR)

Request Description

GET /v1/subscription/[suscription id]

The request allows you to get the data of the subscriptions existing in the customer’s order (AR, PMR).

Connection Data

Path Parameters

[suscription id]
required
Subscription identifier
Format: NN_MM, where NN is an identifier of the order that initiates subscriptions (parent order).
You can get it from:

Header Parameters

AuthorizationJWT
required
Authorization token
  • Format: Bearer [token]
  • Where [token] is substituted by the token value obtained through the authentication API

Request Example

https://api.ecommerce.noventiq.com/v1/subscription/111111_22222

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 ОК.
  • Response body: subscription data in JSON format.

Body Parameters

id
string
required
Subscription identifier
type
string
required
Subscription type
Value options:
  • AR - auto-renewable subscription (including AR Trial)
  • PMR - pre-filled manual renewal
More details оn subscription types.
status
string
required
Subscription status
Value options:
  • active - subscription is in progress and requires no payment
  • not paid - subscription is payment pending
  • cancelled - renewal is cancelle.
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.
initial_order
object
required
Subscription-initiator order data
The product of this order initiates a subscription (parent order).
initial_order
/
order_id
number
required
Parent order identifier
initial_order
/
create_date
string
required
Date and time of the parent order payment

Format: YYYY-MM-DDThh:mm:ss±hh:mm.
url
string
required*
Link to manage auto-renewable subscriptions (AR, AR Trial)
This anchor link leads to he subscription section within the subscription order initiator page.

* - Required, if the type parameter is equal to AR. Otherwise, the parameter is not transferred.
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.

Example:
  • A subscription for the product having a 7-day term has been created:
    • The response to the request will contain period = P7D
  • A child order for the product having a 1-month term has been created:
    • The response to the request will contain 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:
    • The response to the request will contain period = P1M since the child order has been paid for, the subscription has been extended and the current subscription period has been updated
Format:
  • ISO 8601 code - P[number][unit of measurement]
  • Units of measurement supported: Y - year, M - month, D - day.
    Example: "P1Y" - "1-year" validity period
expiration_date
string
required
Subscription expiration date
Learn more about expiration date.

Format: YYYY-MM-DDThh:mm:ss±hh:mm.
next_charge_date
string
required*
Renewal payment date
Next recurring payment date for AR, AR Trial subscription. Learn more about renewal payment date.
  • * - Required, if the type parameter is equal to AR. Otherwise, the parameter is not transferred
  • Format: YYYY-MM-DDThh:mm:ss±hh:mm
next_notification_date
string
required
Renewal reminder date
The email containing the reminder on the upcoming payment for a renewal is sent to the customer on this date. The date matches the date of the next child order creation. Learn more about renewal reminder date.

Format: YYYY-MM-DDThh:mm:ss±hh:mm.

Please note: If the date comes, but no renewal order is created for any reason, then every subsequent day another attempt is made to create a renewal order - 6 attempts in total. In this case, the date transferred in this parameter does not change during the retries.
currency
string
required
Currency code of renewal price (it is the same as the currency code of the order for the subscription-initiator product). The currency cannot be changed during the subscription lifetime.
  • Format: ISO 4217 alpha-3, 3 characters
  • For the value options, see the reference guide
current_price
string
required
Current subscription price
The customer pays this amount for a current valid subscription (incl. product quantity, VAT, discount). If the current validity period of the subscription ends and no renewal is paid, the price paid for the last validity period (term) is transferred here.

Format: String contains numerals; value separating by point, with two decimal places.
next_billing_price
string
required
Next subscription price
The customer has to pay this amount for a renewal (incl. product quantity, VAT, discount) to extend the subscription validity period (term).

Format: String contains numerals; value separating by point, with two decimal places.
next_product_name
string
required
Next renewal product name
The name of the next product that extends the customer’s subscription for another validity period (term).

Example of Successful Response for AR Subscriptions

{
 "id": "111111_22222",
 "type": "AR",
 "status": "active",
 "initial_order": {
  "order_id": 111111,
  "create_date": "2021-08-13T09:16:35+03:00"
 },
 "url": "https://demo.checkout.noventiq.com/order/status/111111/fb61abcba997a5da0a627535a5879ab5#autorenewal",
 "period": "P1Y",
 "expiration_date": "2022-08-13T23:59:00+03:00",
 "next_charge_date": "2022-08-05T09:25:00+03:00",
 "next_notification_date": "2022-08-01T09:25:00+03:00",
 "currency": "USD",
 "current_price": "99.99",
 "next_billing_price": "80.00",
 "next_product_name": "Product renewal for 1 year"
}

Example of Successful Response for PMR Subscriptions

{
 "id": "111111_22222",
 "type": "PMR",
 "status": "active",
 "initial_order": {
  "order_id": 111111,
  "create_date": "2021-08-13T09:16:35+03:00"
 },
 "period": "P1Y",
 "expiration_date": "2022-08-13T23:59:00+03:00",
 "next_notification_date": "2022-08-01T09:25:00+03:00",
 "currency": "USD",
 "current_price": "99.99",
 "next_billing_price": "80.00",
 "next_product_name": "Product renewal for 1 year"
}

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 subscription having the identifier transferred is found. If no subscription 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
If at least one error from the list below is found, then it returns in response to a request, other errors are not validated.
7000 No access to subscription management. Please contact technical support. During processing, we could not identify your account setting unambiguously. Please contact support team.
7010 Invalid field value: [parametr name] The request is not valid, e.g., the required parameter is not filled out, the parameter name is incorrect, the parameter 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 parameter, and this value option is not set as valid in the parameter description.

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
If at least one error from the list below is found, then request validation is not interrupted. Several errors may return in response.
7400 Subscription not found. No subscription 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
required
Error description.

Example of Error Response

{
 "errors": [{
   "error": 7010,
   "message": "Subscription not found: 111111_22222"
  }
 ]
}
Terms & Conditions
© 2024 Noventiq