[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
- Endpoint URL:
- Production environment: https://api.ecommerce.noventiq.com/v1/subscription
- Test environment: https://api.ecommerce.noventiq.com.demonqweb.com/v1/subscription
- Request Method: GET
- Authorization: token-based
Subscription identifier
Format: NN_MM, where NN is an identifier of the order that initiates subscriptions (parent order).
You can get it from:
Format: NN_MM, where NN is an identifier of the order that initiates subscriptions (parent order).
You can get it from:
- Webhook (subscription.id)
- Orders API request response
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_22222Response 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.
Subscription type
Value options:
Value options:
- AR - auto-renewable subscription (including AR Trial)
- PMR - pre-filled manual renewal
Subscription status
Value options:
Pre-filled manual renewal (PMR) subscriptions exploit the same statuses, however, the following options are not available: subscription cancellation or subscription restoration.
Value options:
- active - subscription is in progress and requires no payment
- not paid - subscription is payment pending
- cancelled - renewal is cancelle.
Pre-filled manual renewal (PMR) subscriptions exploit the same statuses, however, the following options are not available: subscription cancellation or subscription restoration.
Subscription-initiator order data
The product of this order initiates a subscription (parent order).
The product of this order initiates a subscription (parent order).
Date and time of the parent order payment
Format: YYYY-MM-DDThh:mm:ss±hh:mm.
Format: YYYY-MM-DDThh:mm:ss±hh:mm.
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.
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.
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:
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
- ISO 8601 code - P[number][unit of measurement]
- Units of measurement supported: Y - year, M - month, D - day.
Example: "P1Y" - "1-year" validity period
Renewal payment date
Next recurring payment date for AR, AR Trial subscription. Learn more about 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
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.
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 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 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.
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 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.
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.
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. |
Example of Error Response
{
"errors": [{
"error": 7010,
"message": "Subscription not found: 111111_22222"
}
]
}