v1

latestOpenAPI 3.1.02026-07-222392081.7 MB

Subscriptions

Get subscription

Retrieve the details of an existing subscription.

get/v2/subscriptions/{id}

Path parameters

idstring required

Query parameters

include_live_billingstring

Response

idstring required

Subscription ID.

namestring nullable required

Subscription custom name.

currency'EUR' | 'AED' | 'AFN' | 'XCD' | 'ALL' | 'AMD' | 'AOA' | 'ARS' | 'USD' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'XOF' | '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' required

Currency code. See ISO 4217.

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.
archived: The subscription is a previous version kept after an update.
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.

purchase_orderstring nullable required

Reference to the purchase order.

customer_idstring required

ID of the customer.

invoicing_entity_idstring nullable required

ID of the invoicing entity attached to the subscription. If not defined, fallback to customer's invoicing entity.

plan_idstring nullable required

Deprecated field, please use template_id.

template_idstring nullable required

ID of the template that the subscription is linked to.

checkout_session_idstring nullable required

ID of the checkout session.

crm_opportunity_idstring nullable required

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

minimum_invoice_feenumber nullable required

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

renew_automaticallyboolean required

Deprecated field, please use contract_terms.

activation_strategy'start_date' | 'manually' | 'checkout' | 'quote' | 'contract_start_date' nullable 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.

starts_atstring date-time nullable required

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

contract_startstring date-time nullable required

Deprecated field, please use contract_terms.

contract_endstring date-time nullable required

Deprecated field, please use contract_terms.

initial_billing_atstring date-time nullable 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.

paused_atstring date-time nullable required

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

reactivate_atstring date-time nullable required

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

cancel_atstring date-time nullable required

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

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.

cancellation_amountnumber nullable required

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

cancellation_reasonstring nullable required

Reason for the cancellation.

cancellation_source'portal' | 'app' | 'api' | 'system' nullable required

Origin of the cancellation.

portal: customer cancelled themselves from the hosted customer portal.
app: admin cancelled from the Hyperline dashboard.
api: cancelled programmatically through the public API.
system: cancelled by an automated internal process.

estimated_arrnumber nullable required

Estimated Annual Recurring Revenue generated by the subscription.

contract_valuenumber nullable required

Contract value of the subscription. This value is overridable by the user.

current_period_started_atstring date-time nullable required

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

current_period_ends_atstring date-time nullable required

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

next_payment_atstring date-time nullable required

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

next_payment_amountnumber nullable required

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

renews_atstring date-time nullable required

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

current_phase_idstring nullable required

ID of the current subscription phase.

display_shipping_detailsboolean nullable required

Indicates if the shipping details should be displayed on the subscription's invoices.

propertiesobject nullable required

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

custom_propertiesobject nullable required

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

invoice_schedule'period_start' | 'period_end' nullable required

Defines when invoices are generated relative to the billing period.

period_start: Invoices are generated at the start of the billing period.
period_end: Invoices are generated at the end of the billing period.

generate_documentboolean required

Generate documents instead of invoices for the subscription.

document_namestring nullable required

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

add_tax_to_documentboolean required

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

generate_draft_invoicesboolean required

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

invoice_custom_notestring nullable required

Default custom note added to invoices generated by the subscription.

created_atstring date-time required

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

updated_atstring date-time required

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

Payment method type used to pay the subscription.

Example response

{
  "id": "sub_B6ClkdqNqVNBgY",
  "name": "Yearly subscription",
  "currency": "EUR",
  "status": "active",
  "customer_id": "cus_QalW2vTAdkR6IY",
  "invoicing_entity_id": "ive_jerrb484RHn",
  "plan_id": "plan_zHmjoDee4ZRmQV",
  "template_id": "subt_7gdusOkqr5L0B8",
  "minimum_invoice_fee": 250,
  "commitment_interval": {
    "period": "years",
    "count": 1
  },
  "renew_automatically": true,
  "renew_for": {
    "period": "years",
    "count": 1
  },
  "activation_strategy": "start_date",
  "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",
  "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",
  "renews_at": "2024-12-20T16:04:11Z",
  "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.",
      "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": "once"
      },
      "payment_schedule": "start",
      "count": 1
    }
  ],
  "integrations": [
    {
      "entity_id": "123456789",
      "provider_name": "stripe",
      "provider_account_id": "acc_1234567890"
    }
  ],
  "phases": [
    {
      "id": "sup_1FoLfIQ5VOMbXf",
      "name": "Initial term",
      "type": "standard",
      "status": "pending",
      "activation_strategy": "manual",
      "end_strategy": "duration",
      "duration": {
        "count": 1,
        "period": "years"
      },
      "billing_date_setting": "phase_start",
      "billing_cycle_alignment": "anniversary",
      "transition_calculation_method": "prorata",
      "transition_invoicing_schedule": "immediately",
      "products": [
        {
          "id": "itm_FJKlqUb8COXw55",
          "name": "Product name",
          "description": "A description of the product.",
          "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": "once"
          },
          "payment_schedule": "start",
          "count": 1
        }
      ],
      "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"
  },
  "template": {
    "id": "subt_7gdusOkqr5L0B8",
    "name": "My example template",
    "configurationId": "subtc_7mHWOlPStUogvp"
  },
  "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"
    },
    "url": "https://billing.hyperline.co/checkout/che_hEUPdVG7IgjpW1"
  },
  "payment_method": {
    "id": "pm_1xMpj5bwRqN7LM",
    "status": "active",
    "type": "card",
    "last_4_digits": 2718,
    "expiration_date": "2027-11",
    "brand": "visa"
  },
  "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_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"
  }
}