Contents

Get Subscription Data (AR/PMR)

GET /v1/subscription/[suscription id]

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

[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:
AuthorizationJWT
required
Authorization token.
  • Format: Bearer [token]
  • Where [token] is substituted by the token value obtained through the authentication API.
https://api.ecommerce.softline.com/v1/subscription/111111_22222

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.

If processing is successful, the following will return in response:

  • Server response code: HTTP/1.1 200 ОК.
  • Response body: subscription data in JSON format.
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 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.
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 validity period (Term).
  • 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.
Format: YYYY-MM-DDThh:mm:ss±hh:mm.
next_charge_date
string
required*
Renewal payment date of AR subscription (next recurring 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.

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).
{
 "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.softline.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"
}
{
 "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"
}

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. 
errors
array [objects]
required
Error list.
errors / [error object]
/
error
number
required
Error code.
errors / [error object]
/
message
string
required
Error description.
{
 "errors": [{
   "error": 7010,
   "message": "Subscription not found: 111111_22222"
  }
 ]
}