Get subscription phases

GET

subscriptions

{id}

phases

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

{
  "meta": {
    "total": 1,
    "taken": 1,
    "skipped": 0
  },
  "data": [
    {
      "id": "sup_1FoLfIQ5VOMbXf",
      "type": "standard",
      "status": "active",
      "order": 0,
      "activation_strategy": "manual",
      "end_strategy": "duration",
      "duration": {
        "count": 1,
        "period": "years"
      },
      "billing_date_setting": "phase_start",
      "initial_billing_at": "2024-10-13T02:00:00.000Z",
      "starts_at": "2024-10-13T02:00:00.000Z",
      "ends_at": "2024-10-13T02:00:00.000Z",
      "billing_cycle_alignment": "calendar_period",
      "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": "fee",
              "id": "<string>",
              "amount": 24000
            }
          ]
        }
      ],
      "coupons": [
        {
          "description": "<string>",
          "expiration_date": "2024-10-13T02:00:00.000Z",
          "redemption_limit": 123,
          "created_at": "2024-12-20T16:04:11Z",
          "type": "amount",
          "discount_amount": 2000,
          "currency": "EUR",
          "id": "cou_DKL4Xcb5VSa8CQ",
          "name": "Partner discount",
          "subscription_coupon_id": "coos_d9pVekhjoGppuX",
          "repeat": "forever",
          "product_ids": [
            "itm_FJKlqUb8COXw55"
          ],
          "apply_at": "2024-10-13T02:00:00.000Z",
          "expires_at": "2024-10-13T02:00:00.000Z"
        }
      ],
      "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.

Path Parameters

string

required

Response

200

application/json

meta

object

required

data

object[]

required

List of SubscriptionPhase.

data.id

string

required

Subscription phase ID.

Example:

"sup_1FoLfIQ5VOMbXf"

data.type

enum<string>

required

Type of subscription phase.

setup: The phase represents a non-recurring service setup period, often used before the actual recurring subscription begins.
trial: The phase represents a non-recurring trial period, often used to allow users to opt out or experience a free test.
standard: The phase represents a standard recurring billing.

Available options:

setup,

trial,

standard

Example:

"standard"

data.status

enum<string>

required

Status of subscription phase.

pending: The phase is waiting to start (not started yet).
active: The phase is currently in progress.
finished: The phase has ended and is complete.

Available options:

pending,

active,

finished

Example:

"active"

data.order

number

required

Order in which the phase is executed within all subscription phases.

Example:

0

data.activation_strategy

enum<string>

required

Activation strategy of subscription phase.

immediately: The phase starts as soon as the subscription is activated.
manual: The phase starts when a user manually activates it.
start_date: The phase starts on a specified date.
quote_signature: The phase starts when the subscription quote is signed.
checkout: The phase starts when the subscription checkout is completed.
contract_start_date: The phase starts on the start date of the related subscription contract.
previous_phase_end: The phase starts when the previous phase ends.

Available options:

immediately,

manual,

start_date,

quote_signature,

checkout,

contract_start_date,

previous_phase_end

Example:

"manual"

data.end_strategy

enum<string>

required

End strategy of subscription phase.

manual: The phase ends when a user manually stops it.
end_date: The phase ends on a specified date.
duration: The phase ends after a specific relative duration.
contract_end_date: The phase ends on the end date of the related subscription contract.

Available options:

manual,

end_date,

duration,

contract_end_date

Example:

"duration"

data.duration

object | null

required

Interval over which the subscription phase spans. Only applies to duration end strategy.

Example:

{ "count": 1, "period": "years" }

data.billing_date_setting

enum<string>

required

Represents when the first billing date occurs.

phase_start: Aligns with the start of the phase.
specific_date: Occurs on a specified date.

Available options:

phase_start,

specific_date

Example:

"phase_start"

data.initial_billing_at

string | null

required

Date when the subscription phase will start being billed. Only applies to specific_date billing date setting. UTC date time string in the ISO 8601 format.

Example:

"2024-10-13T02:00:00.000Z"

data.starts_at

string | null

required

Actual start date of the phase. UTC date time string in the ISO 8601 format.

Example:

"2024-10-13T02:00:00.000Z"

data.ends_at

string | null

required

Actual end date of the phase. UTC date time string in the ISO 8601 format.

Example:

"2024-10-13T02:00:00.000Z"

data.billing_cycle_alignment

enum<string>

required

Alignment of product billing cycles.

calendar_period: The billing cycles of the products will be aligned on the calendar period, after the first period which will be invoiced taking into account the prorata of the first cycle compared to the product periodicity.
anniversary: The billing cycles of the products will be aligned on the anniversary of the phase initial billing date.

Available options:

calendar_period,

anniversary

data.transition_calculation_method

enum<string>

required

Calculation method used when transitioning from one phase to the next one.

prorata: The prorated amount between the two phases relative to the end date (the transition date) must be paid.
pay_in_full: The full amount for the phase billing period must be paid.
none: No amount will need to be paid, phase will simply transition from one to the next.

Available options:

prorata,

pay_in_full,

none

Example:

"prorata"

data.transition_invoicing_schedule

enum<string>

required

Represents when the transition amount will be invoiced.

immediately: An invoice will be generated immediately with the corresponding amount.

Available options:

immediately

Example:

"immediately"

data.products

object[]

required

Products comprising the subscription phase.

data.products.id

string

required

Product ID.

Example:

"itm_FJKlqUb8COXw55"

data.products.name

string

required

Product name. This will appear on the final invoices.

Example:

"Product name"

data.products.description

string | null

required

Product description. This will appear on the final invoices.

Example:

"A description of the product."

data.products.description_display_interval_dates

boolean

required

Indicates if the dates of the interval should be automatically added in the product description on the invoices.

data.products.attached_at

string | null

required

Date on which the product has been attached to the subscription. UTC date time string in the ISO 8601 format.

Example:

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

data.products.detached_at

string | null

required

Date on which the product has been detached from the subscription. UTC date time string in the ISO 8601 format.

Example:

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

data.products.current_period_started_at

string | null

required

Date on which the current period started. UTC date time string in the ISO 8601 format.

Example:

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

data.products.current_period_ends_at

string | null

required

Date on which the current period will end. UTC date time string in the ISO 8601 format.

Example:

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

data.products.next_payment_at

string | null

required

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

Example:

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

data.products.payment_interval

object | null

required

Interval on which the product is billed. This interval can be different between products and can differ from the subscription commitment interval.

Example:

{ "period": "months", "count": 1 }

data.products.payment_schedule

enum<string> | null

required

Indicates if the product should be billed at the start or the end of the payment interval.

Available options:

start,

end

Example:

"start"

data.products.type

enum<string>

required

Available options:

flat_fee

data.products.count

number

required

Number of product units.

Example:

1

data.products.prices

object[]

required

Price tiers of the product. If fixed amount, only one price is available.

data.coupons

object[]

required

Coupons comprising the subscription phase.

data.coupons.description

string | null

required

Coupon description.

data.coupons.expiration_date

string | null

required

Date corresponding to the expiration of the coupon.

Example:

"2024-10-13T02:00:00.000Z"

data.coupons.redemption_limit

number | null

required

Maximum number of subscriptions to which a single coupon can be applied.

data.coupons.created_at

string

required

UTC date time string in the ISO 8601 format.

Example:

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

data.coupons.type

enum<string>

required

Available options:

amount

data.coupons.discount_amount

number

required

Amount to apply as a discount on the total amount (excluding taxes) of a subscription. Expressed in the currency's smallest unit.

Example:

2000

data.coupons.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"

data.coupons.id

string | null

required

Coupon ID.

Example:

"cou_DKL4Xcb5VSa8CQ"

data.coupons.name

string | null

required

Coupon name.

Example:

"Partner discount"

data.coupons.subscription_coupon_id

string

required

Coupon identifier in the context of the subscription.

Example:

"coos_d9pVekhjoGppuX"

data.coupons.repeat

enum<string>

required

Coupon frequency.

once: Will apply the coupon only to the first one invoice.
forever: Will apply the coupon to all invoices.
custom: Will apply to coupon until a specified expiration date.

Available options:

once,

forever,

custom

Example:

"forever"

data.coupons.product_ids

string[]

required

Product IDs to which the coupon will be applied.

Example:

["itm_FJKlqUb8COXw55"]

data.coupons.apply_at

string | null

required

Coupon first application date. UTC date time string in the ISO 8601 format.

Example:

"2024-10-13T02:00:00.000Z"

data.coupons.expires_at

string | null

required

Coupon expiration date. Only applies to the custom coupon frequency. UTC date time string in the ISO 8601 format.

Example:

"2024-10-13T02:00:00.000Z"

data.created_at

string

required

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

Example:

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

data.updated_at

string

required

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

Example:

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

Get subscription Get subscription phase

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

{
  "meta": {
    "total": 1,
    "taken": 1,
    "skipped": 0
  },
  "data": [
    {
      "id": "sup_1FoLfIQ5VOMbXf",
      "type": "standard",
      "status": "active",
      "order": 0,
      "activation_strategy": "manual",
      "end_strategy": "duration",
      "duration": {
        "count": 1,
        "period": "years"
      },
      "billing_date_setting": "phase_start",
      "initial_billing_at": "2024-10-13T02:00:00.000Z",
      "starts_at": "2024-10-13T02:00:00.000Z",
      "ends_at": "2024-10-13T02:00:00.000Z",
      "billing_cycle_alignment": "calendar_period",
      "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": "fee",
              "id": "<string>",
              "amount": 24000
            }
          ]
        }
      ],
      "coupons": [
        {
          "description": "<string>",
          "expiration_date": "2024-10-13T02:00:00.000Z",
          "redemption_limit": 123,
          "created_at": "2024-12-20T16:04:11Z",
          "type": "amount",
          "discount_amount": 2000,
          "currency": "EUR",
          "id": "cou_DKL4Xcb5VSa8CQ",
          "name": "Partner discount",
          "subscription_coupon_id": "coos_d9pVekhjoGppuX",
          "repeat": "forever",
          "product_ids": [
            "itm_FJKlqUb8COXw55"
          ],
          "apply_at": "2024-10-13T02:00:00.000Z",
          "expires_at": "2024-10-13T02:00:00.000Z"
        }
      ],
      "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

Invoices > Transactions

Invoicing entities

OAuth2

Organisations

Payments

Plans

Price configurations

Products

Quotes

Subscriptions

Taxes

Third-party apps

Wallets

Webhooks

Get subscription phases

Authorizations

Path Parameters

Response