Get Subscription

Use this when you need one subscription as Hyfin has it, by its _id.


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 we assign to this subscription. Leave it out when creating a subscription, and send it when updating one.
externalId
String
Your own id for this subscription, from your software. Send the same externalId again to update this subscription instead of adding a new one. We match on this value but do not stop duplicates, so keep it unique within the site.
frequency
String
The billing frequency. Bi-Weekly bills every 14 days and Quarterly every 3 months. Semi-Monthly bills twice a month, on the start day and on the day of the month 14 away from it: a start on the 1st bills the 1st and 15th, and a start on the 20th bills the 20th and the 6th. Semi-Annually bills every 6 months on the start day. A Monthly subscription started on the 29th to 31st bills on the last day of a shorter month and stays on that day afterwards.
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. Only applies to Daily, Weekly, Monthly and Yearly, and is ignored for the other frequencies.
startDate
The start date of the subscription. If left blank, it will be set when the customer confirms their payment method. A date without a time. A time or time zone sent with it is dropped, not converted, so the date stays as written. 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. A webhook is sent when a payment reaches a new status, and when a text message, email or WhatsApp message is sent, delivered, read, delayed or fails, or the customer clicks the payment link.
attachmentRefs
A list of attachments.
send
Who the subscription is sent to, per channel. A channel you list is used as given, and an empty list ([]) turns that channel off. A channel you omit keeps the recipients the subscription already has, or is filled from the customer's contacts, following the customer's notification control, when it has none yet. On a create, leave send out to let the customer's contacts decide every channel when the subscription is sent. On an update, leaving it out keeps the recipients already chosen. A read returns send.to as null until recipients have been chosen. billTo.emails and billTo.sms stay the override for who receives those channels, but never turn back on a channel send turned off. Every invoice the subscription generates is sent to these recipients, as they stand when that invoice is generated, so a change applies to invoices generated afterwards.
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 on each invoice the subscription creates. 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 who receives and pays the invoice.
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",
  "externalId": "439772921",
  "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": {}
  },
  "send": {
    "to": {
      "email": [
        {
          "name": "John Doe",
          "address": "johndoe@abc.com",
          "as": "to",
          "contact": "6839e415564d3cc216032361"
        }
      ],
      "sms": [],
      "whatsApp": []
    }
  },
  "deleted": false
}


		

Related