GET
/
v2
/
subscriptions
/
{id}
Get subscription
curl --request GET \
  --url https://api.hyperline.co/v2/subscriptions/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "sub_B6ClkdqNqVNBgY",
  "name": "Yearly subscription",
  "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>",
  "transition_from_subscription_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": 123,
  "cancellation_reason": "<string>",
  "estimated_arr": 123,
  "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": 123,
  "renews_at": "2024-12-20T16:04:11Z",
  "current_phase_id": "<string>",
  "properties": {},
  "custom_properties": {},
  "generate_document": true,
  "document_name": "<string>",
  "add_tax_to_document": true,
  "created_at": "2024-10-12T07:00:01.860Z",
  "updated_at": "2024-10-12T07:00:01.860Z",
  "products": [
    {
      "id": "itm_FJKlqUb8COXw55",
      "name": "Product name",
      "description": "A description of the product.",
      "description_display_interval_dates": true,
      "attached_at": "2024-01-15T00:00:00Z",
      "detached_at": "2024-04-15T00:00:00Z",
      "current_period_started_at": "2024-01-15T00:00:00Z",
      "current_period_ends_at": "2024-02-15T00:00:00Z",
      "next_payment_at": "2024-02-15T00:00:00Z",
      "payment_interval": {
        "period": "months",
        "count": 1
      },
      "payment_schedule": "start",
      "type": "flat_fee",
      "count": 1,
      "prices": [
        {
          "type": "<any>",
          "id": "<any>",
          "amount": "<any>"
        }
      ]
    }
  ],
  "coupons": [
    {
      "description": "<string>",
      "expiration_date": "2023-11-07T05:31:56Z",
      "redemption_limit": 123,
      "created_at": "2024-12-20T16:04:11Z",
      "type": "amount",
      "discount_amount": 2000,
      "currency": "EUR",
      "id": "cou_DKL4Xcb5VSa8CQ",
      "promotion_code_id": "<string>",
      "name": "Partner discount",
      "subscription_coupon_id": "coos_d9pVekhjoGppuX",
      "repeat": "forever",
      "product_ids": [
        "itm_FJKlqUb8COXw55"
      ],
      "apply_at": "2023-11-07T05:31:56Z",
      "expires_at": "2023-11-07T05:31:56Z"
    }
  ],
  "phases": [
    {
      "id": "sup_1FoLfIQ5VOMbXf",
      "type": "standard",
      "status": "pending",
      "order": 0,
      "activation_strategy": "manual",
      "end_strategy": "duration",
      "duration": {
        "count": 1,
        "period": "years"
      },
      "billing_date_setting": "phase_start",
      "initial_billing_at": "2023-11-07T05:31:56Z",
      "starts_at": "2023-11-07T05:31:56Z",
      "ends_at": "2023-11-07T05:31:56Z",
      "billing_cycle_alignment": "anniversary",
      "do_not_invoice_phase": false,
      "transition_calculation_method": "prorata",
      "transition_invoicing_schedule": "immediately",
      "products": [
        {
          "id": "itm_FJKlqUb8COXw55",
          "name": "Product name",
          "description": "A description of the product.",
          "description_display_interval_dates": true,
          "attached_at": "2024-01-15T00:00:00Z",
          "detached_at": "2024-04-15T00:00:00Z",
          "current_period_started_at": "2024-01-15T00:00:00Z",
          "current_period_ends_at": "2024-02-15T00:00:00Z",
          "next_payment_at": "2024-02-15T00:00:00Z",
          "payment_interval": {
            "period": "months",
            "count": 1
          },
          "payment_schedule": "start",
          "type": "flat_fee",
          "count": 1,
          "prices": [
            {
              "type": "<any>",
              "id": "<any>",
              "amount": "<any>"
            }
          ]
        }
      ],
      "coupons": [
        {
          "description": "<string>",
          "expiration_date": "2023-11-07T05:31:56Z",
          "redemption_limit": 123,
          "created_at": "2024-12-20T16:04:11Z",
          "type": "amount",
          "discount_amount": 2000,
          "currency": "EUR",
          "id": "cou_DKL4Xcb5VSa8CQ",
          "promotion_code_id": "<string>",
          "name": "Partner discount",
          "subscription_coupon_id": "coos_d9pVekhjoGppuX",
          "repeat": "forever",
          "product_ids": [
            "itm_FJKlqUb8COXw55"
          ],
          "apply_at": "2023-11-07T05:31:56Z",
          "expires_at": "2023-11-07T05:31:56Z"
        }
      ],
      "created_at": "2024-10-12T07:00:01.860Z",
      "updated_at": "2024-10-12T07:00:01.860Z"
    }
  ],
  "quote": {
    "id": "quo_38YwqvItBH3d8a",
    "status": "signed"
  },
  "plan": {
    "id": "plan_zHmjoDee4ZRmQV",
    "name": "My example plan"
  },
  "checkout_session": {
    "id": "che_hEUPdVG7IgjpW1",
    "status": "opened",
    "available_payment_methods": [
      "card"
    ],
    "redirect_url": "https://app.hyperline.co/callback/checkout",
    "send_to": {
      "email": "josh@alpeak.com",
      "message": "<string>"
    },
    "url": "https://billing.hyperline.co/checkout/che_hEUPdVG7IgjpW1"
  },
  "payment_method_type": "card",
  "payment_method": {
    "id": "pm_1xMpj5bwRqN7LM",
    "status": "active",
    "type": "card",
    "last_4_digits": 2718,
    "expiration_date": "2027-11",
    "brand": "visa"
  },
  "generate_draft_invoices": true,
  "contract_terms": {
    "status": "active",
    "activation_strategy": "start_date",
    "end_strategy": "duration",
    "starts_at": "2024-12-31T23:00:00.000Z",
    "ends_at": "2025-06-30T21:59:59.999Z",
    "duration": {
      "count": 6,
      "period": "months"
    },
    "renew_automatically": true,
    "renew_for_duration": {
      "count": 1,
      "period": "years"
    },
    "current_period_started_at": "2025-06-30T22:00:00.000Z",
    "current_period_ends_at": "2026-06-30T21:59:59.999Z"
  },
  "live_billing": {
    "total_amount": 123,
    "total_discount": 123,
    "fixed_amount": 123,
    "billing_items": [
      {
        "id": "<string>",
        "total_amount": 123,
        "original_amount": 123,
        "discount_amount": 123,
        "item_name": "<string>",
        "tiers": [
          {
            "from": 123,
            "to": 123,
            "amount": 123,
            "total_amount": 123,
            "count": 123
          }
        ]
      }
    ],
    "coupons": [
      {
        "id": "<string>",
        "name": "<string>",
        "discount_amount": 123,
        "item_ids": [
          "<string>"
        ]
      }
    ]
  }
}

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
id
string
required

Query Parameters

​
include_live_billing
string

Response

​
id
string
required

Subscription ID.

Example:

"sub_B6ClkdqNqVNBgY"

​
name
string | null
required

Subscription custom name.

Example:

"Yearly subscription"

​
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
Example:

"EUR"

​
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
Example:

"active"

​
purchase_order
string | null
required

Reference to the purchase order.

​
customer_id
string
required

ID of the customer.

Example:

"cus_QalW2vTAdkR6IY"

​
plan_id
string | null
required

ID of the plan used to create the subscription.

Example:

"plan_zHmjoDee4ZRmQV"

​
invoicing_entity_id
string
required

ID of the invoicing entity attached to the subscription.

Example:

"ive_jerrb484RHn"

​
checkout_session_id
string | null
required

ID of the checkout session.

​
crm_opportunity_id
string | null
required

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

​
transition_from_subscription_id
string | null
required

ID of the subscription this subscription was transitioned from.

​
minimum_invoice_fee
number | null
required

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

Example:

250

​
commitment_interval
object | null
required
deprecated

Deprecated field, please use contract_terms.

Example:
{ "period": "years", "count": 1 }
​
renew_automatically
boolean
required

Deprecated field, please use contract_terms.

Example:

true

​
renew_for
object | null
required

Deprecated field, please use contract_terms.

Example:
{ "period": "years", "count": 1 }
​
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
Example:

"checkout"

​
starts_at
string<date-time>
required
deprecated

Applies only if the activation strategy is start_date. UTC date time string in the ISO 8601 format.

Example:

"2024-12-20T16:04:11Z"

​
contract_start
string<date-time>
required

Deprecated field, please use contract_terms.

Example:

"2024-01-15T00:00:00Z"

​
contract_end
string<date-time> | null
required

Deprecated field, please use contract_terms.

Example:

"2025-01-15T00:00:00Z"

​
initial_billing_at
string<date-time> | null
required

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

Example:

"2024-12-20T16:04:11Z"

​
paused_at
string<date-time> | null
required

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

Example:

"2024-12-20T16:04:11Z"

​
reactivate_at
string<date-time> | null
required

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

Example:

"2024-12-20T16:04:11Z"

​
cancel_at
string<date-time> | null
required

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

Example:

"2024-12-20T16:04:11Z"

​
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
​
cancellation_amount
number | null
required

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

​
cancellation_reason
string | null
required

Reason for the cancellation.

​
estimated_arr
number | null
required

Estimated Annual Recurring Revenue generated by the subscription.

​
current_period_started_at
string<date-time> | null
required

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

Example:

"2024-12-20T16:04:11Z"

​
current_period_ends_at
string<date-time> | null
required

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

Example:

"2024-12-20T16:04:11Z"

​
next_payment_at
string<date-time> | null
required

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

Example:

"2024-12-20T16:04:11Z"

​
next_payment_amount
number | null
required

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

​
renews_at
string<date-time> | null
required

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

Example:

"2024-12-20T16:04:11Z"

​
current_phase_id
string | null
required

ID of the current subscription phase.

​
properties
object | null
required

Key/value pairs to store any metadata useful in your context.

​
custom_properties
object | null
required

A list of key value with the slug of the custom property as the key and the custom property value as value.

​
generate_document
boolean
required

Generate documents instead of invoices for the subscription.

​
document_name
string | null
required

If generate_document is turned on, allows you to give a name to your document.

​
add_tax_to_document
boolean
required

If generate_document is turned on, will add taxes to document.

​
created_at
string<date-time>
required

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

Example:

"2024-10-12T07:00:01.860Z"

​
updated_at
string<date-time>
required

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

Example:

"2024-10-12T07:00:01.860Z"

​
products
object[]
required

Products that make up the subscription.

​
coupons
object[]
required

Coupons to be applied to the prices of subscription products.

​
phases
object[]
required

Phases of the subscription.

​
quote
object | null
required
​
plan
object | null
required
​
checkout_session
object | null
required

Checkout session of the subscription.

​
payment_method_type
enum<string> | null
required

Payment method type used to pay the subscription.

Available options:
card,
apple_pay,
google_pay,
direct_debit,
direct_debit_ach,
direct_debit_bacs,
stripe_link,
transfer,
transfer_automated,
external
​
payment_method
object | null
required

Default payment method of the customer. Only applies to card and direct debit. Payment method details used to pay the subscription.

​
generate_draft_invoices
boolean
required

Generate draft invoices for the subscription. Each invoice will need to be reviewed and validated manually before being sent

​
contract_terms
object | null
required

Contract terms linked to the subscription.

​
live_billing
object