[GET] Get subscription data

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

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:

• Webhook (subscription.id)

• Orders API request response

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

Additional Error Codes for HTTP 400

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

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"
  }
 ]
}

Noventiq Checkout