Get Subscription
The following endpoint can be used to retrieve the details of a subscription within the Hyfin application.
Endpoint
The following endpoint can be used to retrieve a subscription. You must replace the {base_url} , {external_id} and {site_id} variables with the appropriate values.
GET
{base_url}/api/v3.1/site/{site_id}/subscription/{external_id}
Request
No body is required for this API call
Response
Field
Type
Description
external_id
String
The unique subscription id from the source system/database. If we detect a record with the same external_id, it will be updated, otherwise it will be added.
id
String
The id of the subscription, assigned by the system.
description
String
A short description of the products/services on the subscription used in the payment request displayed to the customer.
amount
Number
The amount to charge for each billing period. Format = 0.00
frequency
String
The billing frequency.
One of Daily, Weekly, Bi-Weekly, Semi-Monthly, Monthly, Quarterly, Semi-Annually, Yearly
One of Daily, Weekly, Bi-Weekly, Semi-Monthly, Monthly, Quarterly, Semi-Annually, Yearly
customer
A reference to the customer record.
start_date
Date
The start date of the subscription. If left blank, it will be set when the customer confirms their payment method. Format = YYYY-MM-DD
number_of_payments
Number
The number of installments to be made. If left blank, the subscription continues indefinitely or until manually closed.
status
String
The current status of the subscription.
One of pending, active, paused, failed, closed
One of pending, active, paused, failed, closed
active
Boolean
Whether the subscription is active. Setting to false will irreversibly close the subscription if the customer has already accepted it.
Default = true
Default = true
reference_number
String
The unique reference number assigned to the subscription by the system. It is also the code in the customer-facing link.
invoices
The invoices billed by the subscription so far, each without its customer (it is the subscription's own customer). Empty until the first one is billed.
created_at
Date
The date the subscription was created.
updated_at
Date
The date the subscription was last updated.
Sample Response
{
"id": "61f32dc2f62bdc6a48945067",
"external_id": "439772921",
"reference_number": "N7E6NSZ4A816",
"description": "Gold+ Plan",
"amount": 9.97,
"frequency": "Weekly",
"start_date": "2022-02-23",
"number_of_payments": "",
"invoices": [
{
"external_id": "39772634",
"invoice_number": "",
"totals": {
"total": 9.97,
"tax": 0
},
"notifications": [],
"lines": [],
"description": "Gold+ Plan",
"invoice_date": "2022-02-23",
"due_date": "2022-02-23",
"customer_memo": "",
"internal_memo": "",
"active": true,
"payments": [
{
"external_id": "62331255",
"gateway_transaction_id": "574823902",
"display_name": "Visa",
"amount": 9.97,
"tip": 0,
"tax": 0,
"fee": 0,
"paid_on": "2022-02-23T11:29:01-06:00",
"payment_type": "payment_card",
"payment_sub_type": "visa",
"status": "captured",
"is_refund": false
}
]
}
],
"status": "active",
"customer": {
"external_id": "72345322",
"first_name": "John",
"last_name": "Doe",
"account_name": null,
"mobile_phone": "111-222-3333",
"email": "johndoe@abc.com",
"notification_options": {
"notify_phone": true,
"notify_email": false
}
},
"active": true,
"created_at": "2025-05-30T19:19:44.143Z",
"updated_at": "2025-05-30T19:19:44.143Z"
}