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",
      "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>",
          "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.

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

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

data.order

number

required

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

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

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

data.duration

object | null

required

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

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

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.

data.starts_at

string | null

required

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

data.ends_at

string | null

required

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

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

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

data.products

object[]

required

Products comprising the subscription phase.

data.products.id

string

required

Product ID.

data.products.name

string

required

Product name. This will appear on the final invoices.

data.products.description

string | null

required

Product description. This will appear on the final invoices.

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.

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.

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.

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.

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.

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.

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

data.products.type

enum<string>

required

Available options:

flat_fee

data.products.count

number

required

Number of product units.

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.created_at

string

required

UTC date time string in the ISO 8601 format.

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.

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

data.coupons.id

string | null

required

Coupon ID.

data.coupons.name

string | null

required

Coupon name.

data.coupons.subscription_coupon_id

string

required

Coupon identifier in the context of the subscription.

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

data.coupons.product_ids

string[]

required

Product IDs to which the coupon will be applied.

data.coupons.apply_at

string | null

required

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

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.

data.created_at

string

required

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

data.updated_at

string

required

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

Was this page helpful?

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",
      "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>",
          "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

Invoicing entities

OAuth2

Organisations

Payments

Plans

Price configurations

Products

Quotes

Subscriptions

Taxes

Third-party apps

Wallets

Webhooks

Get subscription phases

Authorizations

Path Parameters

Response