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.

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

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

active

Boolean

Whether the subscription is active. Setting to false will irreversibly close the subscription if the customer has already accepted it.
Default = true

webhook_url

String

The url to post to when certain actions are performed on the subscription.

Sample Response

			
{
  "_id": "61f32dc2f62bdc6a48945067",
  "external_id": "439772921",
  "description": "Gold+ Plan",
  "amount": 9.97,
  "frequency": "Weekly",
  "start_date": "2022-02-23",
  "number_of_payments": "",
  "end_date": null,
  "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 **** 4279",
          "amount": 9.97,
          "tip": 0,
          "paid_on": "2022-02-23T11:29:01-06:00",
          "payment_type": "payment_card",
          "transaction_type": "capture",
          "tax": 0
        }
      ]
    }
  ],
  "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,
  "webhook_url": "https://yourcompany.com/webhook"
}