Get subscriptions

GET

subscriptions

curl --request GET \
  --url https://api.hyperline.co/v2/subscriptions \
  --header 'Authorization: Bearer <token>'

{
  "meta": {
    "total": 1,
    "taken": 1,
    "skipped": 0
  },
  "data": [
    {
      "id": "sub_B6ClkdqNqVNBgY",
      "currency": "EUR",
      "status": "active",
      "purchase_order": "<string>",
      "customer_id": "cus_QalW2vTAdkR6IY",
      "plan_id": "plan_zHmjoDee4ZRmQV",
      "invoicing_entity_id": "ive_jerrb484RHn",
      "checkout_session_id": "<string>",
      "crm_opportunity_id": "<string>",
      "minimum_invoice_fee": 250,
      "commitment_interval": {
        "period": "years",
        "count": 1
      },
      "renew_automatically": true,
      "renew_for": {
        "period": "years",
        "count": 1
      },
      "activation_strategy": "checkout",
      "starts_at": "2024-12-20T16:04:11Z",
      "contract_start": "2024-01-15T00:00:00Z",
      "contract_end": "2025-01-15T00:00:00Z",
      "initial_billing_at": "2024-12-20T16:04:11Z",
      "paused_at": "2024-12-20T16:04:11Z",
      "reactivate_at": "2024-12-20T16:04:11Z",
      "cancel_at": "2024-12-20T16:04:11Z",
      "cancellation_strategy": "refund_prorata",
      "cancellation_amount": 24000,
      "estimated_arr": 24000,
      "current_period_started_at": "2024-12-20T16:04:11Z",
      "current_period_ends_at": "2024-12-20T16:04:11Z",
      "next_payment_at": "2024-12-20T16:04:11Z",
      "next_payment_amount": 24000,
      "renews_at": "2024-12-20T16:04:11Z",
      "current_phase_id": "<string>",
      "trial_ends_at": "2024-12-20T16:04:11Z",
      "properties": {},
      "custom_properties": {},
      "created_at": "2024-10-12T07:00:01.860Z",
      "updated_at": "2024-10-12T07:00:01.860Z"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

take

number | null

default:

Required range: 0 < x < 100

skip

number | null

default:

Required range: x > 0

status

Available options:

all,

inactive,

active,

errored,

cancelled,

paused,

pending,

draft,

voided

status__in

Available options:

all,

inactive,

active,

errored,

cancelled,

paused,

pending,

draft,

voided

status__notIn

Available options:

all,

inactive,

active,

errored,

cancelled,

paused,

pending,

draft,

voided

currency

string

currency__not

string

currency__isNull

string

currency__isNotNull

string

currency__equals

string

currency__contains

string

currency__startsWith

string

currency__endWith

string

plan_id

string

plan_id__not

string

plan_id__isNull

string

plan_id__isNotNull

string

plan_id__equals

string

plan_id__contains

string

plan_id__startsWith

string

plan_id__endWith

string

customer_id

string

customer_id__not

string

customer_id__isNull

string

customer_id__isNotNull

string

customer_id__equals

string

customer_id__contains

string

customer_id__startsWith

string

customer_id__endWith

string

invoicing_entity_id

string

invoicing_entity_id__not

string

invoicing_entity_id__isNull

string

invoicing_entity_id__isNotNull

string

invoicing_entity_id__equals

string

invoicing_entity_id__contains

string

invoicing_entity_id__startsWith

string

invoicing_entity_id__endWith

string

customer_external_id

string

updated_at

string

updated_at__not

string

updated_at__isNull

string

updated_at__isNotNull

string

updated_at__equals

string

updated_at__lt

string

updated_at__lte

string

updated_at__gt

string

updated_at__gte

string

Response

200 - application/json

meta

object

required

data

object[]

required

List of Subscription.

data.id

string

required

Subscription ID.

data.currency

enum<string>

required

Currency code. See ISO 4217.

Available options:

EUR,

AED,

AFN,

XCD,

ALL,

AMD,

AOA,

ARS,

USD,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

XOF,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BTN,

NOK,

BWP,

BYR,

BZD,

CAD,

CDF,

XAF,

CHF,

NZD,

CLP,

CNY,

COP,

CRC,

CUP,

CVE,

ANG,

CZK,

DJF,

DKK,

DOP,

DZD,

EGP,

MAD,

ERN,

ETB,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

IRR,

ISK,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KPW,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LYD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRO,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

XPF,

NGN,

NIO,

NPR,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SDG,

SEK,

SGD,

SHP,

SLL,

SOS,

SRD,

SSP,

STD,

SYP,

SZL,

THB,

TJS,

TMT,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

UYU,

UZS,

VEF,

VND,

VUV,

WST,

YER,

ZAR,

ZMW,

ZWL

data.status

enum<string>

required

Subscription status.

draft: The subscription is being created, this status is only used in the subscription assignation flow of the UI version of Hyperline.
pending: The subscription has been created and won't be charged until it is activated.
active: The subscription is running and will be invoiced at the next payment date.
paused: The subscription's payment collection is paused.
cancelled: The subscription has been canceled from an active state.
voided: The subscription has been voided directly from the pending state.
errored: We attempted 4 times (3 retries) and failed to charge a subscription's invoice, see Handling payment errors. We consider the subscription as inactive (as the customer failed to pay you) meaning that we won't invoice the customer in the future nor collect payment. You can choose to reactivate it manually.

Available options:

active,

cancelled,

draft,

errored,

paused,

pending,

voided

data.purchase_order

string | null

required

Reference to the purchase order.

data.customer_id

string

required

ID of the customer.

data.plan_id

string | null

required

ID of the plan used to create the subscription.

data.invoicing_entity_id

string

required

ID of the invoicing entity attached to the subscription.

data.checkout_session_id

string | null

required

ID of the checkout session.

data.crm_opportunity_id

string | null

required

ID of the related opportunity/deal in the connected CRM.

data.minimum_invoice_fee

number | null

required

Minimum fee applied to each invoice outside of one time payments.

data.commitment_interval

object | null

requireddeprecated

Use contract_start contract_end and renew_automatically instead. Interval previously used to represent the commitment period of the subscription.

data.renew_automatically

boolean

required

Indicates if the subscription should automatically renew.

data.renew_for

object | null

required

If renew_automatically is enabled, will renew the subscription for the given interval.

data.activation_strategy

enum<string> | null

required

Strategy used to activate the subscription.

start_date: The subscription will become active on the specified start date. If the start date is in the past, it will be activated immediately.
manually: The subscription requires activation through a manual action.
checkout: The subscription will be activated once the checkout is completed, but only if the start date is in the past. Otherwise, activation will occur later on the specified start date.
quote: The subscription will be activated depending on the configuration and the signature of the related quote.

Available options:

start_date,

manually,

checkout,

quote,

contract_start_date

data.starts_at

string

requireddeprecated

Deprecated field, please use contract_start.

data.contract_start

string

required

Subscription contract start date. UTC date time string in the ISO 8601 format.

data.contract_end

string | null

required

Subscription contract end date. UTC date time string in the ISO 8601 format.

data.initial_billing_at

string | null

required

Date when the subscription will start being billed. If not specified, it will correspond to the contract_start date. UTC date time string in the ISO 8601 format.

data.paused_at

string | null

required

Date when the subscription was paused. Only applies to paused status. UTC date time string in the ISO 8601 format.

data.reactivate_at

string | null

required

Date when the subscription will be automatically reactivated. UTC date time string in the ISO 8601 format.

data.cancel_at

string | null

required

Subscription cancel date. UTC date time string in the ISO 8601 format.

data.cancellation_strategy

enum<string> | null

required

Strategy used to cancel the subscription. If not specified do_nothing is used.

charge_prorata: Will charge the customer the unpaid amount for the prorated period up to the end of the current period.
charge_custom: Will charge the customer a custom amount.
refund_prorata: Will refund to the customer the overpaid subscription amount using prorated calculations on the cancellation date.
refund_custom: Will refund to the customer a custom amount.
end_of_period: Will cancel the subscription at the end date of the current billing period.
do_nothing: Will only cease the subscription without any additional actions.

Available options:

refund_prorata,

refund_custom,

charge_prorata,

charge_custom,

end_of_period,

do_nothing

data.cancellation_amount

number

required

Custom amount used when cancelling the subscription. Only applies to the charge_custom or the refund_custom cancellation strategy.

data.estimated_arr

number

required

Estimated Annual Recurring Revenue generated by the subscription.

data.current_period_started_at

string | null

required

Start date of the current billing period. UTC date time string in the ISO 8601 format.

data.current_period_ends_at

string | null

required

End date of the current billing period. UTC date time string in the ISO 8601 format.

data.next_payment_at

string | null

required

Date on which the next subscription payment will occur. UTC date time string in the ISO 8601 format.

data.next_payment_amount

number

required

The amount of the next subscription payment. The system will generate an invoice to pay on the next_payment_at.

data.renews_at

string | null

required

Next subscription commitment renewal date. UTC date time string in the ISO 8601 format.

data.current_phase_id

string | null

required

ID of the current subscription phase.

data.trial_ends_at

string | null

required

End date of the trial period. UTC date time string in the ISO 8601 format.

data.properties

object | null

required

Key/value pairs to store any information you find useful.

data.custom_properties

object | null

required

A list of key value with the ID or the name of the custom property as the key and the custom property value as value.

data.created_at

string

required

Subscription creation date. UTC date time string in the ISO 8601 format.

data.updated_at

string

required

Subscription last edition date. UTC date time string in the ISO 8601 format.

Was this page helpful?

Void quote Get subscription

curl --request GET \
  --url https://api.hyperline.co/v2/subscriptions \
  --header 'Authorization: Bearer <token>'

{
  "meta": {
    "total": 1,
    "taken": 1,
    "skipped": 0
  },
  "data": [
    {
      "id": "sub_B6ClkdqNqVNBgY",
      "currency": "EUR",
      "status": "active",
      "purchase_order": "<string>",
      "customer_id": "cus_QalW2vTAdkR6IY",
      "plan_id": "plan_zHmjoDee4ZRmQV",
      "invoicing_entity_id": "ive_jerrb484RHn",
      "checkout_session_id": "<string>",
      "crm_opportunity_id": "<string>",
      "minimum_invoice_fee": 250,
      "commitment_interval": {
        "period": "years",
        "count": 1
      },
      "renew_automatically": true,
      "renew_for": {
        "period": "years",
        "count": 1
      },
      "activation_strategy": "checkout",
      "starts_at": "2024-12-20T16:04:11Z",
      "contract_start": "2024-01-15T00:00:00Z",
      "contract_end": "2025-01-15T00:00:00Z",
      "initial_billing_at": "2024-12-20T16:04:11Z",
      "paused_at": "2024-12-20T16:04:11Z",
      "reactivate_at": "2024-12-20T16:04:11Z",
      "cancel_at": "2024-12-20T16:04:11Z",
      "cancellation_strategy": "refund_prorata",
      "cancellation_amount": 24000,
      "estimated_arr": 24000,
      "current_period_started_at": "2024-12-20T16:04:11Z",
      "current_period_ends_at": "2024-12-20T16:04:11Z",
      "next_payment_at": "2024-12-20T16:04:11Z",
      "next_payment_amount": 24000,
      "renews_at": "2024-12-20T16:04:11Z",
      "current_phase_id": "<string>",
      "trial_ends_at": "2024-12-20T16:04:11Z",
      "properties": {},
      "custom_properties": {},
      "created_at": "2024-10-12T07:00:01.860Z",
      "updated_at": "2024-10-12T07:00:01.860Z"
    }
  ]
}

API documentation

Integrations

Analytics

Billable events

Companies

Coupons

Custom properties

Customers

Customers > Credits

Customers > Payment methods

Integrations

Invoices

Invoicing entities

OAuth2

Organisations

Payments

Plans

Price configurations

Products

Quotes

Subscriptions

Taxes

Third-party apps

Wallets

Webhooks

Authorizations

Query Parameters

Response