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} , {_id} and {site_id} variables with the appropriate values.

GET

{base_url}/api/v4/site/{site_id}/subscription/{_id}

Request

No body is required for this API call

Response

Field

Type

Description

_id

String

The id of the subscription. This field is auto generated by the system and is not required when creating a new subscription, but it is required when updating an existing subscription.

frequency

String

The billing frequency.
One of Daily, Weekly, Bi-Weekly, Semi-Monthly, Monthly, Quarterly, Semi-Annually, Yearly

frequencyUnits

Number

Number of frequency units between installments. Ex: frequency = Yearly and frequencyUnits = 2 means every 2 years.

startDate

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

numberOfPayments

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

webhookUrl

String

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

attachmentRefs

A list of attachments.

customer

String

The _id of the customer

code

String

The unique code used in the customer-facing link to the subscription.

lines

The line items billed by the subscription. A request that only sends amount and description gets a single recurring line built from them.

totalsRecurring

The totals of each recurring invoice. total is the amount charged each billing period.

totalsFirstInvoice

The totals of the first invoice, which also includes any one-time lines.

billToCustomer

String

The _id of the customer to bill.

billTo

Optional overrides for the Bill To section of the invoice. If billToCustomer is provided, this object will be merged with the customer's information and can be used to override specific fields. If billToCustomer is not provided, the fields in this object will be used as the Bill To information on the invoice.

soldTo

Optional overrides for the Sold To / Customer section of the invoice.

deleted

Boolean

This flag represents whether the record is deleted and no longer available to be used.

Sample Response

			
{
  "_id": "61f32dc2f62bdc6a48945067",
  "code": "KA39TI45JLMN",
  "customer": "61f32dc2f62bdc6a48951255",
  "billToCustomer": "61f32dc2f62bdc6a48951255",
  "lines": [
    {
      "name": "",
      "description": "Gold+ Plan",
      "qty": 1,
      "unitPrice": 3499,
      "total": 3499,
      "isRecurring": true
    }
  ],
  "totalsRecurring": {
    "taxes": 0,
    "discounts": 0,
    "total": 3499
  },
  "totalsFirstInvoice": {
    "taxes": 0,
    "discounts": 0,
    "total": 3499
  },
  "frequency": "Monthly",
  "frequencyUnits": 1,
  "startDate": "2022-02-23",
  "numberOfPayments": null,
  "status": "active",
  "webhookUrl": "https://yourcompany.com/webhook",
  "attachmentRefs": {
    "internal": [],
    "external": []
  },
  "billTo": {
    "name": "John Doe",
    "attn": "",
    "address": {},
    "emails": [],
    "sms": []
  },
  "soldTo": {
    "name": "John Doe",
    "attn": "",
    "address": {}
  },
  "deleted": false
}