# Hyfin

> Hyfin is an accounts receivable and payment automation platform that helps businesses send invoices, accept payments, reduce processing costs, and improve cash flow through flexible payment options and integrations.

---

# Frequently Asked Questions

> Here are some answers to the questions we get asked the most.


## What can be branded/customized?
<b>Hyfin allows for many brand or feature customizations.</b>
<br>Logo, color theme, message details, Payment types (CC, ACH), payment confirmations/notifications, payment terms, tipping, partial payments, hosted payment page field additions, text message contents, and much more can all be set in Hyfin.

## Can users have different roles/limits?
<b>Roles are completely customizable.</b>
<br>
With proper permissions, Hyfin gives the ability to create any number of roles as needed so their employees can create invoices and/or, apply refunds, produce reports, receive payment confirmation or failure notifications, and much more.

## Does the merchant have access to the customer's credit card information?
<b>No.</b>
<br>
Hyfin does not store or display credit card data.  Hyfin receives an encrypted token that is used to facilitate payments.

## Is there a limit or fee per Hyfin Users?
<b>No. </b>
<br>Hyfin does not limit the number of users per merchant account.
<br>
Authorized users can add new users and assign permissions according to job function.

## Can customers submit a tip?
<b>Yes, if applicable, tipping can be enabled.</b> 
<br>
 Like the partial payment option, once enabled in Hyfin, the option to provide a tip would be available to any and all customers

## Can Hyfin automatically charge a credit card on file?
<b>Yes, Hyfin supports a "payment-on-file" like functionality which requests customers provide a CC or ACH payment method that can be used for future invoices or to initiate a subscription. </b>
<br>This is completely secure and better than "card-on-file" in that the Credit Card or ACH information is never shared with the merchant and the tokenized payment method can be charged

## Can customers submit partial payments?
<b>Yes, Hyfin can be configured to collect partial payments for deposits purposes, also check out invoice installments. </b> <br>Like the tipping option, if you choose to enable partial payments, the option would be available to any and all customers. For spreading payments over time, the Subscriptions feature is recommended.  The customer will be able to pay a specific amount or percentage of the total according to their choosing.<br><br>
<b>While partial payments allow collection of any amount less than the total, Invoice installments allow merchants to specify amounts due for deposits or through stages of a contract with specific due dates for each installment. </b> 

## Can payments be scheduled?
<b>Yes, a Hyfin invoice can be scheduled to go out at a particular date and time. </b> <br> Invoices also have installments which allow for specified amounts or percentages of the total to be sent on specific days</b> <br> Additionally, with "Subscriptions," payment requests can be sent on a recurring basis to satisfy a regular/recurring obligation or spread a payment over time.<br><br>Future dated invoice installments and iterations of recurring payments will be collected/processed at 10 AM local time based on the business address.

## Can recurring payments be set up?
<b>Yes</b> <br>Hyfin supports recurring payments as Subscriptions that can be set up to recur weekly, monthly, quarterly, annually, semi-monthly/annually, or with a custom cadence in multiples of days, weeks, months, etc...<br><br>Recurring payments will be collected/processed at 10AM local time based on the business's timezone.

## Can the platform be used as a virtual terminal (input CC info)?
<b>Yes</b> <br>Hyfin offers a virtual terminal so a merchant can enter credit card or ACH information directly.<br>With certain integrations, a physical terminal can also be used to take card present payments.

## Can payment receipt confirmation be set up?
<b>Yes</b> <br>Hyfin payment receipt notifications can be configured to go to one or more account users.  Additionally, the "Payments" option on the left will provide a bubble and a number indicating a payment has been received since your last log in.

## Does Hyfin provide confirmation of receipt or that the customer has opened/viewed the email or text?
<b>Yes</b> <br>Hyfin communicates receipts to both merchants and customers with the last 4 digits of the credit card used and the authorization code

## How do I know when a payment is received?
<b>Hyfin provides payment notifications in several ways:</b><br>
<li> An email alert can be sent when a payment is received
<li> the Payments option on the left will provide a bubble and a number indicating a payment has been received since your last log in
<li> You can go to the paid column of any page to see payments in the last day, week, month, or all time.
<li> If you are looking for a specific payment, you can search for that invoice, customer name, phone number, email address, or amount in the search bars

## Can an invoice be attached?
<b>Yes, PDF's can be attached in Hyfin and downloaded from the payment link sent.</b><br>
If the invoice is sent via Hyfin from within QuickBooks Online, the customer will see details for each line item as well as receive the QuickBooks Invoice.  This capability is not available for QuickBooks Desktop, but the merchant can still send the QBD invoice directly, but that would need to be accomplished through QuickBooks conventionally.

## Can surcharges and convenience fees be applied?
<b>Hyfin supports multiple cost savings features, including Convenience Fees,  surcharging, cash discounting and Dual Pricing that can be applied per payment request.</b> <br>
Convenience fees: Apply a specific dollar amount applied to all transactions, regardless of credit, debit, or ACH.  </b> <br>
Surcharge (prohibited in some states): Apply a percentage to credit card transactions, only.<br>
Cash Discount/Dual Pricing: Apply a percentage discount automatically to all cash payments and consistent price on all Hyfin transactions, regardless of credit, debit, or ACH<br>
<b>Dual Pricing is a great way to virtually eliminate the cost of CC processing, so reach out to your merchant service provider for more detail</b><br><br>
<body>
  <p style="color:rgba(255,0,0,0.5);">Please note, we strongly advise merchants check their state legislation and Visa/Master Card guidelines to determine if any rules prohibit or limit the use of convenience fees. text</p>
</body> 
<br>
Hyfin does also allow merchants using the QuickBooks Online integration to collect any fee.<br><br>

To set up fees, use the following steps:<br>
<li>Click "Settings", Click “Fees”
<li>You must Read and Agree to the “Important Notice” regarding compliance to proceed.
<li>Select which fee you wish to impose. 
<li>Enter fee amount in space below.
<br><br>
Allow Fee overrides - toggle these on if you would like to: <br>
  <li>Select a specific customer to not bill fees to.
  <li>Turn off the fees while completing a specific transaction.

## Does an invoice have an expiration date?
<b>Yes, it can. </b> <br> When the invoice is created, you can set an expiration date and the invoice will be automatically cancelled on that date.  You can also cancel an outstanding invoice directly. 

## How does Hyfin use the personal information provided in the platform?
Please see Hyfin's privacy policy: 
<a href="/privacy-policy" target="_blank" style="color: blue"><u>Hyfin Privacy Policy</u></a>


## What reporting is available?
Hyfin offers payment reporting (date, status, order number, payment method, and amount) for the last day, week, month or dynamic period.<br>
Please contact our support team if you have need for a  custom report

## Can merchants send a text message to people after that initial text goes out with their invoice link / can people actually respond to them via text? 
Hyfin does not support custom communication between merchant and customer, but a payment request can be resent.  
<br>This will be the same as the original message. Merchants can copy and paste the payment link manually in a text message from their own device.  The link to the payment request can be found within the payment request.

## Can I tell how the customer paid (ACH vs CC)?
<b>Yes. </b> <br>The payment types (CC vs ACH) are identified in the Payments listing screen as well as exports from that area of Hyfin

## When will I receive my deposits?
Batch times and deposits are not determined by Hyfin.<br>
Please consult your merchant services provider for more detail, to request a time change, or to understand CC/ACH funding.

## Can the platform be connected to a physical terminal?
<b>Yes.</b> With certain gateways, a physical terminal can be connected allowing merchants to take card present transactions.

## Can international merchants be supported?
<b>Yes, international merchants can be supported, but there are limitations.</b>
<br>

Auth.NET, NMI, Nuvei, and PaySafe support Canadian-based Merchants and may support other currencies as well, but only PaySafe has EFT (Canada's version of ACH).  
<br>Please note, card gateways do accept international payments, so US based merchants can send invoices off-shore and receive card payments.
In addition to currency, please consider language and ask our team about specific scenarios not detailed here.

## What are the limits to attachments?
Supported file types: '.jpg', '.jpeg', '.png', '.gif', '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.xlsm', '.xml', '.csv', '.txt', '.md' <br><br>Size: 10 mb <br>Number of attachments: 5 attachments

## How does this compare to QuickBooks with Intuit Payments
If you love QuickBooks, you can continue to use it as is with zero disruption, but still gain the benefit of our add-on.<br><br>
<li>1. Text Message invoice delivery</li>
<li>2. Deposit/Installment/Milestone based billing</li>
<li>3. Payment Links (hosted payments page and rapid checkout and donation pages)</li>
<li>4. Unlimited Payment reminders</li>
<li>5. Late fees and early pay discounts</li>
<li>6. Customer Portal</li>
<li>7. Virtual Terminal and Card Present (gateway specific)</li>
<li>8. Compliant Dual Pricing and Surcharging</li>
<li>9. Interchange Optimization</li>
<li>10. Unlimited users</li>
<li>11. A merchant service provider of your choosing</li>

## When should I change my password?
Your password will expire 90 days to help keep your account secure. You should also change it immediately if you think your password may have been compromised, shared, reused on a breached site, or used on a device you no longer trust.

Source: https://hyfin.app/w/faq

---

# Hyfin API Version 3.1

## Getting Started

### Introduction

Introduction to the API

All endpoints live under `{base_url}/api/v3.1/`. Replace `{base_url}` with the host you were issued.
The version is part of the URL path and is never negotiated by a header.

Hyfin is multi-tenant. Most endpoints act on one site and take its id in the path as `{site_id}`.
The Onboarding endpoints create the tiers that sit above a site.

### Authentication

API Authentication

Every request requires an `x-access-token` header carrying your API token:

```
x-access-token: API_TOKEN_VALUE
```

A valid token is not enough on its own. API access is a licensed feature that must be enabled on each site you call,
so a site without it fails on its very first request rather than part way through your integration:

```
Feature integrations.hyfin_api_access is not available for Site
```

That error means the token and the request were both accepted and the feature is the only thing missing.
It is enabled per site by Hyfin, so contact your representative to have it turned on.

### Endpoints

API Endpoints

Each endpoint below shows its HTTP method and URL directly under its heading, as
`METHOD {base_url}/api/v3.1/<path>`. Replace `{base_url}` with your issued host and
`{site_id}` with the id of the site you are acting on.

List endpoints page with `updated_after`. Send the `next_updated_after` from each response as the
`updated_after` of your next request. When `records_matched` is greater than `records_returned` there
are more pages still to collect.

## Onboarding

### Add/Update Site Enterprise

Add or Update a Site Enterprise

`POST {base_url}/api/v3.1/siteEnterprise/addUpdate`

#### Request Fields
- `external_id` (String, required): The unique site enterprise 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.
- `name` (String, required): The name of the site enterprise.
- `agency` (Agency, required): A reference to the agency record.
- `active` (Boolean, optional): This flag represents whether the site enterprise record is active and available to be used or not.

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `id` (String): The same id as `_id`, kept for backwards compatibility. Not returned on 4.0 and later.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "id": "60f720d248f143332af022e0"
}
```



### Add/Update Site Group

Add or Update a Site Group

`POST {base_url}/api/v3.1/siteGroup/addUpdate`

#### Request Fields
- `external_id` (String, required): The unique site group 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.
- `name` (String, required): The name of the site group.
- `agency` (Agency, required): A reference to the agency record.
- `site_enterprise` (SiteEnterprise, optional): A reference to the site enterprise record.
  - `external_id` (String, required): The unique site enterprise 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.
  - `name` (String, required): The name of the site enterprise.
  - `agency` (Agency, required): A reference to the agency record.
  - `active` (Boolean, optional): This flag represents whether the site enterprise record is active and available to be used or not.
- `active` (Boolean, optional): This flag represents whether the site group record is active and available to be used or not.

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `id` (String): The same id as `_id`, kept for backwards compatibility. Not returned on 4.0 and later.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "id": "60f720d248f143332af022e0"
}
```



### Add/Update Site

Add or Update a Site

`POST {base_url}/api/v3.1/site/addUpdate`

#### Request Fields
- `external_id` (String, required): The unique id assigned by the source system/database. If we detect a record with the same `external_id`, it will be updated, otherwise it will be added.
- `name` (String, required): The name of the site/business.
- `merchant_id` (String, required): The merchant id assigned to the business by the acquiring bank/processor.
- `agency` (Agency, required): A reference to the agency record.
- `location` (Location, required): The business address of this site/business.
  - `address_line_1` (String, optional): The street address
  - `address_line_2` (String, optional): Suite or apartment #
  - `city` (String, optional): The city
  - `state_code` (String, optional): 2-digit state abbreviation code
  - `zip_code` (String, optional): 5-digit zip code or postal code
  - `phone` (Phone, required): 10-digit main phone number of the business.
  - `website` (URL, optional): The website of the business.
- `payment_types` (Object, required): The payment methods available to accept payments from customers. At least one payment method is required.
  - `payment_card` (Object, optional): Required if you would like to enable credit/debit card transactions.
    - `active` (Boolean, optional): Whether this payment method is active and available to be used.
    - `gateway` (GatewayCard, required): The gateway used to process credit/debit card payments.
      - `code` (String, required): The code used to identify the payment gateway.
      - `credentials` (Object, required): The specific fields required to access the gateway for this site.
  - `ach` (Object, optional): Required if you would like to enable ACH transactions.
    - `active` (Boolean, optional): Whether this payment method is active and available to be used.
    - `gateway` (GatewayACH, required): The gateway used to process ACH payments.
      - `code` (String, required): The code used to identify the payment gateway.
      - `credentials` (Object, required): The specific fields required to access the gateway for this site.
- `primary_contact` (PrimaryContact, optional): The main person responsible for the business. Not required if `access_type = api_only`.
  - `first_name` (String, required): First name of the primary contact.
  - `last_name` (String, required): Last name of the primary contact.
  - `email` (Email, required): Email of the primary contact.
  - `mobile_phone` (Phone, optional): Mobile phone number of the primary contact.
- `site_enterprise` (SiteEnterprise, optional): A reference to the site enterprise record.
  - `external_id` (String, required): The unique site enterprise 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.
  - `name` (String, required): The name of the site enterprise.
  - `agency` (Agency, required): A reference to the agency record.
  - `active` (Boolean, optional): This flag represents whether the site enterprise record is active and available to be used or not.
- `site_group` (SiteGroup, optional): A reference to the site group record.
  - `external_id` (String, required): The unique site group 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.
  - `name` (String, required): The name of the site group.
  - `agency` (Agency, required): A reference to the agency record.
  - `site_enterprise` (SiteEnterprise, optional): A reference to the site enterprise record.
    - `external_id` (String, required): The unique site enterprise 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.
    - `name` (String, required): The name of the site enterprise.
    - `agency` (Agency, required): A reference to the agency record.
    - `active` (Boolean, optional): This flag represents whether the site enterprise record is active and available to be used or not.
  - `active` (Boolean, optional): This flag represents whether the site group record is active and available to be used or not.
- `branding` (Branding, optional): The unique branding of the business including the logo and primary color.
  - `logo_url` (URL, optional): The URL pointing to the company logo. Must be accessible over the internet. Required unless you send `logo_base_64`. Sending both is rejected.
  - `logo_base_64` (Base64, optional): The image data of your logo encoded in Base64, with no `data:image/png;base64,` prefix. Required unless you send `logo_url`. Sending both is rejected.
  - `color` (HEXColor, optional): The business primary color in HEX (RGB) format.
- `access_type` (String, optional): The level of access the site is requesting. Use `api_only` if you do not wish to send the welcome email to the primary contact. - format: `api_only | basic | pro`
- `active` (Boolean, optional): This flag represents whether the site record is active and available to be used or not.
- `webhook` (SiteWebhook, optional): Setup webhooks to receive real-time updates when data related to this site is updated.
  - `url` (URL, required): The remote url to send site updates to when data for this site is added or updated. Please view the `Webhooks` section of the API docs for details.
  - `active` (Boolean, optional): Used to enable or disable webhooks for this site.

#### Example Request
```json
{
  "external_id": "12345678",
  "name": "Sample Company",
  "merchant_id": "123544633452",
  "agency": {
    "external_id": "65123125",
    "name": "Sample Agency"
  },
  "location": {
    "address_line_1": "123 Main Street",
    "address_line_2": "Suite 123",
    "city": "Naples",
    "state_code": "FL",
    "zip_code": "34102",
    "phone": "239-123-1234",
    "website": "https://samplecompany.com"
  },
  "primary_contact": {
    "first_name": "Thomas",
    "last_name": "Smith",
    "email": "tsmith@samplecompany.com",
    "mobile_phone": "239-987-6543"
  },
  "payment_types": {
    "payment_card": {
      "active": true,
      "gateway": {
        "code": "gatewaycode",
        "credentials": {
          "key": "value",
          "key_2": "value2"
        }
      }
    },
    "ach": {
      "active": true,
      "gateway": {
        "code": "gatewaycode",
        "credentials": {
          "key": "value",
          "key_2": "value2"
        }
      }
    }
  },
  "branding": {
    "logo_url": "https://samplecompany.com/images/logo.png",
    "color": "#336699"
  },
  "access_type": "basic",
  "active": true,
  "webhook": {
    "active": true,
    "url": "https://mysoftware.com/webhook"
  }
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `id` (String): The same id as `_id`, kept for backwards compatibility. Not returned on 4.0 and later.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "id": "60f720d248f143332af022e0"
}
```



## Invoices

### Add/Update Invoice

Add or Update an Invoice

`POST {base_url}/api/v3.1/site/{site_id}/invoice/addUpdate`

#### Request Fields
- `external_id` (String, optional): The unique invoice 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.
- `invoice_number` (String, required): The unique number assigned from the source system and displayed to the customer on the invoice.
- `totals` (Totals, required): The total amounts on the invoice. When `lines` are supplied, `total` is validated against them and must equal the sum of every `lines[].total`, plus `tax`, minus `discounts`. A request whose totals do not reconcile is rejected. Omit `lines` and no such check is made.
  - `tax` (MoneyDollar, optional): The tax amount on the invoice.
  - `discounts` (MoneyDollar, optional): The amount to discount off of the total.
  - `subtotal` (MoneyDollar, optional): The invoice amount before tax and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you.
  - `total` (MoneyDollar, required): The total amount of the invoice (including tax and subtracting discounts).
- `customer` (Customer, optional): A reference to the customer record. Omit this field to receive a link to the invoice.
  - `external_id` (String, optional): The unique customer 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.
  - `first_name` (String, optional): The first name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `last_name` (String, optional): The last name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `account_name` (String, optional): If the customer is a business, you may use this field as an extra identifier (Ex. 123 Main Street or ABC Company). At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `mobile_phone` (String, optional): The customers mobile phone number. Required if `notification_options.notify_phone` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `email` (String, optional): The customers email address. Required if `notification_options.notify_email` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `notes` (String, optional): Internal customer notes. Visible to merchant only.
  - `active` (Boolean, optional): Whether the customer record is active and available to be used.
  - `notification_options` (NotificationOptions, optional): The customer's preferences for receiving notifications via text message and email.
    - `notify_phone` (Boolean, optional): The customer agrees to receive text messages on their mobile phone.
    - `notify_email` (Boolean, optional): The customer agrees to receive email messages.
    - `notify_whats_app` (Boolean, optional): The customer agrees to receive WhatsApp messages. Deprecated, and retained for existing integrations.
- `invoice_term_name` (String, optional): The invoice term name for the invoice. Defaults to the customer invoice term if it exists, unless `null` is passed in.
- `lines` (InvoiceLine, optional): A list of line items on the invoice. Required if `description` is not passed in.
  - `name` (String, optional): The name of the product or service. Required if `product` is not passed in.
  - `description` (String, optional): A description of the product or service.
  - `unit_price` (MoneyDollar, required): The price per unit of the line item.
  - `qty` (Integer, required): The qty of units for the line item.
  - `total` (MoneyDollar, required): The total price of the line item. Should equal `unit_price * qty`.
  - `product` (String, optional): The _id of the item.
- `description` (String, optional): A short description of the products/services on the invoice. Required if `lines` are not passed in.
- `invoice_date` (Date, optional): The date of the invoice. If set in the future, the request will not be sent until that date. Defaults to today if left blank. - format: `YYYY-MM-DD`
- `due_date` (Date, optional): The date the invoice is due. Will be overwritten if `invoice_term_name` is set and returns a different due date. - format: `YYYY-MM-DD`
- `expire_at` (Date, optional): The date the invoice will expire. The request will be cancelled if it hasn't been completed. - format: `YYYY-MM-DD`
- `po_number` (String, optional): The unique purchase order number assigned from the source system and displayed to the customer on the invoice.
- `customer_memo` (String, optional): A note presented to the customer on the bottom of the invoice.
- `internal_memo` (String, optional): A memo added to the bottom of the invoice. Only visible to internal staff, never displayed to customers.
- `active` (Boolean, optional): This flag represents whether the invoice record is active and available to be used or not.
- `payments` (Payment, optional): A list of payments made on the invoice.
  - `external_id` (String, optional): The unique payment 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.
  - `display_name` (String, required): The secure friendly display name of the payment method. Example: `VISA **** 3421`.
  - `amount` (MoneyDollar, required): The amount that was paid.
  - `paid_on` (Date, required): The date and time of when the payment was made. - format: `YYYY-MM-DDTHH:mm:ssZ`
  - `gateway_transaction_id` (String, optional): The unique id that was assigned to the payment record from the gateway when the payment was processed.
  - `tip` (MoneyDollar, optional): The tip amount that was added.
  - `tax` (MoneyDollar, optional): The tax amount that was added.
  - `fee` (MoneyDollar, optional): The fee amount that was added.
  - `invoice` (Object, optional): A reference to the invoice record. On a write this is how the payment is applied to an invoice; it is echoed back on a read, alongside the fuller `allocations` list.
    - `external_id` (String, optional): The `external_id` used in the `Add/Update Invoice` call.
    - `_id` (String, optional): The id of the invoice.
  - `allow_missing_invoice` (Boolean, optional): When `invoice.external_id` names an invoice that has not been sent yet, save the payment without applying it instead of rejecting it. An `Add/Update Invoice` call with that `external_id` within 30 days applies the payment to it. Without this, the payment is rejected with `Invoice was not found` and nothing is saved.
  - `payment_type` (String, optional): The type of payment method used to make the payment. - format: `payment_card | ach | cash | check`
  - `payment_sub_type` (String, optional): The sub type of the payment method used to make the payment. - format: `checking | savings | visa | mastercard | discover | amex | cash | other`
  - `status` (String, optional): The current status of the payment. - format: `declined | authorized | captured | voided | settled | returned | refundFailed | refunded | refundSettled`
  - `transaction_type` (String, optional): The type of transaction. Recorded on the payment but not returned by any read endpoint. - format: `sale | capture | refund | void`
  - `active` (Boolean, optional): This flag represents whether the payment record is active.
- `webhook_url` (URL, optional): The url to post to when certain actions are performed on the invoice. Notifications will be sent when a text/email fails, a customer clicks a link, or they make a payment.
- `attachments` (URL, optional): A list of attachment urls.
- `options` (Object, optional): Options to set on the invoice.
  - `tipping_enabled` (Boolean, optional): Whether tipping/gratuity should be requested on the invoice.
  - `cash_discount_disabled` (Boolean, optional): If set to `true`, cash discount will be disabled for the invoice.
  - `resend` (Boolean, optional): If set to `true` and performing an update, the invoice will be re-sent to the customer.

#### Example Request
```json
{
  "external_id": "439772921",
  "invoice_number": "12345",
  "description": "Merchandise Bundle",
  "totals": {
    "total": 45.99
  },
  "customer": {
    "external_id": "39772634",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_phone": "111-222-3333",
    "email": "johndoe@abc.com"
  },
  "options": {
    "tipping_enabled": false
  },
  "webhook_url": "https://yourcompany.com/webhook"
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `id` (String): The same id as `_id`, kept for backwards compatibility. Not returned on 4.0 and later.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.
- `link` (URL): The link to the invoice. Only returned if a `customer` is not passed in.
- `missing_customer` (Boolean): Whether the invoice references a customer that has not been synced yet, so the customer will be attached once it arrives.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "id": "60f720d248f143332af022e0",
  "link": "https//site.url/KA39T1A45JL",
  "missing_customer": false
}
```



### Send Invoice

Send an Invoice

`POST {base_url}/api/v3.1/site/{site_id}/invoice/send`

#### Request Fields
- `external_id` (String, required): The unique invoice id from the source system/database.
- `force_send` (Boolean, optional): Overrides On Hold status and invoice notification options to send. This flag does not overcome a customer having all notification options disabled.

#### Example Request
```json
{
  "external_id": "39772921"
}
```

#### Response Fields
- `success` (Boolean): Whether the invoice was sent successfully.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true
}
```



### Invoice

Get an Invoice

`GET {base_url}/api/v3.1/site/{site_id}/invoice/{external_id}`

#### Response Fields
- `external_id` (String): The unique invoice 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 invoice, assigned by the system.
- `invoice_number` (String, required): The unique number assigned from the source system and displayed to the customer on the invoice.
- `reference_number` (String): The unique reference number assigned to the invoice by the system. It is also the code in the customer-facing link.
- `internal` (Boolean): Whether the invoice is internal to the merchant and was never sent to a customer.
- `notifications` (Object): The notifications sent to the customer for this invoice, most recent last.
  - `type` (String): Always `Notification`. The invoice history also records other entry types, which are not returned here.
  - `value` (String): The outcome being reported, such as `sent`, `failed`, `Opened` or `Clicked`.
  - `description` (String): A readable description of what happened, including the email address or phone number involved.
  - `at` (Date): When the notification event occurred. - format: `YYYY-MM-DDTHH:mm:ssZ`
  - `error` (Boolean): Whether the event represents a failure.
  - `data` (Object): Any extra detail recorded with the event, such as the channel it was sent on. `null` when there is none.
- `totals` (Totals, required): The total amounts on the invoice. When `lines` are supplied, `total` is validated against them and must equal the sum of every `lines[].total`, plus `tax`, minus `discounts`. A request whose totals do not reconcile is rejected. Omit `lines` and no such check is made.
  - `tax` (MoneyDollar): The tax amount on the invoice.
  - `discounts` (MoneyDollar): The amount to discount off of the total.
  - `subtotal` (MoneyDollar): The invoice amount before tax and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you.
  - `total` (MoneyDollar, required): The total amount of the invoice (including tax and subtracting discounts).
- `customer` (Customer): A reference to the customer record. Omit this field to receive a link to the invoice.
  - `external_id` (String): The unique customer 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.
  - `first_name` (String): The first name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `last_name` (String): The last name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `account_name` (String): If the customer is a business, you may use this field as an extra identifier (Ex. 123 Main Street or ABC Company). At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `mobile_phone` (String): The customers mobile phone number. Required if `notification_options.notify_phone` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `email` (String): The customers email address. Required if `notification_options.notify_email` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `notes` (String): Internal customer notes. Visible to merchant only.
  - `active` (Boolean): Whether the customer record is active and available to be used.
  - `notification_options` (NotificationOptions): The customer's preferences for receiving notifications via text message and email.
    - `notify_phone` (Boolean): The customer agrees to receive text messages on their mobile phone.
    - `notify_email` (Boolean): The customer agrees to receive email messages.
    - `notify_whats_app` (Boolean): The customer agrees to receive WhatsApp messages. Deprecated, and retained for existing integrations.
- `invoice_term_name` (String): The invoice term name for the invoice. Defaults to the customer invoice term if it exists, unless `null` is passed in.
- `lines` (InvoiceLine): A list of line items on the invoice. Required if `description` is not passed in.
  - `name` (String): The name of the product or service. Required if `product` is not passed in.
  - `description` (String): A description of the product or service.
  - `unit_price` (MoneyDollar, required): The price per unit of the line item.
  - `qty` (Integer, required): The qty of units for the line item.
  - `total` (MoneyDollar, required): The total price of the line item. Should equal `unit_price * qty`.
  - `product` (String): The _id of the item.
- `description` (String): A short description of the products/services on the invoice. Required if `lines` are not passed in.
- `invoice_date` (Date): The date of the invoice. If set in the future, the request will not be sent until that date. Defaults to today if left blank. - format: `YYYY-MM-DD`
- `due_date` (Date): The date the invoice is due. Will be overwritten if `invoice_term_name` is set and returns a different due date. - format: `YYYY-MM-DD`
- `expire_at` (Date): The date the invoice will expire. The request will be cancelled if it hasn't been completed. - format: `YYYY-MM-DD`
- `po_number` (String): The unique purchase order number assigned from the source system and displayed to the customer on the invoice.
- `customer_memo` (String): A note presented to the customer on the bottom of the invoice.
- `internal_memo` (String): A memo added to the bottom of the invoice. Only visible to internal staff, never displayed to customers.
- `active` (Boolean): This flag represents whether the invoice record is active and available to be used or not.
- `payments` (Payment): A list of payments made on the invoice.
  - `external_id` (String): The unique payment 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.
  - `display_name` (String, required): The secure friendly display name of the payment method. Example: `VISA **** 3421`.
  - `amount` (MoneyDollar, required): The amount that was paid.
  - `paid_on` (Date, required): The date and time of when the payment was made. - format: `YYYY-MM-DDTHH:mm:ssZ`
  - `gateway_transaction_id` (String): The unique id that was assigned to the payment record from the gateway when the payment was processed.
  - `tip` (MoneyDollar): The tip amount that was added.
  - `tax` (MoneyDollar): The tax amount that was added.
  - `fee` (MoneyDollar): The fee amount that was added.
  - `invoice` (Object): A reference to the invoice record. On a write this is how the payment is applied to an invoice; it is echoed back on a read, alongside the fuller `allocations` list.
    - `external_id` (String): The `external_id` used in the `Add/Update Invoice` call.
    - `_id` (String): The id of the invoice.
  - `allow_missing_invoice` (Boolean): When `invoice.external_id` names an invoice that has not been sent yet, save the payment without applying it instead of rejecting it. An `Add/Update Invoice` call with that `external_id` within 30 days applies the payment to it. Without this, the payment is rejected with `Invoice was not found` and nothing is saved.
  - `payment_type` (String): The type of payment method used to make the payment. - format: `payment_card | ach | cash | check`
  - `payment_sub_type` (String): The sub type of the payment method used to make the payment. - format: `checking | savings | visa | mastercard | discover | amex | cash | other`
  - `status` (String): The current status of the payment. - format: `declined | authorized | captured | voided | settled | returned | refundFailed | refunded | refundSettled`
  - `transaction_type` (String): The type of transaction. Recorded on the payment but not returned by any read endpoint. - format: `sale | capture | refund | void`
  - `active` (Boolean): This flag represents whether the payment record is active.
- `webhook_url` (URL): The url to post to when certain actions are performed on the invoice. Notifications will be sent when a text/email fails, a customer clicks a link, or they make a payment.
- `attachments` (URL): A list of attachment urls.
- `created_at` (Date): The date the invoice was created.
- `updated_at` (Date): The date the invoice was last updated.

#### Example Response
```json
{
  "_id": "61f32dc2f62bdc6a48945067",
  "external_id": "439772921",
  "invoice_number": "12345",
  "description": "",
  "customer_memo": "",
  "internal_memo": "",
  "due_date": "2021-10-01",
  "totals": {
    "tax": 2.85,
    "total": 32.85
  },
  "customer": {
    "external_id": "39772634",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_phone": "111-222-3333",
    "email": "johndoe@abc.com"
  },
  "lines": [
    {
      "description": "",
      "product": {
        "external_id": "62331255",
        "name": "Mens Large T-shirt",
        "unit_price": 15
      },
      "unit_price": 15,
      "qty": 2,
      "total": 30
    }
  ],
  "payments": [
    {
      "external_id": "72345322",
      "reference_number": "N7E6NFU6WZZ5-PW3A",
      "gateway_transaction_id": "53912387124235234",
      "payment_type": "payment_card",
      "payment_sub_type": "amex",
      "display_name": "Amex",
      "amount": 30,
      "tip": 0,
      "tax": 0,
      "fee": 0,
      "paid_on": "2021-03-15T16:32:11Z",
      "status": "captured",
      "is_refund": false,
      "created_at": "2025-05-30T19:19:44.143Z",
      "updated_at": "2025-05-30T19:19:44.143Z"
    }
  ],
  "notifications": [
    {
      "error": false,
      "value": "test@test.com",
      "description": "Email to test@test.com sent",
      "at": "2021-03-15T13:32:11Z"
    },
    {
      "error": false,
      "value": "999-123-4567",
      "description": "Text to 999-123-4567 sent",
      "at": "2021-03-15T13:32:11Z"
    }
  ],
  "webhook_url": "https://yourcompany.com/webhook",
  "created_at": "2025-05-30T19:19:44.143Z",
  "updated_at": "2025-05-30T19:19:44.143Z"
}
```



### Invoices

Get multiple Invoices

`GET {base_url}/api/v3.1/site/{site_id}/invoices?updated_after={updated_after}`

#### Query Parameters
- `updated_after` (Date, optional): A timestamp to be used as the start of the date range (exclusive) of the query. On subsequent requests, you should pass in the <b>next_updated_after</b> value that was in the response of the previous request. Queries look back a maximum of 7 days. A timestamp older than that is moved forward to the limit rather than rejected, so records that last changed before it are not returned. An integration that sends back the <b>next_updated_after</b> of each response never reaches the limit. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`

#### Response Fields
- `records_matched` (Number): The number of records that matched the query parameters.
- `records_returned` (Number): The number of records that were returned.
- `next_updated_after` (Date): A timestamp to be used as the start of the date range (exclusive) of the next query for the same endpoint. This is used for pagination when querying with an updated_after parameter. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `query_time` (Date): The time the query ran. next_updated_after is derived from it, so it is the same value whenever a full page was returned. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `limit` (Number): The maximum number of records a single response will return. When records_returned equals this, more records are likely waiting and another request should be made with the returned next_updated_after.
- `records` (Invoice): The list of contacts that matched the query parameters.
  - `external_id` (String): The unique invoice 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.
  - `invoice_number` (String, required): The unique number assigned from the source system and displayed to the customer on the invoice.
  - `totals` (Totals, required): The total amounts on the invoice. When `lines` are supplied, `total` is validated against them and must equal the sum of every `lines[].total`, plus `tax`, minus `discounts`. A request whose totals do not reconcile is rejected. Omit `lines` and no such check is made.
    - `tax` (MoneyDollar): The tax amount on the invoice.
    - `discounts` (MoneyDollar): The amount to discount off of the total.
    - `subtotal` (MoneyDollar): The invoice amount before tax and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you.
    - `total` (MoneyDollar, required): The total amount of the invoice (including tax and subtracting discounts).
  - `customer` (Customer): A reference to the customer record. Omit this field to receive a link to the invoice.
    - `external_id` (String): The unique customer 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.
    - `first_name` (String): The first name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
    - `last_name` (String): The last name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
    - `account_name` (String): If the customer is a business, you may use this field as an extra identifier (Ex. 123 Main Street or ABC Company). At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
    - `mobile_phone` (String): The customers mobile phone number. Required if `notification_options.notify_phone` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
    - `email` (String): The customers email address. Required if `notification_options.notify_email` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
    - `notes` (String): Internal customer notes. Visible to merchant only.
    - `active` (Boolean): Whether the customer record is active and available to be used.
    - `notification_options` (NotificationOptions): The customer's preferences for receiving notifications via text message and email.
      - `notify_phone` (Boolean): The customer agrees to receive text messages on their mobile phone.
      - `notify_email` (Boolean): The customer agrees to receive email messages.
      - `notify_whats_app` (Boolean): The customer agrees to receive WhatsApp messages. Deprecated, and retained for existing integrations.
  - `invoice_term_name` (String): The invoice term name for the invoice. Defaults to the customer invoice term if it exists, unless `null` is passed in.
  - `lines` (InvoiceLine): A list of line items on the invoice. Required if `description` is not passed in.
    - `name` (String): The name of the product or service. Required if `product` is not passed in.
    - `description` (String): A description of the product or service.
    - `unit_price` (MoneyDollar, required): The price per unit of the line item.
    - `qty` (Integer, required): The qty of units for the line item.
    - `total` (MoneyDollar, required): The total price of the line item. Should equal `unit_price * qty`.
    - `product` (String): The _id of the item.
  - `description` (String): A short description of the products/services on the invoice. Required if `lines` are not passed in.
  - `invoice_date` (Date): The date of the invoice. If set in the future, the request will not be sent until that date. Defaults to today if left blank. - format: `YYYY-MM-DD`
  - `due_date` (Date): The date the invoice is due. Will be overwritten if `invoice_term_name` is set and returns a different due date. - format: `YYYY-MM-DD`
  - `expire_at` (Date): The date the invoice will expire. The request will be cancelled if it hasn't been completed. - format: `YYYY-MM-DD`
  - `po_number` (String): The unique purchase order number assigned from the source system and displayed to the customer on the invoice.
  - `customer_memo` (String): A note presented to the customer on the bottom of the invoice.
  - `internal_memo` (String): A memo added to the bottom of the invoice. Only visible to internal staff, never displayed to customers.
  - `active` (Boolean): This flag represents whether the invoice record is active and available to be used or not.
  - `payments` (Payment): A list of payments made on the invoice.
    - `external_id` (String): The unique payment 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.
    - `display_name` (String, required): The secure friendly display name of the payment method. Example: `VISA **** 3421`.
    - `amount` (MoneyDollar, required): The amount that was paid.
    - `paid_on` (Date, required): The date and time of when the payment was made. - format: `YYYY-MM-DDTHH:mm:ssZ`
    - `gateway_transaction_id` (String): The unique id that was assigned to the payment record from the gateway when the payment was processed.
    - `tip` (MoneyDollar): The tip amount that was added.
    - `tax` (MoneyDollar): The tax amount that was added.
    - `fee` (MoneyDollar): The fee amount that was added.
    - `invoice` (Object): A reference to the invoice record. On a write this is how the payment is applied to an invoice; it is echoed back on a read, alongside the fuller `allocations` list.
      - `external_id` (String): The `external_id` used in the `Add/Update Invoice` call.
      - `_id` (String): The id of the invoice.
    - `allow_missing_invoice` (Boolean): When `invoice.external_id` names an invoice that has not been sent yet, save the payment without applying it instead of rejecting it. An `Add/Update Invoice` call with that `external_id` within 30 days applies the payment to it. Without this, the payment is rejected with `Invoice was not found` and nothing is saved.
    - `payment_type` (String): The type of payment method used to make the payment. - format: `payment_card | ach | cash | check`
    - `payment_sub_type` (String): The sub type of the payment method used to make the payment. - format: `checking | savings | visa | mastercard | discover | amex | cash | other`
    - `status` (String): The current status of the payment. - format: `declined | authorized | captured | voided | settled | returned | refundFailed | refunded | refundSettled`
    - `transaction_type` (String): The type of transaction. Recorded on the payment but not returned by any read endpoint. - format: `sale | capture | refund | void`
    - `active` (Boolean): This flag represents whether the payment record is active.
  - `webhook_url` (URL): The url to post to when certain actions are performed on the invoice. Notifications will be sent when a text/email fails, a customer clicks a link, or they make a payment.
  - `attachments` (URL): A list of attachment urls.
  - `options` (Object): Options to set on the invoice.
    - `tipping_enabled` (Boolean): Whether tipping/gratuity should be requested on the invoice.
    - `cash_discount_disabled` (Boolean): If set to `true`, cash discount will be disabled for the invoice.
    - `resend` (Boolean): If set to `true` and performing an update, the invoice will be re-sent to the customer.
- `success` (Boolean): Whether the query completed successfully.



## Customers

### Add/Update Customer

Add or Update a Customer

`POST {base_url}/api/v3.1/site/{site_id}/customer/addUpdate`

#### Request Fields
- `external_id` (String, optional): The unique customer 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.
- `first_name` (String, optional): The first name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
- `last_name` (String, optional): The last name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
- `account_name` (String, optional): If the customer is a business, you may use this field as an extra identifier (Ex. 123 Main Street or ABC Company). At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
- `mobile_phone` (String, optional): The customers mobile phone number. Required if `notification_options.notify_phone` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
- `email` (String, optional): The customers email address. Required if `notification_options.notify_email` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
- `notes` (String, optional): Internal customer notes. Visible to merchant only.
- `active` (Boolean, optional): Whether the customer record is active and available to be used.
- `notification_options` (NotificationOptions, optional): The customer's preferences for receiving notifications via text message and email.
  - `notify_phone` (Boolean, optional): The customer agrees to receive text messages on their mobile phone.
  - `notify_email` (Boolean, optional): The customer agrees to receive email messages.
  - `notify_whats_app` (Boolean, optional): The customer agrees to receive WhatsApp messages. Deprecated, and retained for existing integrations.

#### Example Request
```json
{
  "external_id": "39772634",
  "first_name": "John",
  "last_name": "Doe",
  "account_name": "",
  "mobile_phone": "111-222-3333",
  "email": "johndoe@abc.com",
  "notes": "World's best customer",
  "active": true,
  "notification_options": {
    "notify_phone": true,
    "notify_email": true
  }
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `id` (String): The same id as `_id`, kept for backwards compatibility. Not returned on 4.0 and later.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "id": "60f720d248f143332af022e0"
}
```



### Customer

Get a Customer

`GET {base_url}/api/v3.1/site/{site_id}/customer/{external_id}`

#### Response Fields
- `external_id` (String): The unique customer 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 auto generated id assigned to the customer by the system.
- `first_name` (String): The first name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
- `last_name` (String): The last name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
- `account_name` (String): If the customer is a business, you may use this field as an extra identifier (Ex. 123 Main Street or ABC Company). At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
- `mobile_phone` (String): The customers mobile phone number. Required if `notification_options.notify_phone` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
- `email` (String): The customers email address. Required if `notification_options.notify_email` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
- `notes` (String): Internal customer notes. Visible to merchant only.
- `display_name` (String): The customer's name as it is shown to them, built by the system from the name fields above.
- `reference_number` (String): A short human readable id the system assigns to the customer.
- `contacts` (Object): The contacts attached to the customer. A customer created through the API always has one, built from the name, email and phone above.
  - `_id` (String): The auto generated id assigned to the contact.
  - `is_primary` (Boolean): Whether this is the customer's primary contact.
  - `roles` (String): The roles assigned to the contact.
- `notification_options` (NotificationOptions): The customer's preferences for receiving notifications via text message and email.
  - `notify_phone` (Boolean): The customer agrees to receive text messages on their mobile phone.
  - `notify_email` (Boolean): The customer agrees to receive email messages.
  - `notify_whats_app` (Boolean): The customer agrees to receive WhatsApp messages. Deprecated, and retained for existing integrations.
- `created_at` (Date): The date the customer was created.
- `updated_at` (Date): The date the customer was last updated.

#### Example Response
```json
{
  "_id": "6839e415564d3cc2160d945e",
  "external_id": "39772634",
  "reference_number": "N7E6NCFYECH9",
  "first_name": "John",
  "last_name": "Doe",
  "account_name": null,
  "display_name": "John Doe",
  "mobile_phone": "12223334444",
  "email": "johndoe@abc.com",
  "notes": "World's best customer",
  "notification_options": {
    "notify_phone": true,
    "notify_email": false,
    "notify_whats_app": false
  },
  "contacts": [
    {
      "_id": "61f32dc2f62bdc6a48951255",
      "is_primary": true,
      "roles": []
    }
  ],
  "created_at": "2025-05-30T19:19:44.143Z",
  "updated_at": "2025-05-30T19:19:44.143Z"
}
```



### Customers

Get multiple Customers

`GET {base_url}/api/v3.1/site/{site_id}/customers?updated_after={updated_after}`

#### Query Parameters
- `updated_after` (Date, optional): A timestamp to be used as the start of the date range (exclusive) of the query. On subsequent requests, you should pass in the <b>next_updated_after</b> value that was in the response of the previous request. Queries look back a maximum of 7 days. A timestamp older than that is moved forward to the limit rather than rejected, so records that last changed before it are not returned. An integration that sends back the <b>next_updated_after</b> of each response never reaches the limit. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`

#### Response Fields
- `records_matched` (Number): The number of records that matched the query parameters.
- `records_returned` (Number): The number of records that were returned.
- `next_updated_after` (Date): A timestamp to be used as the start of the date range (exclusive) of the next query for the same endpoint. This is used for pagination when querying with an updated_after parameter. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `query_time` (Date): The time the query ran. next_updated_after is derived from it, so it is the same value whenever a full page was returned. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `limit` (Number): The maximum number of records a single response will return. When records_returned equals this, more records are likely waiting and another request should be made with the returned next_updated_after.
- `records` (Customer): The list of contacts that matched the query parameters.
  - `external_id` (String): The unique customer 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.
  - `first_name` (String): The first name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `last_name` (String): The last name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `account_name` (String): If the customer is a business, you may use this field as an extra identifier (Ex. 123 Main Street or ABC Company). At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `mobile_phone` (String): The customers mobile phone number. Required if `notification_options.notify_phone` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `email` (String): The customers email address. Required if `notification_options.notify_email` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `notes` (String): Internal customer notes. Visible to merchant only.
  - `active` (Boolean): Whether the customer record is active and available to be used.
  - `notification_options` (NotificationOptions): The customer's preferences for receiving notifications via text message and email.
    - `notify_phone` (Boolean): The customer agrees to receive text messages on their mobile phone.
    - `notify_email` (Boolean): The customer agrees to receive email messages.
    - `notify_whats_app` (Boolean): The customer agrees to receive WhatsApp messages. Deprecated, and retained for existing integrations.
- `success` (Boolean): Whether the query completed successfully.



## Payments

### Add/Update Payment

Add or Update a Payment

`POST {base_url}/api/v3.1/site/{site_id}/payment/addUpdate`

#### Request Fields
- `external_id` (String, optional): The unique payment 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.
- `display_name` (String, required): The secure friendly display name of the payment method. Example: `VISA **** 3421`.
- `amount` (MoneyDollar, required): The amount that was paid.
- `paid_on` (Date, required): The date and time of when the payment was made. - format: `YYYY-MM-DDTHH:mm:ssZ`
- `gateway_transaction_id` (String, optional): The unique id that was assigned to the payment record from the gateway when the payment was processed.
- `tip` (MoneyDollar, optional): The tip amount that was added.
- `tax` (MoneyDollar, optional): The tax amount that was added.
- `fee` (MoneyDollar, optional): The fee amount that was added.
- `invoice` (Object, optional): A reference to the invoice record. On a write this is how the payment is applied to an invoice; it is echoed back on a read, alongside the fuller `allocations` list.
  - `external_id` (String, optional): The `external_id` used in the `Add/Update Invoice` call.
  - `_id` (String, optional): The id of the invoice.
- `allow_missing_invoice` (Boolean, optional): When `invoice.external_id` names an invoice that has not been sent yet, save the payment without applying it instead of rejecting it. An `Add/Update Invoice` call with that `external_id` within 30 days applies the payment to it. Without this, the payment is rejected with `Invoice was not found` and nothing is saved.
- `payment_type` (String, optional): The type of payment method used to make the payment. - format: `payment_card | ach | cash | check`
- `payment_sub_type` (String, optional): The sub type of the payment method used to make the payment. - format: `checking | savings | visa | mastercard | discover | amex | cash | other`
- `status` (String, optional): The current status of the payment. - format: `declined | authorized | captured | voided | settled | returned | refundFailed | refunded | refundSettled`
- `transaction_type` (String, optional): The type of transaction. Recorded on the payment but not returned by any read endpoint. - format: `sale | capture | refund | void`
- `active` (Boolean, optional): This flag represents whether the payment record is active.

#### Example Request
```json
{
  "external_id": "65432325",
  "gateway_transaction_id": "53912387124235234",
  "payment_type": "payment_card",
  "payment_sub_type": "visa",
  "display_name": "VISA **** 5123",
  "amount": 35.15,
  "paid_on": "2021-01-01T14:32:18Z",
  "status": "captured",
  "invoice": {
    "external_id": "65432661"
  }
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `id` (String): The same id as `_id`, kept for backwards compatibility. Not returned on 4.0 and later.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "id": "60f720d248f143332af022e0"
}
```



### Void Payment

Void a Payment

`POST {base_url}/api/v3.1/site/{site_id}/payment/void`

#### Request Fields
- `id` (String, required): The payment id.
- `reason` (String, optional): Optional reason for the void.

#### Example Request
```json
{
  "id": "64fa4489fb1eaa8e5ae93475"
}
```

#### Response Fields
- `success` (Boolean): Whether the void processed successfully.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true
}
```



### Refund Payment

Refund a Payment

`POST {base_url}/api/v3.1/site/{site_id}/payment/refund`

#### Request Fields
- `id` (String, required): The payment id.
- `amount` (Number, required): The refunded amount in cents (e.g. 1035 = $10.35).
- `reason` (String, optional): Optional reason for the refund.

#### Example Request
```json
{
  "id": "64fa4489fb1eaa8e5ae93475",
  "amount": 1035
}
```

#### Response Fields
- `success` (Boolean): Whether the refund processed successfully.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true
}
```



### Payment

Get a Payment

`GET {base_url}/api/v3.1/site/{site_id}/payment/{external_id}`

#### Response Fields
- `external_id` (String): The unique payment 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 payment, assigned by the system.
- `display_name` (String, required): The secure friendly display name of the payment method. Example: `VISA **** 3421`.
- `last_4` (String): The last 4 digits of the payment method. Only returned for payments taken through a stored payment method; a payment recorded through this API has none, so it is omitted.
- `amount` (MoneyDollar, required): The amount that was paid.
- `paid_on` (Date, required): The date and time of when the payment was made. - format: `YYYY-MM-DDTHH:mm:ssZ`
- `gateway_transaction_id` (String): The unique id that was assigned to the payment record from the gateway when the payment was processed.
- `tip` (MoneyDollar): The tip amount that was added.
- `tax` (MoneyDollar): The tax amount that was added.
- `fee` (MoneyDollar): The fee amount that was added.
- `invoice` (Object): A reference to the invoice record. On a write this is how the payment is applied to an invoice; it is echoed back on a read, alongside the fuller `allocations` list.
  - `external_id` (String): The `external_id` used in the `Add/Update Invoice` call.
  - `_id` (String): The id of the invoice.
- `payment_type` (String): The type of payment method used to make the payment. - format: `payment_card | ach | cash | check`
- `payment_sub_type` (String): The sub type of the payment method used to make the payment. - format: `checking | savings | visa | mastercard | discover | amex | cash | other`
- `status` (String): The current status of the payment. - format: `declined | authorized | captured | voided | settled | returned | refundFailed | refunded | refundSettled`
- `created_at` (Date): The date the payment was created.
- `updated_at` (Date): The date the payment was last updated.
- `manual_status_change` (Object): The latest status change a user made by hand in Hyfin, such as marking a payment declined. Use it to tell a manual change apart from one the payment gateway reported. Omitted when no one has changed the payment's status by hand.
  - `event_type` (String): The type of the transaction event whose status was changed, such as `sale` or `refund`.
  - `successful` (Boolean): Whether the change marked the event successful (`true`) or failed (`false`).
  - `changed_by` (String): The name of the user who made the change.
  - `changed_at` (Date): When the change was made.
  - `reason` (String): The reason the user gave for the change.
  - `transaction_id` (String): The transaction id the user entered with the change.
- `reference_number` (String): The unique reference number assigned to the payment by the system, displayed to the merchant.
- `early_pay_discounts_and_late_fees` (MoneyDollar): The net of any early payment discount and late fee applied to the payment.
- `is_refund` (Boolean): Whether the payment is a refund of another payment.
- `orig_payment` (String): On a refund, the `_id` of the payment it refunded. Omitted on payments that are not refunds.
- `custom_fields` (Object): The custom fields recorded on the payment, as name/value pairs. `{}` when there are none.
- `allocations` (Object): How the payment was applied. A payment split across several invoices has one entry per invoice.
  - `ref_type` (String): The type of record the amount was applied to. - format: `Invoice | Payment`
  - `ref` (Object): The record the amount was applied to.
    - `_id` (String): The id of the record the amount was applied to.
    - `external_id` (String): The `external_id` of that record.
    - `reference_number` (String): The reference number of that record.
  - `amount` (MoneyDollar): The amount applied to that record.

#### Example Response
```json
{
  "_id": "61f32dc2f62bdc6a48945067",
  "external_id": "65432325",
  "reference_number": "N7E6N7T75WM9-PGEM",
  "gateway_transaction_id": "53912387124235234",
  "payment_type": "payment_card",
  "payment_sub_type": "amex",
  "display_name": "AMEX ****** 3422",
  "amount": 30,
  "tip": 0,
  "tax": 0,
  "fee": 0,
  "early_pay_discounts_and_late_fees": 0,
  "paid_on": "2021-03-15T16:32:11Z",
  "status": "captured",
  "is_refund": false,
  "custom_fields": {},
  "allocations": [
    {
      "ref_type": "Invoice",
      "ref": {
        "_id": "61f32dc2f62bdc6a48951255",
        "external_id": "65432661",
        "reference_number": "N7E6NICAC2FE"
      },
      "amount": 30
    }
  ],
  "created_at": "2025-05-30T19:19:44.143Z",
  "updated_at": "2025-05-30T19:19:44.143Z"
}
```



### Payments

Get multiple Payments

`GET {base_url}/api/v3.1/site/{site_id}/payments?updated_after={updated_after}`

#### Query Parameters
- `updated_after` (Date, optional): A timestamp to be used as the start of the date range (exclusive) of the query. On subsequent requests, you should pass in the <b>next_updated_after</b> value that was in the response of the previous request. Queries look back a maximum of 7 days. A timestamp older than that is moved forward to the limit rather than rejected, so records that last changed before it are not returned. An integration that sends back the <b>next_updated_after</b> of each response never reaches the limit. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`

#### Response Fields
- `records_matched` (Number): The number of records that matched the query parameters.
- `records_returned` (Number): The number of records that were returned.
- `next_updated_after` (Date): A timestamp to be used as the start of the date range (exclusive) of the next query for the same endpoint. This is used for pagination when querying with an updated_after parameter. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `query_time` (Date): The time the query ran. next_updated_after is derived from it, so it is the same value whenever a full page was returned. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `limit` (Number): The maximum number of records a single response will return. When records_returned equals this, more records are likely waiting and another request should be made with the returned next_updated_after.
- `records` (Payment): The list of contacts that matched the query parameters.
  - `external_id` (String): The unique payment 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.
  - `display_name` (String, required): The secure friendly display name of the payment method. Example: `VISA **** 3421`.
  - `amount` (MoneyDollar, required): The amount that was paid.
  - `paid_on` (Date, required): The date and time of when the payment was made. - format: `YYYY-MM-DDTHH:mm:ssZ`
  - `gateway_transaction_id` (String): The unique id that was assigned to the payment record from the gateway when the payment was processed.
  - `tip` (MoneyDollar): The tip amount that was added.
  - `tax` (MoneyDollar): The tax amount that was added.
  - `fee` (MoneyDollar): The fee amount that was added.
  - `invoice` (Object): A reference to the invoice record. On a write this is how the payment is applied to an invoice; it is echoed back on a read, alongside the fuller `allocations` list.
    - `external_id` (String): The `external_id` used in the `Add/Update Invoice` call.
    - `_id` (String): The id of the invoice.
  - `allow_missing_invoice` (Boolean): When `invoice.external_id` names an invoice that has not been sent yet, save the payment without applying it instead of rejecting it. An `Add/Update Invoice` call with that `external_id` within 30 days applies the payment to it. Without this, the payment is rejected with `Invoice was not found` and nothing is saved.
  - `payment_type` (String): The type of payment method used to make the payment. - format: `payment_card | ach | cash | check`
  - `payment_sub_type` (String): The sub type of the payment method used to make the payment. - format: `checking | savings | visa | mastercard | discover | amex | cash | other`
  - `status` (String): The current status of the payment. - format: `declined | authorized | captured | voided | settled | returned | refundFailed | refunded | refundSettled`
  - `transaction_type` (String): The type of transaction. Recorded on the payment but not returned by any read endpoint. - format: `sale | capture | refund | void`
  - `active` (Boolean): This flag represents whether the payment record is active.
- `success` (Boolean): Whether the query completed successfully.



## Subscriptions

### Add/Update Subscription

Add or Update a Subscription

`POST {base_url}/api/v3.1/site/{site_id}/subscription/addUpdate`

#### Request Fields
- `external_id` (String, optional): 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, required): A short description of the products/services on the subscription used in the payment request displayed to the customer.
- `amount` (MoneyDollar, required): The amount to charge for each billing period.
- `frequency` (String, required): The billing frequency. - format: `Daily | Weekly | Bi-Weekly | Semi-Monthly | Monthly | Quarterly | Semi-Annually | Yearly`
- `frequency_units` (Integer, required): Number of frequency units between installments. Ex: `frequency = Yearly` and `frequency_units = 2` means every 2 years.
- `customer` (Customer, required): A reference to the customer record.
  - `external_id` (String, optional): The unique customer 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.
  - `first_name` (String, optional): The first name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `last_name` (String, optional): The last name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `account_name` (String, optional): If the customer is a business, you may use this field as an extra identifier (Ex. 123 Main Street or ABC Company). At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `mobile_phone` (String, optional): The customers mobile phone number. Required if `notification_options.notify_phone` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `email` (String, optional): The customers email address. Required if `notification_options.notify_email` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `notes` (String, optional): Internal customer notes. Visible to merchant only.
  - `active` (Boolean, optional): Whether the customer record is active and available to be used.
  - `notification_options` (NotificationOptions, optional): The customer's preferences for receiving notifications via text message and email.
    - `notify_phone` (Boolean, optional): The customer agrees to receive text messages on their mobile phone.
    - `notify_email` (Boolean, optional): The customer agrees to receive email messages.
    - `notify_whats_app` (Boolean, optional): The customer agrees to receive WhatsApp messages. Deprecated, and retained for existing integrations.
- `start_date` (Date, optional): 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` (Integer, optional): The number of installments to be made. If left blank, the subscription continues indefinitely or until manually closed.
- `active` (Boolean, optional): Whether the subscription is active. Setting to `false` will irreversibly close the subscription if the customer has already accepted it.
- `webhook_url` (URL, optional): The url to post to when certain actions are performed on the subscription.

#### Example Request
```json
{
  "external_id": "439772921",
  "description": "Gold+ Plan",
  "amount": 34.99,
  "frequency": "Monthly",
  "frequency_units": 1,
  "customer": {
    "external_id": "39772634",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_phone": "111-222-3333",
    "email": "johndoe@abc.com"
  },
  "webhook_url": "https://yourcompany.com/webhook"
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `id` (String): The same id as `_id`, kept for backwards compatibility. Not returned on 4.0 and later.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.
- `link` (URL): The link the customer uses to confirm their payment method for the subscription.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "id": "60f720d248f143332af022e0",
  "link": "https//site.url/KA39T1A45JL"
}
```



### Subscription

Get a Subscription

`GET {base_url}/api/v3.1/site/{site_id}/subscription/{external_id}`

#### Response Fields
- `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, required): A short description of the products/services on the subscription used in the payment request displayed to the customer.
- `amount` (MoneyDollar, required): The amount to charge for each billing period.
- `frequency` (String, required): The billing frequency. - format: `Daily | Weekly | Bi-Weekly | Semi-Monthly | Monthly | Quarterly | Semi-Annually | Yearly`
- `customer` (Customer, required): A reference to the customer record.
  - `external_id` (String): The unique customer 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.
  - `first_name` (String): The first name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `last_name` (String): The last name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `account_name` (String): If the customer is a business, you may use this field as an extra identifier (Ex. 123 Main Street or ABC Company). At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `mobile_phone` (String): The customers mobile phone number. Required if `notification_options.notify_phone` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `email` (String): The customers email address. Required if `notification_options.notify_email` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
  - `notes` (String): Internal customer notes. Visible to merchant only.
  - `active` (Boolean): Whether the customer record is active and available to be used.
  - `notification_options` (NotificationOptions): The customer's preferences for receiving notifications via text message and email.
    - `notify_phone` (Boolean): The customer agrees to receive text messages on their mobile phone.
    - `notify_email` (Boolean): The customer agrees to receive email messages.
    - `notify_whats_app` (Boolean): The customer agrees to receive WhatsApp messages. Deprecated, and retained for existing integrations.
- `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` (Integer): 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. - format: `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.
- `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` (Invoice): 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.
  - `external_id` (String): The unique invoice 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.
  - `invoice_number` (String, required): The unique number assigned from the source system and displayed to the customer on the invoice.
  - `totals` (Totals, required): The total amounts on the invoice. When `lines` are supplied, `total` is validated against them and must equal the sum of every `lines[].total`, plus `tax`, minus `discounts`. A request whose totals do not reconcile is rejected. Omit `lines` and no such check is made.
    - `tax` (MoneyDollar): The tax amount on the invoice.
    - `discounts` (MoneyDollar): The amount to discount off of the total.
    - `subtotal` (MoneyDollar): The invoice amount before tax and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you.
    - `total` (MoneyDollar, required): The total amount of the invoice (including tax and subtracting discounts).
  - `customer` (Customer): A reference to the customer record. Omit this field to receive a link to the invoice.
    - `external_id` (String): The unique customer 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.
    - `first_name` (String): The first name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
    - `last_name` (String): The last name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
    - `account_name` (String): If the customer is a business, you may use this field as an extra identifier (Ex. 123 Main Street or ABC Company). At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
    - `mobile_phone` (String): The customers mobile phone number. Required if `notification_options.notify_phone` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
    - `email` (String): The customers email address. Required if `notification_options.notify_email` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
    - `notes` (String): Internal customer notes. Visible to merchant only.
    - `active` (Boolean): Whether the customer record is active and available to be used.
    - `notification_options` (NotificationOptions): The customer's preferences for receiving notifications via text message and email.
      - `notify_phone` (Boolean): The customer agrees to receive text messages on their mobile phone.
      - `notify_email` (Boolean): The customer agrees to receive email messages.
      - `notify_whats_app` (Boolean): The customer agrees to receive WhatsApp messages. Deprecated, and retained for existing integrations.
  - `invoice_term_name` (String): The invoice term name for the invoice. Defaults to the customer invoice term if it exists, unless `null` is passed in.
  - `lines` (InvoiceLine): A list of line items on the invoice. Required if `description` is not passed in.
    - `name` (String): The name of the product or service. Required if `product` is not passed in.
    - `description` (String): A description of the product or service.
    - `unit_price` (MoneyDollar, required): The price per unit of the line item.
    - `qty` (Integer, required): The qty of units for the line item.
    - `total` (MoneyDollar, required): The total price of the line item. Should equal `unit_price * qty`.
    - `product` (String): The _id of the item.
  - `description` (String): A short description of the products/services on the invoice. Required if `lines` are not passed in.
  - `invoice_date` (Date): The date of the invoice. If set in the future, the request will not be sent until that date. Defaults to today if left blank. - format: `YYYY-MM-DD`
  - `due_date` (Date): The date the invoice is due. Will be overwritten if `invoice_term_name` is set and returns a different due date. - format: `YYYY-MM-DD`
  - `expire_at` (Date): The date the invoice will expire. The request will be cancelled if it hasn't been completed. - format: `YYYY-MM-DD`
  - `po_number` (String): The unique purchase order number assigned from the source system and displayed to the customer on the invoice.
  - `customer_memo` (String): A note presented to the customer on the bottom of the invoice.
  - `internal_memo` (String): A memo added to the bottom of the invoice. Only visible to internal staff, never displayed to customers.
  - `active` (Boolean): This flag represents whether the invoice record is active and available to be used or not.
  - `payments` (Payment): A list of payments made on the invoice.
    - `external_id` (String): The unique payment 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.
    - `display_name` (String, required): The secure friendly display name of the payment method. Example: `VISA **** 3421`.
    - `amount` (MoneyDollar, required): The amount that was paid.
    - `paid_on` (Date, required): The date and time of when the payment was made. - format: `YYYY-MM-DDTHH:mm:ssZ`
    - `gateway_transaction_id` (String): The unique id that was assigned to the payment record from the gateway when the payment was processed.
    - `tip` (MoneyDollar): The tip amount that was added.
    - `tax` (MoneyDollar): The tax amount that was added.
    - `fee` (MoneyDollar): The fee amount that was added.
    - `invoice` (Object): A reference to the invoice record. On a write this is how the payment is applied to an invoice; it is echoed back on a read, alongside the fuller `allocations` list.
      - `external_id` (String): The `external_id` used in the `Add/Update Invoice` call.
      - `_id` (String): The id of the invoice.
    - `allow_missing_invoice` (Boolean): When `invoice.external_id` names an invoice that has not been sent yet, save the payment without applying it instead of rejecting it. An `Add/Update Invoice` call with that `external_id` within 30 days applies the payment to it. Without this, the payment is rejected with `Invoice was not found` and nothing is saved.
    - `payment_type` (String): The type of payment method used to make the payment. - format: `payment_card | ach | cash | check`
    - `payment_sub_type` (String): The sub type of the payment method used to make the payment. - format: `checking | savings | visa | mastercard | discover | amex | cash | other`
    - `status` (String): The current status of the payment. - format: `declined | authorized | captured | voided | settled | returned | refundFailed | refunded | refundSettled`
    - `transaction_type` (String): The type of transaction. Recorded on the payment but not returned by any read endpoint. - format: `sale | capture | refund | void`
    - `active` (Boolean): This flag represents whether the payment record is active.
  - `webhook_url` (URL): The url to post to when certain actions are performed on the invoice. Notifications will be sent when a text/email fails, a customer clicks a link, or they make a payment.
  - `attachments` (URL): A list of attachment urls.
  - `options` (Object): Options to set on the invoice.
    - `tipping_enabled` (Boolean): Whether tipping/gratuity should be requested on the invoice.
    - `cash_discount_disabled` (Boolean): If set to `true`, cash discount will be disabled for the invoice.
    - `resend` (Boolean): If set to `true` and performing an update, the invoice will be re-sent to the customer.
- `created_at` (Date): The date the subscription was created.
- `updated_at` (Date): The date the subscription was last updated.

#### Example Response
```json
{
  "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"
}
```



### Subscriptions

Get multiple Subscriptions

`GET {base_url}/api/v3.1/site/{site_id}/subscriptions?updated_after={updated_after}`

#### Query Parameters
- `updated_after` (Date, optional): A timestamp to be used as the start of the date range (exclusive) of the query. On subsequent requests, you should pass in the <b>next_updated_after</b> value that was in the response of the previous request. Queries look back a maximum of 7 days. A timestamp older than that is moved forward to the limit rather than rejected, so records that last changed before it are not returned. An integration that sends back the <b>next_updated_after</b> of each response never reaches the limit. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`

#### Response Fields
- `records_matched` (Number): The number of records that matched the query parameters.
- `records_returned` (Number): The number of records that were returned.
- `next_updated_after` (Date): A timestamp to be used as the start of the date range (exclusive) of the next query for the same endpoint. This is used for pagination when querying with an updated_after parameter. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `query_time` (Date): The time the query ran. next_updated_after is derived from it, so it is the same value whenever a full page was returned. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `limit` (Number): The maximum number of records a single response will return. When records_returned equals this, more records are likely waiting and another request should be made with the returned next_updated_after.
- `records` (Subscription): The list of contacts that matched the query parameters.
  - `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, required): A short description of the products/services on the subscription used in the payment request displayed to the customer.
  - `amount` (MoneyDollar, required): The amount to charge for each billing period.
  - `frequency` (String, required): The billing frequency. - format: `Daily | Weekly | Bi-Weekly | Semi-Monthly | Monthly | Quarterly | Semi-Annually | Yearly`
  - `frequency_units` (Integer, required): Number of frequency units between installments. Ex: `frequency = Yearly` and `frequency_units = 2` means every 2 years.
  - `customer` (Customer, required): A reference to the customer record.
    - `external_id` (String): The unique customer 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.
    - `first_name` (String): The first name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
    - `last_name` (String): The last name of the customer. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
    - `account_name` (String): If the customer is a business, you may use this field as an extra identifier (Ex. 123 Main Street or ABC Company). At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
    - `mobile_phone` (String): The customers mobile phone number. Required if `notification_options.notify_phone` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
    - `email` (String): The customers email address. Required if `notification_options.notify_email` is enabled. At least one of `first_name`, `last_name`, `account_name`, `email`, or `mobile_phone` is required.
    - `notes` (String): Internal customer notes. Visible to merchant only.
    - `active` (Boolean): Whether the customer record is active and available to be used.
    - `notification_options` (NotificationOptions): The customer's preferences for receiving notifications via text message and email.
      - `notify_phone` (Boolean): The customer agrees to receive text messages on their mobile phone.
      - `notify_email` (Boolean): The customer agrees to receive email messages.
      - `notify_whats_app` (Boolean): The customer agrees to receive WhatsApp messages. Deprecated, and retained for existing integrations.
  - `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` (Integer): The number of installments to be made. If left blank, the subscription continues indefinitely or until manually closed.
  - `active` (Boolean): Whether the subscription is active. Setting to `false` will irreversibly close the subscription if the customer has already accepted it.
  - `webhook_url` (URL): The url to post to when certain actions are performed on the subscription.
- `success` (Boolean): Whether the query completed successfully.



## Products

### Add/Update Product

Add or Update a Product

`POST {base_url}/api/v3.1/site/{site_id}/product/addUpdate`

#### Request Fields
- `external_id` (String, required): The unique product 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.
- `name` (String, required): The name of the product.
- `description` (String, required): The description of the product.
- `unit_price` (MoneyDollar, required): The price per unit of the product.
- `active` (Boolean, optional): This flag represents whether the product record is active and available to be used or not.

#### Example Request
```json
{
  "external_id": "39772641",
  "name": "Men's Large T-Shirt",
  "unit_price": 14.99,
  "active": true
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `id` (String): The same id as `_id`, kept for backwards compatibility. Not returned on 4.0 and later.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "id": "60f720d248f143332af022e0"
}
```



### Product

Get a Product

`GET {base_url}/api/v3.1/site/{site_id}/product/{external_id}`

#### Response Fields
- `_id` (String): The id of the product.
- `external_id` (String, required): The unique product 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.
- `name` (String, required): The name of the product.
- `description` (String, required): The description of the product.
- `unit_price` (MoneyDollar, required): The price per unit of the product.
- `created_at` (Date): The date the product was created.
- `updated_at` (Date): The date the product was last updated.

#### Example Response
```json
{
  "_id": "6839e415564d3cc2160d945e",
  "external_id": "1",
  "name": "Garlic Soy Tikkudak Wings",
  "description": "Tikkudak is a specialty where fried chicken is baked in a charcoal oven to create a smoky and crispy flavor.",
  "unit_price": "15.00",
  "created_at": "2025-05-30T19:19:44.143Z",
  "updated_at": "2025-05-30T19:19:44.143Z"
}
```



### Products

Get multiple Products

`GET {base_url}/api/v3.1/site/{site_id}/products?updated_after={updated_after}`

#### Query Parameters
- `updated_after` (Date, optional): A timestamp to be used as the start of the date range (exclusive) of the query. On subsequent requests, you should pass in the <b>next_updated_after</b> value that was in the response of the previous request. Queries look back a maximum of 7 days. A timestamp older than that is moved forward to the limit rather than rejected, so records that last changed before it are not returned. An integration that sends back the <b>next_updated_after</b> of each response never reaches the limit. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`

#### Response Fields
- `records_matched` (Number): The number of records that matched the query parameters.
- `records_returned` (Number): The number of records that were returned.
- `next_updated_after` (Date): A timestamp to be used as the start of the date range (exclusive) of the next query for the same endpoint. This is used for pagination when querying with an updated_after parameter. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `query_time` (Date): The time the query ran. next_updated_after is derived from it, so it is the same value whenever a full page was returned. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `limit` (Number): The maximum number of records a single response will return. When records_returned equals this, more records are likely waiting and another request should be made with the returned next_updated_after.
- `records` (Product): The list of contacts that matched the query parameters.
  - `external_id` (String, required): The unique product 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.
  - `name` (String, required): The name of the product.
  - `description` (String, required): The description of the product.
  - `unit_price` (MoneyDollar, required): The price per unit of the product.
  - `active` (Boolean): This flag represents whether the product record is active and available to be used or not.
- `success` (Boolean): Whether the query completed successfully.

Source: https://hyfin.app/docs/3.1.md

---

# Hyfin API Version 4.0s

## Getting Started

### Introduction

Introduction to the API

All endpoints live under `{base_url}/api/v4/`. Replace `{base_url}` with the host you were issued.
The version is part of the URL path and is never negotiated by a header.

Hyfin is multi-tenant. Most endpoints act on one site and take its id in the path as `{site_id}`.
The Onboarding endpoints create the tiers that sit above a site.

### Authentication

API Authentication

Every request requires an `x-access-token` header carrying your API token:

```
x-access-token: API_TOKEN_VALUE
```

A valid token is not enough on its own. API access is a licensed feature that must be enabled on each site you call,
so a site without it fails on its very first request rather than part way through your integration:

```
Feature integrations.hyfin_api_access is not available for Site
```

That error means the token and the request were both accepted and the feature is the only thing missing.
It is enabled per site by Hyfin, so contact your representative to have it turned on.

### Endpoints

API Endpoints

Each endpoint below shows its HTTP method and URL directly under its heading, as
`METHOD {base_url}/api/v4/<path>`. Replace `{base_url}` with your issued host and
`{site_id}` with the id of the site you are acting on.

List endpoints page with `updated_after`. Send the `nextUpdatedAfter` from each response as the
`updated_after` of your next request. When `recordsMatched` is greater than `recordsReturned` there
are more pages still to collect.

## Invoices

### Add/Update Invoice

Add or Update an Invoice

`POST {base_url}/api/v4/site/{site_id}/invoice/addUpdate`

#### Request Fields
- `externalId` (String, optional): The unique invoice id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `invoiceNumber` (String, required): The unique number assigned from the source system and displayed to the customer on the invoice.
- `totals` (Totals, required): The total amounts on the invoice. When `lines` are supplied, `total` is validated against them and must equal the sum of every `lines[].total`, plus `taxes`, minus `discounts`. A request whose totals do not reconcile is rejected. Omit `lines` and no such check is made.
  - `taxes` (MoneyCent, optional): The tax amount on the invoice. This is an integer number of cents, so 1035 means $10.35.
  - `discounts` (MoneyCent, optional): The amount to discount off of the total. This is an integer number of cents, so 1035 means $10.35.
  - `subtotal` (MoneyCent, optional): The invoice amount before taxes and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you. This is an integer number of cents, so 1035 means $10.35.
  - `total` (MoneyCent, required): The total amount of the invoice (including tax and subtracting discounts). This is an integer number of cents, so 1035 means $10.35.
- `customer` (Customer, optional): A reference to the customer record. Omit this field to receive a link to the invoice.
  - `externalId` (String, optional): The unique customer id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
  - `firstName` (String, optional): The first name of the customer. At least one of `firstName`, `lastName`, `accountName`, `email`, or `mobilePhone` is required.
  - `lastName` (String, optional): The last name of the customer. At least one of `firstName`, `lastName`, `accountName`, `email`, or `mobilePhone` is required.
  - `accountName` (String, optional): If the customer is a business, you may use this field as an extra identifier (Ex. 123 Main Street or ABC Company). At least one of `firstName`, `lastName`, `accountName`, `email`, or `mobilePhone` is required.
  - `mobilePhone` (String, optional): The customers mobile phone number. Required if this customer is to be notified by text message. At least one of `firstName`, `lastName`, `accountName`, `email`, or `mobilePhone` is required.
  - `email` (String, optional): The customers email address. Required if this customer is to be notified by email. At least one of `firstName`, `lastName`, `accountName`, `email`, or `mobilePhone` is required.
  - `notes` (String, optional): Internal customer notes. Visible to merchant only.
  - `attachmentRefs` (AttachmentRefs, optional): A list of attachments.
    - `internal` (Attachment, optional): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
      - `url` (URL, required): Source url of the attachment.
      - `fileName` (String, required): The name of the file including the extension.
      - `size` (Number, optional): Size of the attachment in bytes.
      - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
      - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
      - `ref` (String, optional): The _id of the attachment.
    - `external` (Attachment, optional): External attachments that are sent to the customer.
      - `url` (URL, required): Source url of the attachment.
      - `fileName` (String, required): The name of the file including the extension.
      - `size` (Number, optional): Size of the attachment in bytes.
      - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
      - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
      - `ref` (String, optional): The _id of the attachment.
  - `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.
- `invoiceTermName` (String, optional): The invoice term name for the invoice. Defaults to the customer invoice term if it exists, unless `null` is passed in.
- `lines` (InvoiceLine, optional): A list of line items on the invoice. Required if `description` is not passed in.
  - `name` (String, optional): The name of the product or service. Required if <b>item</b> is not passed in.
  - `description` (String, optional): A description of the product or service.
  - `unitPrice` (MoneyCent, required): The price per unit of the line item. This is an integer number of cents, so 1035 means $10.35.
  - `qty` (Integer, required): The qty of units for the line item.
  - `total` (MoneyCent, required): The total price of the line item. Should equal `unitPrice * qty`. This is an integer number of cents, so 1035 means $10.35.
  - `item` (String, optional): The _id of the item.
- `description` (String, optional): A short description of the products/services on the invoice. Required if `lines` are not passed in.
- `invoiceDate` (Date, optional): The date of the invoice. If set in the future, the request will not be sent until that date. Defaults to today if left blank. - format: `YYYY-MM-DD`
- `dueDate` (Date, optional): The date the invoice is due. Will be overwritten if `invoiceTermName` is set and returns a different due date. - format: `YYYY-MM-DD`
- `expireAt` (Date, optional): The date the invoice will expire. The request will be cancelled if it hasn't been completed. - format: `YYYY-MM-DD`
- `poNumber` (String, optional): The unique purchase order number assigned from the source system and displayed to the customer on the invoice.
- `customerMemo` (String, optional): A note presented to the customer on the bottom of the invoice.
- `internalMemo` (String, optional): A memo added to the bottom of the invoice. Only visible to internal staff, never displayed to customers.
- `payments` (Payment, optional): A list of payments made on the invoice.
  - `externalId` (String, optional): The unique payment id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
  - `displayName` (String, required): The secure friendly display name of the payment method. Example: `VISA **** 3421`.
  - `amount` (MoneyCent, required): The amount that was paid. This is an integer number of cents, so 1035 means $10.35.
  - `paidOn` (Date, required): The date and time of when the payment was made. - format: `YYYY-MM-DDTHH:mm:ssZ`
  - `gatewayTransactionId` (String, optional): The unique id that was assigned to the payment record from the gateway when the payment was processed.
  - `invoice` (Object, optional): A reference to the invoice record. On a write this is how the payment is applied to an invoice; it is echoed back on a read, alongside the fuller `allocations` list.
    - `externalId` (String, optional): The `externalId` used in the `Add/Update Invoice` call.
    - `_id` (String, optional): The id of the invoice.
  - `allowMissingInvoice` (Boolean, optional): When `invoice.externalId` names an invoice that has not been sent yet, save the payment without applying it instead of rejecting it. An `Add/Update Invoice` call with that `externalId` within 30 days applies the payment to it. Without this, the payment is rejected with `Invoice was not found` and nothing is saved.
  - `status` (String, optional): The current status of the payment. - format: `declined | authorized | captured | voided | settled | returned | refundFailed | refunded | refundSettled`
  - `site` (String, optional): The _id of the site
  - `type` (String, optional): The type of payment method used to make the payment. - format: `payment_card | ach | cash | check`
  - `subType` (String, optional): The sub type of the payment method used to make the payment. - format: `checking | savings | visa | mastercard | discover | amex | cash | other`
  - `totals` (Totals, optional): The total amounts of the payment.
    - `taxes` (MoneyCent, optional): The tax amount on the invoice. This is an integer number of cents, so 1035 means $10.35.
    - `discounts` (MoneyCent, optional): The amount to discount off of the total. This is an integer number of cents, so 1035 means $10.35.
    - `subtotal` (MoneyCent, optional): The invoice amount before taxes and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you. This is an integer number of cents, so 1035 means $10.35.
    - `total` (MoneyCent, required): The total amount of the invoice (including tax and subtracting discounts). This is an integer number of cents, so 1035 means $10.35.
  - `allocations` (Object, optional): The allocations for the payment. This is an array of objects that specify how the payment was allocated to different orders or refunds.
    - `refType` (String, optional): The type of the reference.
    - `ref` (String, optional): The id of the reference.
    - `amount` (MoneyCent, optional): The amount allocated to the reference. This is an integer number of cents, so 1035 means $10.35.
  - `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.
- `webhookUrl` (URL, optional): The url to post to when certain actions are performed on the invoice. Notifications will be sent when a text/email fails, a customer clicks a link, or they make a payment.
- `options` (Object, optional): Options to set on the invoice.
  - `tippingEnabled` (Boolean, optional): Whether tipping/gratuity should be requested on the invoice.
  - `cashDiscountDisabled` (Boolean, optional): If set to `true`, cash discount will be disabled for the invoice.
  - `resend` (Boolean, optional): If set to `true` and performing an update, the invoice will be re-sent to the customer.
- `attachmentRefs` (Object, optional): A list of attachments.
  - `internal` (Attachment, optional): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number, optional): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String, optional): The _id of the attachment.
  - `external` (Attachment, optional): External attachments that are sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number, optional): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String, optional): The _id of the attachment.
  - `sourceDocument` (Attachment, optional): The original PDF from a source system. This is only applicable for documents that were created by our PDF parser.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number, optional): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String, optional): The _id of the attachment.
- `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.

#### Example Request
```json
{
  "externalId": "439772921",
  "invoiceNumber": "12345",
  "description": "Merchandise Bundle",
  "totals": {
    "total": 4599
  },
  "customer": {
    "externalId": "39772634",
    "firstName": "John",
    "lastName": "Doe",
    "mobilePhone": "111-222-3333",
    "email": "johndoe@abc.com"
  },
  "options": {
    "tippingEnabled": false
  },
  "webhookUrl": "https://yourcompany.com/webhook"
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `updatedAt` (Date): The date the record was last updated.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.
- `link` (URL): The link to the invoice. Only returned if a `customer` is not passed in.
- `missingCustomer` (Boolean): Whether the invoice references a customer that has not been synced yet, so the customer will be attached once it arrives.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z",
  "link": "https//site.url/KA39T1A45JL",
  "missingCustomer": false
}
```



### Send Invoice

Send an Invoice

`POST {base_url}/api/v4/site/{site_id}/invoice/send`

#### Request Fields
- `externalId` (String, required): The unique invoice id from the source system/database.
- `forceSend` (Boolean, optional): Overrides On Hold status and invoice notification options to send. This flag does not overcome a customer having all notification options disabled.

#### Example Request
```json
{
  "externalId": "39772921"
}
```

#### Response Fields
- `success` (Boolean): Whether the invoice was sent successfully.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true
}
```



## Customers

### Add/Update Customer

Add or Update a Customer

`POST {base_url}/api/v4/site/{site_id}/customer/addUpdate`

#### Request Fields
- `externalId` (String, optional): The unique customer id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `firstName` (String, optional): The first name of the customer. At least one of `firstName`, `lastName`, `accountName`, `email`, or `mobilePhone` is required.
- `lastName` (String, optional): The last name of the customer. At least one of `firstName`, `lastName`, `accountName`, `email`, or `mobilePhone` is required.
- `accountName` (String, optional): If the customer is a business, you may use this field as an extra identifier (Ex. 123 Main Street or ABC Company). At least one of `firstName`, `lastName`, `accountName`, `email`, or `mobilePhone` is required.
- `mobilePhone` (String, optional): The customers mobile phone number. Required if this customer is to be notified by text message. At least one of `firstName`, `lastName`, `accountName`, `email`, or `mobilePhone` is required.
- `email` (String, optional): The customers email address. Required if this customer is to be notified by email. At least one of `firstName`, `lastName`, `accountName`, `email`, or `mobilePhone` is required.
- `notes` (String, optional): Internal customer notes. Visible to merchant only.
- `attachmentRefs` (AttachmentRefs, optional): A list of attachments.
  - `internal` (Attachment, optional): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number, optional): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String, optional): The _id of the attachment.
  - `external` (Attachment, optional): External attachments that are sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number, optional): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String, optional): The _id of the attachment.
- `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.

#### Example Request
```json
{
  "externalId": "39772634",
  "firstName": "John",
  "lastName": "Doe",
  "accountName": "",
  "mobilePhone": "111-222-3333",
  "email": "johndoe@abc.com",
  "notes": "World's best customer",
  "deleted": false
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `updatedAt` (Date): The date the record was last updated.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}
```



## Subscriptions

### Add/Update Subscription

Add or Update a Subscription

`POST {base_url}/api/v4/site/{site_id}/subscription/addUpdate`

#### Request Fields
- `externalId` (String, optional): The unique subscription id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `description` (String, required): A short description of the products/services on the subscription used in the payment request displayed to the customer.
- `amount` (MoneyCent, required): The amount to charge for each billing period. This is an integer number of cents, so 1035 means $10.35.
- `frequency` (String, required): The billing frequency. - format: `Daily | Weekly | Bi-Weekly | Semi-Monthly | Monthly | Quarterly | Semi-Annually | Yearly`
- `frequencyUnits` (Integer, required): Number of frequency units between installments. Ex: `frequency = Yearly` and `frequencyUnits = 2` means every 2 years.
- `customer` (Customer, required): A reference to the customer record.
  - `externalId` (String, optional): The unique customer id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
  - `firstName` (String, optional): The first name of the customer. At least one of `firstName`, `lastName`, `accountName`, `email`, or `mobilePhone` is required.
  - `lastName` (String, optional): The last name of the customer. At least one of `firstName`, `lastName`, `accountName`, `email`, or `mobilePhone` is required.
  - `accountName` (String, optional): If the customer is a business, you may use this field as an extra identifier (Ex. 123 Main Street or ABC Company). At least one of `firstName`, `lastName`, `accountName`, `email`, or `mobilePhone` is required.
  - `mobilePhone` (String, optional): The customers mobile phone number. Required if this customer is to be notified by text message. At least one of `firstName`, `lastName`, `accountName`, `email`, or `mobilePhone` is required.
  - `email` (String, optional): The customers email address. Required if this customer is to be notified by email. At least one of `firstName`, `lastName`, `accountName`, `email`, or `mobilePhone` is required.
  - `notes` (String, optional): Internal customer notes. Visible to merchant only.
  - `attachmentRefs` (AttachmentRefs, optional): A list of attachments.
    - `internal` (Attachment, optional): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
      - `url` (URL, required): Source url of the attachment.
      - `fileName` (String, required): The name of the file including the extension.
      - `size` (Number, optional): Size of the attachment in bytes.
      - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
      - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
      - `ref` (String, optional): The _id of the attachment.
    - `external` (Attachment, optional): External attachments that are sent to the customer.
      - `url` (URL, required): Source url of the attachment.
      - `fileName` (String, required): The name of the file including the extension.
      - `size` (Number, optional): Size of the attachment in bytes.
      - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
      - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
      - `ref` (String, optional): The _id of the attachment.
  - `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.
- `startDate` (Date, optional): 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` (Integer, optional): The number of installments to be made. If left blank, the subscription continues indefinitely or until manually closed.
- `webhookUrl` (URL, optional): The url to post to when certain actions are performed on the subscription.
- `attachmentRefs` (AttachmentRefs, optional): A list of attachments.
  - `internal` (Attachment, optional): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number, optional): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String, optional): The _id of the attachment.
  - `external` (Attachment, optional): External attachments that are sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number, optional): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String, optional): The _id of the attachment.
- `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.

#### Example Request
```json
{
  "externalId": "439772921",
  "description": "Gold+ Plan",
  "amount": 3499,
  "frequency": "Monthly",
  "frequencyUnits": 1,
  "customer": {
    "externalId": "39772634",
    "firstName": "John",
    "lastName": "Doe",
    "mobilePhone": "111-222-3333",
    "email": "johndoe@abc.com"
  },
  "webhookUrl": "https://yourcompany.com/webhook"
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `updatedAt` (Date): The date the record was last updated.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.
- `link` (URL): The link the customer uses to confirm their payment method for the subscription.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z",
  "link": "https//site.url/KA39T1A45JL"
}
```



## Items

### Add/Update Item

Add or Update an Item

`POST {base_url}/api/v4/site/{site_id}/item/addUpdate`

#### Request Fields
- `externalId` (String, optional): The unique item id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `name` (String, required): The name of the item.
- `description` (String, required): The description of the item.
- `unitPrice` (MoneyCent, required): The price per unit of the item. This is an integer number of cents, so 1035 means $10.35.
- `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.

#### Example Request
```json
{
  "externalId": "439772921",
  "name": "Men's Large T-Shirt",
  "unitPrice": 1499,
  "deleted": false
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `updatedAt` (Date): The date the record was last updated.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}
```

Source: https://hyfin.app/docs/4.0s.md

---

# Hyfin API Version 4.0

## Getting Started

### Introduction

Introduction to the API

All endpoints live under `{base_url}/api/v4/`. Replace `{base_url}` with the host you were issued.
The version is part of the URL path and is never negotiated by a header.

Hyfin is multi-tenant. Most endpoints act on one site and take its id in the path as `{site_id}`.
The Onboarding endpoints create the tiers that sit above a site.

### Authentication

API Authentication

Every request requires an `x-access-token` header carrying your API token:

```
x-access-token: API_TOKEN_VALUE
```

A valid token is not enough on its own. API access is a licensed feature that must be enabled on each site you call,
so a site without it fails on its very first request rather than part way through your integration:

```
Feature integrations.hyfin_api_access is not available for Site
```

That error means the token and the request were both accepted and the feature is the only thing missing.
It is enabled per site by Hyfin, so contact your representative to have it turned on.

### Endpoints

API Endpoints

Each endpoint below shows its HTTP method and URL directly under its heading, as
`METHOD {base_url}/api/v4/<path>`. Replace `{base_url}` with your issued host and
`{site_id}` with the id of the site you are acting on.

List endpoints page with `updated_after`. Send the `nextUpdatedAfter` from each response as the
`updated_after` of your next request. When `recordsMatched` is greater than `recordsReturned` there
are more pages still to collect.

## Onboarding

### Add/Update Site Enterprise

Add or Update a Site Enterprise

`POST {base_url}/api/v4/siteEnterprise/addUpdate`

#### Request Fields
- `externalId` (String, required): The unique site enterprise id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `name` (String, required): The name of the site enterprise.
- `agency` (Agency, required): A reference to the agency record.
- `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `updatedAt` (Date): The date the record was last updated.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}
```



### Add/Update Site Group

Add or Update a Site Group

`POST {base_url}/api/v4/siteGroup/addUpdate`

#### Request Fields
- `externalId` (String, required): The unique site group id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `name` (String, required): The name of the site group.
- `agency` (Agency, required): A reference to the agency record.
- `siteEnterprise` (SiteEnterprise, optional): A reference to the site enterprise record.
  - `externalId` (String, required): The unique site enterprise id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
  - `name` (String, required): The name of the site enterprise.
  - `agency` (Agency, required): A reference to the agency record.
  - `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.
- `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `updatedAt` (Date): The date the record was last updated.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}
```



### Add/Update Site

Add or Update a Site

`POST {base_url}/api/v4/site/addUpdate`

#### Request Fields
- `externalId` (String, required): The unique id assigned by the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `name` (String, required): The name of the site/business.
- `merchantId` (String, required): The merchant id assigned to the business by the acquiring bank/processor.
- `agency` (Agency, required): A reference to the agency record.
- `location` (Location, required): The business address of this site/business.
  - `addressLine1` (String, optional): The street address
  - `addressLine2` (String, optional): Suite or apartment #
  - `city` (String, optional): The city
  - `stateCode` (String, optional): 2-digit state abbreviation code
  - `zipCode` (String, optional): 5-digit zip code or postal code
  - `phone` (Phone, required): 10-digit main phone number of the business.
  - `website` (URL, optional): The website of the business.
- `paymentTypes` (Object, required): The payment methods available to accept payments from customers. At least one payment method is required.
  - `paymentCard` (Object, optional): Required if you would like to enable credit/debit card transactions.
    - `active` (Boolean, optional): Whether this payment method is active and available to be used.
    - `gateway` (GatewayCard, required): The gateway used to process credit/debit card payments.
      - `code` (String, required): The code used to identify the payment gateway.
      - `credentials` (Object, required): The specific fields required to access the gateway for this site.
  - `ach` (Object, optional): Required if you would like to enable ACH transactions.
    - `active` (Boolean, optional): Whether this payment method is active and available to be used.
    - `gateway` (GatewayACH, required): The gateway used to process ACH payments.
      - `code` (String, required): The code used to identify the payment gateway.
      - `credentials` (Object, required): The specific fields required to access the gateway for this site.
- `primaryContact` (PrimaryContact, optional): The main person responsible for the business. Not required if `accessType = api_only`.
  - `firstName` (String, required): First name of the primary contact.
  - `lastName` (String, required): Last name of the primary contact.
  - `email` (Email, required): Email of the primary contact.
  - `mobilePhone` (Phone, optional): Mobile phone number of the primary contact.
- `siteEnterprise` (SiteEnterprise, optional): A reference to the site enterprise record.
  - `externalId` (String, required): The unique site enterprise id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
  - `name` (String, required): The name of the site enterprise.
  - `agency` (Agency, required): A reference to the agency record.
  - `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.
- `siteGroup` (SiteGroup, optional): A reference to the site group record.
  - `externalId` (String, required): The unique site group id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
  - `name` (String, required): The name of the site group.
  - `agency` (Agency, required): A reference to the agency record.
  - `siteEnterprise` (SiteEnterprise, optional): A reference to the site enterprise record.
    - `externalId` (String, required): The unique site enterprise id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
    - `name` (String, required): The name of the site enterprise.
    - `agency` (Agency, required): A reference to the agency record.
    - `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.
  - `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.
- `branding` (Branding, optional): The unique branding of the business including the logo and primary color.
  - `logoUrl` (URL, optional): The URL pointing to the company logo. Must be accessible over the internet. Required unless you send `logoBase64`. Sending both is rejected.
  - `logoBase64` (Base64, optional): The image data of your logo encoded in Base64, with no `data:image/png;base64,` prefix. Required unless you send `logoUrl`. Sending both is rejected.
  - `color` (HEXColor, optional): The business primary color in HEX (RGB) format.
- `accessType` (String, optional): The level of access the site is requesting. Use `api_only` if you do not wish to send the welcome email to the primary contact. - format: `api_only | basic | pro`
- `webhook` (SiteWebhook, optional): Setup webhooks to receive real-time updates when data related to this site is updated.
  - `url` (URL, required): The remote url to send site updates to when data for this site is added or updated. Please view the `Webhooks` section of the API docs for details.
  - `active` (Boolean, optional): Used to enable or disable webhooks for this site.
- `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.

#### Example Request
```json
{
  "externalId": "12345678",
  "name": "Sample Company",
  "merchantId": "123544633452",
  "agency": {
    "externalId": "65123125",
    "name": "Sample Agency"
  },
  "location": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Suite 123",
    "city": "Naples",
    "stateCode": "FL",
    "zipCode": "34102",
    "phone": "239-123-1234",
    "website": "https://samplecompany.com"
  },
  "primaryContact": {
    "firstName": "Thomas",
    "lastName": "Smith",
    "email": "tsmith@samplecompany.com",
    "mobilePhone": "239-987-6543"
  },
  "paymentTypes": {
    "paymentCard": {
      "active": true,
      "gateway": {
        "code": "gatewaycode",
        "credentials": {
          "key": "value",
          "key2": "value2"
        }
      }
    },
    "ach": {
      "active": true,
      "gateway": {
        "code": "gatewaycode",
        "credentials": {
          "key": "value",
          "key2": "value2"
        }
      }
    }
  },
  "branding": {
    "logoUrl": "https://samplecompany.com/images/logo.png",
    "color": "#336699"
  },
  "accessType": "basic",
  "webhook": {
    "active": true,
    "url": "https://mysoftware.com/webhook"
  },
  "deleted": false
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `updatedAt` (Date): The date the record was last updated.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}
```



## Invoices

### Add/Update Invoice

Add or Update an Invoice

`POST {base_url}/api/v4/site/{site_id}/invoice/addUpdate`

#### Request Fields
- `_id` (String, optional): The id of the invoice. This field is auto generated by the system and is not required when creating a new invoice, but it is required when updating an existing invoice.
- `externalId` (String, optional): The unique invoice id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `invoiceNumber` (String, required): The unique number assigned from the source system and displayed to the customer on the invoice.
- `totals` (Totals, required): The total amounts on the invoice. When `lines` are supplied, `total` is validated against them and must equal the sum of every `lines[].total`, plus `taxes`, minus `discounts`. A request whose totals do not reconcile is rejected. Omit `lines` and no such check is made.
  - `taxes` (MoneyCent, optional): The tax amount on the invoice. This is an integer number of cents, so 1035 means $10.35.
  - `discounts` (MoneyCent, optional): The amount to discount off of the total. This is an integer number of cents, so 1035 means $10.35.
  - `subtotal` (MoneyCent, optional): The invoice amount before taxes and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you. This is an integer number of cents, so 1035 means $10.35.
  - `total` (MoneyCent, required): The total amount of the invoice (including tax and subtracting discounts). This is an integer number of cents, so 1035 means $10.35.
- `customer` (Customer, optional): A reference to the customer record. Omit this field to receive a link to the invoice.
  - `_id` (String, optional): The id of the customer. This field is auto generated by the system and is not required when creating a new customer, but it is required when updating an existing customer.
  - `externalId` (String, optional): The unique customer id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
  - `displayName` (String, optional): The name that will be displayed for the customer.
  - `accountName` (String, optional): A business name or address for the customer, useful when the customer is a group. Required if more than one entry is provided in `contacts`.
  - `primaryContact` (Object, optional): The customers primary contact information. Required if no `contacts` are provided.
    - `firstName` (String, optional): The first name of the customer. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
    - `lastName` (String, optional): The last name of the customer. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
    - `displayName` (String, optional): The name that will be displayed for the contact. If left blank, it will default to the first and last name. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
    - `mobilePhone` (String, optional): The customers mobile phone number. Supports comma separated multiple phone numbers if necessary. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
    - `email` (String, optional): The customers email address. Supports comma separated multiple emails if necessary. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
    - `billingAddress` (Address, optional): The business address of this site/business.
      - `addressLine1` (String, optional): The street address
      - `addressLine2` (String, optional): Suite or apartment #
      - `city` (String, optional): The city
      - `stateCode` (String, optional): 2-digit state abbreviation code
      - `zipCode` (String, optional): 5-digit zip code or postal code
    - `shippingAddress` (Address, optional): The business address of this site/business.
      - `addressLine1` (String, optional): The street address
      - `addressLine2` (String, optional): Suite or apartment #
      - `city` (String, optional): The city
      - `stateCode` (String, optional): 2-digit state abbreviation code
      - `zipCode` (String, optional): 5-digit zip code or postal code
  - `contacts` (Object, optional): A list of customer contacts. Required if `primaryContact` is not passed in.
    - `_id` (String, optional): The id of a previously inserted contact.
    - `isPrimary` (Boolean, optional): A flag indicating whether this contact is the primary contact. If not passed in the request, the first contact will be set as the primary contact by default.
    - `roles` (String, optional): The role(s) that this contact fulfills for the customer. For example: "accounting", "technical", etc. This is for informational purposes only and does not impact functionality in any way.
  - `parentCustomer` (Object, optional): The parent customer, if applicable. A bare `_id` string is also accepted.
    - `_id` (String, optional): The id of the parent customer.
    - `externalId` (String, optional): The `externalId` of the parent customer, which can be sent instead of its `_id`.
  - `billToParentFlag` (Boolean, optional): A flag indicating whether the parent customer should be billed for this customer. Only applicable if `parentCustomer` is provided.
  - `notes` (String, optional): Internal customer notes. Visible to merchant only.
  - `attachmentRefs` (AttachmentRefs, optional): A list of attachments.
    - `internal` (Attachment, optional): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
      - `url` (URL, required): Source url of the attachment.
      - `fileName` (String, required): The name of the file including the extension.
      - `size` (Number, optional): Size of the attachment in bytes.
      - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
      - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
      - `ref` (String, optional): The _id of the attachment.
    - `external` (Attachment, optional): External attachments that are sent to the customer.
      - `url` (URL, required): Source url of the attachment.
      - `fileName` (String, required): The name of the file including the extension.
      - `size` (Number, optional): Size of the attachment in bytes.
      - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
      - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
      - `ref` (String, optional): The _id of the attachment.
  - `deleted` (Boolean, optional): Whether the customer record has been deleted and is no longer active.
- `invoiceTermName` (String, optional): The invoice term name for the invoice. Defaults to the customer invoice term if it exists, unless `null` is passed in.
- `lines` (InvoiceLine, optional): A list of line items on the invoice. Required if `description` is not passed in.
  - `name` (String, optional): The name of the product or service. Required if <b>item</b> is not passed in.
  - `description` (String, optional): A description of the product or service.
  - `unitPrice` (MoneyCent, required): The price per unit of the line item. This is an integer number of cents, so 1035 means $10.35.
  - `qty` (Integer, required): The qty of units for the line item.
  - `total` (MoneyCent, required): The total price of the line item. Should equal `unitPrice * qty`. This is an integer number of cents, so 1035 means $10.35.
  - `item` (String, optional): The _id of the item.
- `description` (String, optional): A short description of the products/services on the invoice. Required if `lines` are not passed in.
- `invoiceDate` (Date, optional): The date of the invoice. If set in the future, the request will not be sent until that date. Defaults to today if left blank. - format: `YYYY-MM-DD`
- `dueDate` (Date, optional): The date the invoice is due. Will be overwritten if `invoiceTermName` is set and returns a different due date. - format: `YYYY-MM-DD`
- `expireAt` (Date, optional): The date the invoice will expire. The request will be cancelled if it hasn't been completed. - format: `YYYY-MM-DD`
- `poNumber` (String, optional): The unique purchase order number assigned from the source system and displayed to the customer on the invoice.
- `customerMemo` (String, optional): A note presented to the customer on the bottom of the invoice.
- `internalMemo` (String, optional): A memo added to the bottom of the invoice. Only visible to internal staff, never displayed to customers.
- `payments` (Payment, optional): A list of payments made on the invoice.
  - `_id` (String, optional): The id of the payment. This field is auto generated by the system and is not required when creating a new payment, but it is required when updating an existing payment.
  - `externalId` (String, optional): The unique payment id from the source system/database. Required when `_id` is not passed in. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
  - `displayName` (String, required): The secure friendly display name of the payment method. Example: `VISA **** 3421`.
  - `amount` (MoneyCent, required): The amount that was paid. This is an integer number of cents, so 1035 means $10.35.
  - `paidOn` (Date, required): The date and time of when the payment was made. - format: `YYYY-MM-DDTHH:mm:ssZ`
  - `gatewayTransactionId` (String, optional): The unique id that was assigned to the payment record from the gateway when the payment was processed.
  - `invoice` (Object, optional): A reference to the invoice record. On a write this is how the payment is applied to an invoice; it is echoed back on a read, alongside the fuller `allocations` list.
    - `externalId` (String, optional): The `externalId` used in the `Add/Update Invoice` call.
    - `_id` (String, optional): The id of the invoice.
  - `allowMissingInvoice` (Boolean, optional): When `invoice.externalId` names an invoice that has not been sent yet, save the payment without applying it instead of rejecting it. An `Add/Update Invoice` call with that `externalId` within 30 days applies the payment to it. Without this, the payment is rejected with `Invoice was not found` and nothing is saved.
  - `status` (String, optional): The current status of the payment. - format: `declined | authorized | captured | voided | settled | returned | refundFailed | refunded | refundSettled`
  - `site` (String, optional): The _id of the site
  - `type` (String, optional): The type of payment method used to make the payment. - format: `payment_card | ach | cash | check`
  - `subType` (String, optional): The sub type of the payment method used to make the payment. - format: `checking | savings | visa | mastercard | discover | amex | cash | other`
  - `totals` (Totals, optional): The total amounts of the payment.
    - `taxes` (MoneyCent, optional): The tax amount on the invoice. This is an integer number of cents, so 1035 means $10.35.
    - `discounts` (MoneyCent, optional): The amount to discount off of the total. This is an integer number of cents, so 1035 means $10.35.
    - `subtotal` (MoneyCent, optional): The invoice amount before taxes and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you. This is an integer number of cents, so 1035 means $10.35.
    - `total` (MoneyCent, required): The total amount of the invoice (including tax and subtracting discounts). This is an integer number of cents, so 1035 means $10.35.
  - `allocations` (Object, optional): The allocations for the payment. This is an array of objects that specify how the payment was allocated to different orders or refunds.
    - `refType` (String, optional): The type of the reference.
    - `ref` (String, optional): The id of the reference.
    - `amount` (MoneyCent, optional): The amount allocated to the reference. This is an integer number of cents, so 1035 means $10.35.
  - `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.
- `webhookUrl` (URL, optional): The url to post to when certain actions are performed on the invoice. Notifications will be sent when a text/email fails, a customer clicks a link, or they make a payment.
- `options` (Object, optional): Options to set on the invoice.
  - `tippingEnabled` (Boolean, optional): Whether tipping/gratuity should be requested on the invoice.
  - `cashDiscountDisabled` (Boolean, optional): If set to `true`, cash discount will be disabled for the invoice.
  - `resend` (Boolean, optional): If set to `true` and performing an update, the invoice will be re-sent to the customer.
- `attachmentRefs` (Object, optional): A list of attachments.
  - `internal` (Attachment, optional): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number, optional): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String, optional): The _id of the attachment.
  - `external` (Attachment, optional): External attachments that are sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number, optional): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String, optional): The _id of the attachment.
  - `sourceDocument` (Attachment, optional): The original PDF from a source system. This is only applicable for documents that were created by our PDF parser.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number, optional): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String, optional): The _id of the attachment.
- `billToCustomer` (Customer, optional): The customer to bill, if different than the <b>customer</b>.
  - `_id` (String, optional): The unique _id of the customer to bill. If provided, the invoice will be billed to this customer and sent to their email and/or mobile phone number on file. Otherwise, this field will automatically be populated if the selected customer has a <b>parentCustomer</b> assigned and <b>billToParentFlag</b> is set.
- `billTo` (Object, optional): Optional overrides for the Bill To section of the invoice. If <b>billToCustomer</b> is provided, this object will be merged with the customer's information and can be used to override specific fields. If <b>billToCustomer</b> is not provided, the fields in this object will be used as the Bill To information on the invoice.
  - `name` (String, optional): Override the name displayed on the invoice in the Bill To section
  - `attn` (String, optional): Override the attention to (e.g. Attn: John Doe) displayed on the invoice in the Bill To section
  - `address` (Address, optional): Override the address displayed on the invoice in the Bill To section
    - `addressLine1` (String, optional): The street address
    - `addressLine2` (String, optional): Suite or apartment #
    - `city` (String, optional): The city
    - `stateCode` (String, optional): 2-digit state abbreviation code
    - `zipCode` (String, optional): 5-digit zip code or postal code
  - `emails` (Object, optional): Override the email addresses to send the invoice to
    - `name` (String, optional): The name of the email recipient.
    - `address` (String, optional): The email address of the recipient.
    - `as` (String, optional): Whether the email should be sent as a 'to', 'cc', or 'bcc' to the recipient. - format: `to | cc | bcc`
  - `sms` (Object, optional): Override the phone numbers to text the invoice to
    - `name` (String, optional): The name of the SMS recipient.
    - `number` (String, optional): The phone number of the recipient.
- `soldTo` (Object, optional): Optional overrides for the Sold To / Customer section of the invoice.
  - `name` (String, optional): Override the name displayed on the invoice in the Sold To section
  - `attn` (String, optional): Override the attention to (e.g. Attn: John Doe) displayed on the invoice in the Sold To section
  - `address` (Address, optional): Override the address displayed on the invoice in the Sold To section
    - `addressLine1` (String, optional): The street address
    - `addressLine2` (String, optional): Suite or apartment #
    - `city` (String, optional): The city
    - `stateCode` (String, optional): 2-digit state abbreviation code
    - `zipCode` (String, optional): 5-digit zip code or postal code
- `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.

#### Example Request
```json
{
  "_id": "61f32dc2f62bdc6a48945067",
  "invoiceNumber": "12345",
  "description": "Merchandise Bundle",
  "totals": {
    "total": 4599
  },
  "customer": {
    "externalId": "39772634",
    "primaryContact": {
      "firstName": "John",
      "lastName": "Doe",
      "mobilePhone": "111-222-3333",
      "email": "johndoe@abc.com"
    }
  },
  "options": {
    "tippingEnabled": false
  },
  "webhookUrl": "https://yourcompany.com/webhook"
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `updatedAt` (Date): The date the record was last updated.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.
- `link` (URL): The link to the invoice. Only returned if a `customer` is not passed in.
- `missingCustomer` (Boolean): Whether the invoice references a customer that has not been synced yet, so the customer will be attached once it arrives.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z",
  "link": "https//site.url/KA39T1A45JL",
  "missingCustomer": false
}
```



### Send Invoice

Send an Invoice

`POST {base_url}/api/v4/site/{site_id}/invoice/send`

#### Request Fields
- `_id` (String, required): The _id of the invoice.
- `forceSend` (Boolean, optional): Overrides On Hold status and invoice notification options to send. This flag does not overcome a customer having all notification options disabled.

#### Example Request
```json
{
  "_id": "61f32dc2f62bdc6a48945067"
}
```

#### Response Fields
- `success` (Boolean): Whether the invoice was sent successfully.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true
}
```



### Invoice

Get an Invoice

`GET {base_url}/api/v4/site/{site_id}/invoice/{_id}`

#### Response Fields
- `_id` (String): The id of the invoice. This field is auto generated by the system and is not required when creating a new invoice, but it is required when updating an existing invoice.
- `externalId` (String): The unique invoice id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `invoiceNumber` (String, required): The unique number assigned from the source system and displayed to the customer on the invoice.
- `totals` (Totals, required): The total amounts on the invoice. When `lines` are supplied, `total` is validated against them and must equal the sum of every `lines[].total`, plus `taxes`, minus `discounts`. A request whose totals do not reconcile is rejected. Omit `lines` and no such check is made.
  - `taxes` (MoneyCent): The tax amount on the invoice. This is an integer number of cents, so 1035 means $10.35.
  - `discounts` (MoneyCent): The amount to discount off of the total. This is an integer number of cents, so 1035 means $10.35.
  - `subtotal` (MoneyCent): The invoice amount before taxes and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you. This is an integer number of cents, so 1035 means $10.35.
  - `total` (MoneyCent, required): The total amount of the invoice (including tax and subtracting discounts). This is an integer number of cents, so 1035 means $10.35.
- `invoiceTermName` (String): The invoice term name for the invoice. Defaults to the customer invoice term if it exists, unless `null` is passed in.
- `lines` (InvoiceLine): A list of line items on the invoice. Required if `description` is not passed in.
  - `name` (String): The name of the product or service. Required if <b>item</b> is not passed in.
  - `description` (String): A description of the product or service.
  - `unitPrice` (MoneyCent, required): The price per unit of the line item. This is an integer number of cents, so 1035 means $10.35.
  - `qty` (Integer, required): The qty of units for the line item.
  - `total` (MoneyCent, required): The total price of the line item. Should equal `unitPrice * qty`. This is an integer number of cents, so 1035 means $10.35.
  - `item` (String): The _id of the item.
- `invoiceDate` (Date): The date of the invoice. If set in the future, the request will not be sent until that date. Defaults to today if left blank. - format: `YYYY-MM-DD`
- `dueDate` (Date): The date the invoice is due. Will be overwritten if `invoiceTermName` is set and returns a different due date. - format: `YYYY-MM-DD`
- `expireAt` (Date): The date the invoice will expire. The request will be cancelled if it hasn't been completed. - format: `YYYY-MM-DD`
- `poNumber` (String): The unique purchase order number assigned from the source system and displayed to the customer on the invoice.
- `customerMemo` (String): A note presented to the customer on the bottom of the invoice.
- `internalMemo` (String): A memo added to the bottom of the invoice. Only visible to internal staff, never displayed to customers.
- `webhookUrl` (URL): The url to post to when certain actions are performed on the invoice. Notifications will be sent when a text/email fails, a customer clicks a link, or they make a payment.
- `createdAt` (Date): The date the invoice was created.
- `attachmentRefs` (Object): A list of attachments.
  - `internal` (Attachment): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String): The _id of the attachment.
  - `external` (Attachment): External attachments that are sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String): The _id of the attachment.
  - `sourceDocument` (Attachment): The original PDF from a source system. This is only applicable for documents that were created by our PDF parser.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String): The _id of the attachment.
- `customerUrl` (URL): The customer-facing link to view and pay the invoice. This is the same link the customer receives when the invoice is sent to them.
- `customer` (String): The _id of the customer
- `billToCustomer` (String): The _id of the customer to bill.
- `billTo` (Object): Optional overrides for the Bill To section of the invoice. If <b>billToCustomer</b> is provided, this object will be merged with the customer's information and can be used to override specific fields. If <b>billToCustomer</b> is not provided, the fields in this object will be used as the Bill To information on the invoice.
  - `name` (String): Override the name displayed on the invoice in the Bill To section
  - `attn` (String): Override the attention to (e.g. Attn: John Doe) displayed on the invoice in the Bill To section
  - `address` (Address): Override the address displayed on the invoice in the Bill To section
    - `addressLine1` (String): The street address
    - `addressLine2` (String): Suite or apartment #
    - `city` (String): The city
    - `stateCode` (String): 2-digit state abbreviation code
    - `zipCode` (String): 5-digit zip code or postal code
  - `emails` (Object): Override the email addresses to send the invoice to
    - `name` (String): The name of the email recipient.
    - `address` (String): The email address of the recipient.
    - `as` (String): Whether the email should be sent as a 'to', 'cc', or 'bcc' to the recipient. - format: `to | cc | bcc`
  - `sms` (Object): Override the phone numbers to text the invoice to
    - `name` (String): The name of the SMS recipient.
    - `number` (String): The phone number of the recipient.
- `soldTo` (Object): Optional overrides for the Sold To / Customer section of the invoice.
  - `name` (String): Override the name displayed on the invoice in the Sold To section
  - `attn` (String): Override the attention to (e.g. Attn: John Doe) displayed on the invoice in the Sold To section
  - `address` (Address): Override the address displayed on the invoice in the Sold To section
    - `addressLine1` (String): The street address
    - `addressLine2` (String): Suite or apartment #
    - `city` (String): The city
    - `stateCode` (String): 2-digit state abbreviation code
    - `zipCode` (String): 5-digit zip code or postal code
- `payments` (String): The _ids of the payments associated with this invoice.
- `deleted` (Boolean): This flag represents whether the record is deleted and no longer available to be used.

#### Example Response
```json
{
  "_id": "61f32dc2f62bdc6a48945067",
  "externalId": "439772921",
  "invoiceNumber": "12345",
  "totals": {
    "taxes": 285,
    "discounts": 0,
    "total": 3285
  },
  "customer": "61f32dc2f62bdc6a48951255",
  "billToCustomer": "61f32dc2f62bdc6a48951255",
  "billTo": {
    "name": "John Doe",
    "attn": "",
    "address": {},
    "emails": [],
    "sms": []
  },
  "soldTo": {
    "name": "John Doe",
    "attn": "",
    "address": {}
  },
  "invoiceTermName": null,
  "lines": [
    {
      "name": "Mens Large T-shirt",
      "description": "",
      "qty": 2,
      "unitPrice": 1500,
      "total": 3000,
      "item": "62166eda3a8c0517866b9b46"
    }
  ],
  "invoiceDate": "2022-12-01T00:00:00.000Z",
  "dueDate": "2022-12-01T00:00:00.000Z",
  "expireAt": "2023-01-01",
  "poNumber": "",
  "customerMemo": "Thank you for your business!",
  "internalMemo": "",
  "payments": [
    "62166eda3a8c0517866b9c23"
  ],
  "attachmentRefs": {
    "internal": [],
    "external": [],
    "sourceDocument": null
  },
  "webhookUrl": "https://yourcompany.com/webhook",
  "customerUrl": "https://site.url/L-KA39TI45JLMN",
  "createdAt": "2025-05-30T19:19:44.143Z",
  "deleted": false
}
```



### Invoices

Get multiple Invoices

`GET {base_url}/api/v4/site/{site_id}/invoices?updated_after={updated_after}`

#### Query Parameters
- `updated_after` (Date, optional): A timestamp to be used as the start of the date range (exclusive) of the query. On subsequent requests, you should pass in the <b>nextUpdatedAfter</b> value that was in the response of the previous request. Queries look back a maximum of 7 days. A timestamp older than that is moved forward to the limit rather than rejected, so records that last changed before it are not returned. Omitting this parameter returns the last 7 days. An integration that sends back the <b>nextUpdatedAfter</b> of each response never reaches the limit. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`

#### Response Fields
- `recordsMatched` (Number): The number of records that matched the query parameters.
- `recordsReturned` (Number): The number of records that were returned.
- `nextUpdatedAfter` (Date): A timestamp to be used as the start of the date range (exclusive) of the next query for the same endpoint. This is used for pagination when querying with an updated_after parameter. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `queryTime` (Date): The time the query ran. nextUpdatedAfter is derived from it, so it is the same value whenever a full page was returned. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `limit` (Number): The maximum number of records a single response will return. When recordsReturned equals this, more records are likely waiting and another request should be made with the returned nextUpdatedAfter.
- `records` (Invoice): The list of contacts that matched the query parameters.
  - `_id` (String): The id of the invoice. This field is auto generated by the system and is not required when creating a new invoice, but it is required when updating an existing invoice.
  - `externalId` (String): The unique invoice id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
  - `invoiceNumber` (String, required): The unique number assigned from the source system and displayed to the customer on the invoice.
  - `totals` (Totals, required): The total amounts on the invoice. When `lines` are supplied, `total` is validated against them and must equal the sum of every `lines[].total`, plus `taxes`, minus `discounts`. A request whose totals do not reconcile is rejected. Omit `lines` and no such check is made.
    - `taxes` (MoneyCent): The tax amount on the invoice. This is an integer number of cents, so 1035 means $10.35.
    - `discounts` (MoneyCent): The amount to discount off of the total. This is an integer number of cents, so 1035 means $10.35.
    - `subtotal` (MoneyCent): The invoice amount before taxes and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you. This is an integer number of cents, so 1035 means $10.35.
    - `total` (MoneyCent, required): The total amount of the invoice (including tax and subtracting discounts). This is an integer number of cents, so 1035 means $10.35.
  - `customer` (Customer): A reference to the customer record. Omit this field to receive a link to the invoice.
    - `_id` (String): The id of the customer. This field is auto generated by the system and is not required when creating a new customer, but it is required when updating an existing customer.
    - `externalId` (String): The unique customer id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
    - `displayName` (String): The name that will be displayed for the customer.
    - `accountName` (String): A business name or address for the customer, useful when the customer is a group. Required if more than one entry is provided in `contacts`.
    - `primaryContact` (Object): The customers primary contact information. Required if no `contacts` are provided.
      - `firstName` (String): The first name of the customer. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
      - `lastName` (String): The last name of the customer. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
      - `displayName` (String): The name that will be displayed for the contact. If left blank, it will default to the first and last name. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
      - `mobilePhone` (String): The customers mobile phone number. Supports comma separated multiple phone numbers if necessary. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
      - `email` (String): The customers email address. Supports comma separated multiple emails if necessary. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
      - `billingAddress` (Address): The business address of this site/business.
        - `addressLine1` (String): The street address
        - `addressLine2` (String): Suite or apartment #
        - `city` (String): The city
        - `stateCode` (String): 2-digit state abbreviation code
        - `zipCode` (String): 5-digit zip code or postal code
      - `shippingAddress` (Address): The business address of this site/business.
        - `addressLine1` (String): The street address
        - `addressLine2` (String): Suite or apartment #
        - `city` (String): The city
        - `stateCode` (String): 2-digit state abbreviation code
        - `zipCode` (String): 5-digit zip code or postal code
    - `contacts` (Object): A list of customer contacts. Required if `primaryContact` is not passed in.
      - `_id` (String): The id of a previously inserted contact.
      - `isPrimary` (Boolean): A flag indicating whether this contact is the primary contact. If not passed in the request, the first contact will be set as the primary contact by default.
      - `roles` (String): The role(s) that this contact fulfills for the customer. For example: "accounting", "technical", etc. This is for informational purposes only and does not impact functionality in any way.
    - `parentCustomer` (Object): The parent customer, if applicable. A bare `_id` string is also accepted.
      - `_id` (String): The id of the parent customer.
      - `externalId` (String): The `externalId` of the parent customer, which can be sent instead of its `_id`.
    - `billToParentFlag` (Boolean): A flag indicating whether the parent customer should be billed for this customer. Only applicable if `parentCustomer` is provided.
    - `notes` (String): Internal customer notes. Visible to merchant only.
    - `attachmentRefs` (AttachmentRefs): A list of attachments.
      - `internal` (Attachment): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
        - `url` (URL, required): Source url of the attachment.
        - `fileName` (String, required): The name of the file including the extension.
        - `size` (Number): Size of the attachment in bytes.
        - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
        - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
        - `ref` (String): The _id of the attachment.
      - `external` (Attachment): External attachments that are sent to the customer.
        - `url` (URL, required): Source url of the attachment.
        - `fileName` (String, required): The name of the file including the extension.
        - `size` (Number): Size of the attachment in bytes.
        - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
        - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
        - `ref` (String): The _id of the attachment.
    - `deleted` (Boolean): Whether the customer record has been deleted and is no longer active.
  - `invoiceTermName` (String): The invoice term name for the invoice. Defaults to the customer invoice term if it exists, unless `null` is passed in.
  - `lines` (InvoiceLine): A list of line items on the invoice. Required if `description` is not passed in.
    - `name` (String): The name of the product or service. Required if <b>item</b> is not passed in.
    - `description` (String): A description of the product or service.
    - `unitPrice` (MoneyCent, required): The price per unit of the line item. This is an integer number of cents, so 1035 means $10.35.
    - `qty` (Integer, required): The qty of units for the line item.
    - `total` (MoneyCent, required): The total price of the line item. Should equal `unitPrice * qty`. This is an integer number of cents, so 1035 means $10.35.
    - `item` (String): The _id of the item.
  - `description` (String): A short description of the products/services on the invoice. Required if `lines` are not passed in.
  - `invoiceDate` (Date): The date of the invoice. If set in the future, the request will not be sent until that date. Defaults to today if left blank. - format: `YYYY-MM-DD`
  - `dueDate` (Date): The date the invoice is due. Will be overwritten if `invoiceTermName` is set and returns a different due date. - format: `YYYY-MM-DD`
  - `expireAt` (Date): The date the invoice will expire. The request will be cancelled if it hasn't been completed. - format: `YYYY-MM-DD`
  - `poNumber` (String): The unique purchase order number assigned from the source system and displayed to the customer on the invoice.
  - `customerMemo` (String): A note presented to the customer on the bottom of the invoice.
  - `internalMemo` (String): A memo added to the bottom of the invoice. Only visible to internal staff, never displayed to customers.
  - `payments` (Payment): A list of payments made on the invoice.
    - `_id` (String): The id of the payment. This field is auto generated by the system and is not required when creating a new payment, but it is required when updating an existing payment.
    - `externalId` (String): The unique payment id from the source system/database. Required when `_id` is not passed in. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
    - `displayName` (String, required): The secure friendly display name of the payment method. Example: `VISA **** 3421`.
    - `amount` (MoneyCent, required): The amount that was paid. This is an integer number of cents, so 1035 means $10.35.
    - `paidOn` (Date, required): The date and time of when the payment was made. - format: `YYYY-MM-DDTHH:mm:ssZ`
    - `gatewayTransactionId` (String): The unique id that was assigned to the payment record from the gateway when the payment was processed.
    - `invoice` (Object): A reference to the invoice record. On a write this is how the payment is applied to an invoice; it is echoed back on a read, alongside the fuller `allocations` list.
      - `externalId` (String): The `externalId` used in the `Add/Update Invoice` call.
      - `_id` (String): The id of the invoice.
    - `allowMissingInvoice` (Boolean): When `invoice.externalId` names an invoice that has not been sent yet, save the payment without applying it instead of rejecting it. An `Add/Update Invoice` call with that `externalId` within 30 days applies the payment to it. Without this, the payment is rejected with `Invoice was not found` and nothing is saved.
    - `status` (String): The current status of the payment. - format: `declined | authorized | captured | voided | settled | returned | refundFailed | refunded | refundSettled`
    - `site` (String): The _id of the site
    - `type` (String): The type of payment method used to make the payment. - format: `payment_card | ach | cash | check`
    - `subType` (String): The sub type of the payment method used to make the payment. - format: `checking | savings | visa | mastercard | discover | amex | cash | other`
    - `totals` (Totals): The total amounts of the payment.
      - `taxes` (MoneyCent): The tax amount on the invoice. This is an integer number of cents, so 1035 means $10.35.
      - `discounts` (MoneyCent): The amount to discount off of the total. This is an integer number of cents, so 1035 means $10.35.
      - `subtotal` (MoneyCent): The invoice amount before taxes and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you. This is an integer number of cents, so 1035 means $10.35.
      - `total` (MoneyCent, required): The total amount of the invoice (including tax and subtracting discounts). This is an integer number of cents, so 1035 means $10.35.
    - `allocations` (Object): The allocations for the payment. This is an array of objects that specify how the payment was allocated to different orders or refunds.
      - `refType` (String): The type of the reference.
      - `ref` (String): The id of the reference.
      - `amount` (MoneyCent): The amount allocated to the reference. This is an integer number of cents, so 1035 means $10.35.
    - `deleted` (Boolean): This flag represents whether the record is deleted and no longer available to be used.
  - `webhookUrl` (URL): The url to post to when certain actions are performed on the invoice. Notifications will be sent when a text/email fails, a customer clicks a link, or they make a payment.
  - `options` (Object): Options to set on the invoice.
    - `tippingEnabled` (Boolean): Whether tipping/gratuity should be requested on the invoice.
    - `cashDiscountDisabled` (Boolean): If set to `true`, cash discount will be disabled for the invoice.
    - `resend` (Boolean): If set to `true` and performing an update, the invoice will be re-sent to the customer.
  - `attachmentRefs` (Object): A list of attachments.
    - `internal` (Attachment): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
      - `url` (URL, required): Source url of the attachment.
      - `fileName` (String, required): The name of the file including the extension.
      - `size` (Number): Size of the attachment in bytes.
      - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
      - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
      - `ref` (String): The _id of the attachment.
    - `external` (Attachment): External attachments that are sent to the customer.
      - `url` (URL, required): Source url of the attachment.
      - `fileName` (String, required): The name of the file including the extension.
      - `size` (Number): Size of the attachment in bytes.
      - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
      - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
      - `ref` (String): The _id of the attachment.
    - `sourceDocument` (Attachment): The original PDF from a source system. This is only applicable for documents that were created by our PDF parser.
      - `url` (URL, required): Source url of the attachment.
      - `fileName` (String, required): The name of the file including the extension.
      - `size` (Number): Size of the attachment in bytes.
      - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
      - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
      - `ref` (String): The _id of the attachment.
  - `billToCustomer` (Customer): The customer to bill, if different than the <b>customer</b>.
    - `_id` (String): The unique _id of the customer to bill. If provided, the invoice will be billed to this customer and sent to their email and/or mobile phone number on file. Otherwise, this field will automatically be populated if the selected customer has a <b>parentCustomer</b> assigned and <b>billToParentFlag</b> is set.
  - `billTo` (Object): Optional overrides for the Bill To section of the invoice. If <b>billToCustomer</b> is provided, this object will be merged with the customer's information and can be used to override specific fields. If <b>billToCustomer</b> is not provided, the fields in this object will be used as the Bill To information on the invoice.
    - `name` (String): Override the name displayed on the invoice in the Bill To section
    - `attn` (String): Override the attention to (e.g. Attn: John Doe) displayed on the invoice in the Bill To section
    - `address` (Address): Override the address displayed on the invoice in the Bill To section
      - `addressLine1` (String): The street address
      - `addressLine2` (String): Suite or apartment #
      - `city` (String): The city
      - `stateCode` (String): 2-digit state abbreviation code
      - `zipCode` (String): 5-digit zip code or postal code
    - `emails` (Object): Override the email addresses to send the invoice to
      - `name` (String): The name of the email recipient.
      - `address` (String): The email address of the recipient.
      - `as` (String): Whether the email should be sent as a 'to', 'cc', or 'bcc' to the recipient. - format: `to | cc | bcc`
    - `sms` (Object): Override the phone numbers to text the invoice to
      - `name` (String): The name of the SMS recipient.
      - `number` (String): The phone number of the recipient.
  - `soldTo` (Object): Optional overrides for the Sold To / Customer section of the invoice.
    - `name` (String): Override the name displayed on the invoice in the Sold To section
    - `attn` (String): Override the attention to (e.g. Attn: John Doe) displayed on the invoice in the Sold To section
    - `address` (Address): Override the address displayed on the invoice in the Sold To section
      - `addressLine1` (String): The street address
      - `addressLine2` (String): Suite or apartment #
      - `city` (String): The city
      - `stateCode` (String): 2-digit state abbreviation code
      - `zipCode` (String): 5-digit zip code or postal code
  - `deleted` (Boolean): This flag represents whether the record is deleted and no longer available to be used.
- `success` (Boolean): Whether the query completed successfully.



## Customers

### Add/Update Customer

Add or Update a Customer

`POST {base_url}/api/v4/site/{site_id}/customer/addUpdate`

#### Request Fields
- `_id` (String, optional): The id of the customer. This field is auto generated by the system and is not required when creating a new customer, but it is required when updating an existing customer.
- `externalId` (String, optional): The unique customer id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `displayName` (String, optional): The name that will be displayed for the customer.
- `accountName` (String, optional): A business name or address for the customer, useful when the customer is a group. Required if more than one entry is provided in `contacts`.
- `primaryContact` (Object, optional): The customers primary contact information. Required if no `contacts` are provided.
  - `firstName` (String, optional): The first name of the customer. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
  - `lastName` (String, optional): The last name of the customer. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
  - `displayName` (String, optional): The name that will be displayed for the contact. If left blank, it will default to the first and last name. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
  - `mobilePhone` (String, optional): The customers mobile phone number. Supports comma separated multiple phone numbers if necessary. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
  - `email` (String, optional): The customers email address. Supports comma separated multiple emails if necessary. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
  - `billingAddress` (Address, optional): The business address of this site/business.
    - `addressLine1` (String, optional): The street address
    - `addressLine2` (String, optional): Suite or apartment #
    - `city` (String, optional): The city
    - `stateCode` (String, optional): 2-digit state abbreviation code
    - `zipCode` (String, optional): 5-digit zip code or postal code
  - `shippingAddress` (Address, optional): The business address of this site/business.
    - `addressLine1` (String, optional): The street address
    - `addressLine2` (String, optional): Suite or apartment #
    - `city` (String, optional): The city
    - `stateCode` (String, optional): 2-digit state abbreviation code
    - `zipCode` (String, optional): 5-digit zip code or postal code
- `contacts` (Object, optional): A list of customer contacts. Required if `primaryContact` is not passed in.
  - `_id` (String, optional): The id of a previously inserted contact.
  - `isPrimary` (Boolean, optional): A flag indicating whether this contact is the primary contact. If not passed in the request, the first contact will be set as the primary contact by default.
  - `roles` (String, optional): The role(s) that this contact fulfills for the customer. For example: "accounting", "technical", etc. This is for informational purposes only and does not impact functionality in any way.
- `parentCustomer` (Object, optional): The parent customer, if applicable. A bare `_id` string is also accepted.
  - `_id` (String, optional): The id of the parent customer.
  - `externalId` (String, optional): The `externalId` of the parent customer, which can be sent instead of its `_id`.
- `billToParentFlag` (Boolean, optional): A flag indicating whether the parent customer should be billed for this customer. Only applicable if `parentCustomer` is provided.
- `notes` (String, optional): Internal customer notes. Visible to merchant only.
- `attachmentRefs` (AttachmentRefs, optional): A list of attachments.
  - `internal` (Attachment, optional): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number, optional): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String, optional): The _id of the attachment.
  - `external` (Attachment, optional): External attachments that are sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number, optional): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String, optional): The _id of the attachment.
- `deleted` (Boolean, optional): Whether the customer record has been deleted and is no longer active.

#### Example Request
```json
{
  "externalId": "39772634",
  "displayName": "ABC Plumbing",
  "primaryContact": {
    "firstName": "John",
    "lastName": "Doe",
    "mobilePhone": "333-444-5555",
    "email": "johndoe@abc.com",
    "billingAddress": {
      "addressLine1": "123 Main Street",
      "addressLine2": "Suite 123",
      "city": "Naples",
      "stateCode": "FL",
      "zipCode": "34102"
    }
  }
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `updatedAt` (Date): The date the record was last updated.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}
```



### Customer

Get a Customer

`GET {base_url}/api/v4/site/{site_id}/customer/{_id}`

#### Response Fields
- `_id` (String): The id of the customer. This field is auto generated by the system and is not required when creating a new customer, but it is required when updating an existing customer.
- `externalId` (String): The unique customer id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `displayName` (String): The name that will be displayed for the customer.
- `accountName` (String): A business name or address for the customer, useful when the customer is a group. Required if more than one entry is provided in `contacts`.
- `contacts` (Object): A list of customer contacts. Required if `primaryContact` is not passed in.
  - `_id` (String): The id of a previously inserted contact.
  - `isPrimary` (Boolean): A flag indicating whether this contact is the primary contact. If not passed in the request, the first contact will be set as the primary contact by default.
  - `roles` (String): The role(s) that this contact fulfills for the customer. For example: "accounting", "technical", etc. This is for informational purposes only and does not impact functionality in any way.
- `parentCustomer` (String): The id of the parent customer, if applicable.
- `billToParentFlag` (Boolean): A flag indicating whether the parent customer should be billed for this customer. Only applicable if `parentCustomer` is provided.
- `notes` (String): Internal customer notes. Visible to merchant only.
- `attachmentRefs` (AttachmentRefs): A list of attachments.
  - `internal` (Attachment): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String): The _id of the attachment.
  - `external` (Attachment): External attachments that are sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String): The _id of the attachment.
- `createdAt` (Date): The date the customer was created.
- `updatedAt` (Date): The date the customer was last updated.
- `deleted` (Boolean): Whether the customer record has been deleted and is no longer active.

#### Example Response
```json
{
  "_id": "6839e415564d3cc2160d945e",
  "externalId": "39772634",
  "displayName": "ABC Plumbing",
  "accountName": null,
  "contacts": [
    {
      "_id": "6839e415564d3cc216032361",
      "isPrimary": true,
      "roles": []
    }
  ],
  "billToParentFlag": false,
  "notes": null,
  "attachmentRefs": {
    "internal": [],
    "external": []
  },
  "deleted": false,
  "createdAt": "2025-05-30T19:19:44.143Z",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}
```



### Customers

Get multiple Customers

`GET {base_url}/api/v4/site/{site_id}/customers?updated_after={updated_after}`

#### Query Parameters
- `updated_after` (Date, optional): A timestamp to be used as the start of the date range (exclusive) of the query. On subsequent requests, you should pass in the <b>nextUpdatedAfter</b> value that was in the response of the previous request. Queries look back a maximum of 7 days. A timestamp older than that is moved forward to the limit rather than rejected, so records that last changed before it are not returned. Omitting this parameter returns the last 7 days. An integration that sends back the <b>nextUpdatedAfter</b> of each response never reaches the limit. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`

#### Response Fields
- `recordsMatched` (Number): The number of records that matched the query parameters.
- `recordsReturned` (Number): The number of records that were returned.
- `nextUpdatedAfter` (Date): A timestamp to be used as the start of the date range (exclusive) of the next query for the same endpoint. This is used for pagination when querying with an updated_after parameter. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `queryTime` (Date): The time the query ran. nextUpdatedAfter is derived from it, so it is the same value whenever a full page was returned. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `limit` (Number): The maximum number of records a single response will return. When recordsReturned equals this, more records are likely waiting and another request should be made with the returned nextUpdatedAfter.
- `records` (Customer): The list of contacts that matched the query parameters.
  - `_id` (String): The id of the customer. This field is auto generated by the system and is not required when creating a new customer, but it is required when updating an existing customer.
  - `externalId` (String): The unique customer id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
  - `displayName` (String): The name that will be displayed for the customer.
  - `accountName` (String): A business name or address for the customer, useful when the customer is a group. Required if more than one entry is provided in `contacts`.
  - `primaryContact` (Object): The customers primary contact information. Required if no `contacts` are provided.
    - `firstName` (String): The first name of the customer. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
    - `lastName` (String): The last name of the customer. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
    - `displayName` (String): The name that will be displayed for the contact. If left blank, it will default to the first and last name. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
    - `mobilePhone` (String): The customers mobile phone number. Supports comma separated multiple phone numbers if necessary. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
    - `email` (String): The customers email address. Supports comma separated multiple emails if necessary. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
    - `billingAddress` (Address): The business address of this site/business.
      - `addressLine1` (String): The street address
      - `addressLine2` (String): Suite or apartment #
      - `city` (String): The city
      - `stateCode` (String): 2-digit state abbreviation code
      - `zipCode` (String): 5-digit zip code or postal code
    - `shippingAddress` (Address): The business address of this site/business.
      - `addressLine1` (String): The street address
      - `addressLine2` (String): Suite or apartment #
      - `city` (String): The city
      - `stateCode` (String): 2-digit state abbreviation code
      - `zipCode` (String): 5-digit zip code or postal code
  - `contacts` (Object): A list of customer contacts. Required if `primaryContact` is not passed in.
    - `_id` (String): The id of a previously inserted contact.
    - `isPrimary` (Boolean): A flag indicating whether this contact is the primary contact. If not passed in the request, the first contact will be set as the primary contact by default.
    - `roles` (String): The role(s) that this contact fulfills for the customer. For example: "accounting", "technical", etc. This is for informational purposes only and does not impact functionality in any way.
  - `parentCustomer` (Object): The parent customer, if applicable. A bare `_id` string is also accepted.
    - `_id` (String): The id of the parent customer.
    - `externalId` (String): The `externalId` of the parent customer, which can be sent instead of its `_id`.
  - `billToParentFlag` (Boolean): A flag indicating whether the parent customer should be billed for this customer. Only applicable if `parentCustomer` is provided.
  - `notes` (String): Internal customer notes. Visible to merchant only.
  - `attachmentRefs` (AttachmentRefs): A list of attachments.
    - `internal` (Attachment): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
      - `url` (URL, required): Source url of the attachment.
      - `fileName` (String, required): The name of the file including the extension.
      - `size` (Number): Size of the attachment in bytes.
      - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
      - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
      - `ref` (String): The _id of the attachment.
    - `external` (Attachment): External attachments that are sent to the customer.
      - `url` (URL, required): Source url of the attachment.
      - `fileName` (String, required): The name of the file including the extension.
      - `size` (Number): Size of the attachment in bytes.
      - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
      - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
      - `ref` (String): The _id of the attachment.
  - `deleted` (Boolean): Whether the customer record has been deleted and is no longer active.
- `success` (Boolean): Whether the query completed successfully.



## Contacts

### Add/Update Contact

Add or Update a Contact

`POST {base_url}/api/v4/site/{site_id}/contact/addUpdate`

#### Request Fields
- `_id` (String, optional): The id of the contact. This field is auto generated by the system and is not required when creating a new contact, but it is required when updating an existing contact.
- `externalId` (String, optional): The unique contact id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `firstName` (String, optional): The first name of the contact.
- `lastName` (String, optional): The last name of the contact.
- `displayName` (String, optional): The name that will be displayed for the contact. If left blank, it will default to the first and last name.
- `language` (String, optional): The preferred language for the contact. Uses ISO 639-1 language codes.
- `emails` (Object, optional): A list of email addresses for the contact.
  - `label` (String, optional): The label for the email address. - format: `personal | work | other`
  - `address` (Email, required): The email address.
  - `isPrimary` (Boolean, optional): Whether this is the primary email address for the contact.
  - `doNotContact` (Boolean, optional): Whether to exclude this email address from communications.
- `phoneNumbers` (Object, optional): A list of phone numbers for the contact.
  - `label` (String, optional): The label for the phone number. - format: `mobile | home | work | other`
  - `number` (Phone, required): The phone number.
  - `isPrimary` (Boolean, optional): Whether this is the primary phone number for the contact.
  - `extension` (String, optional): The extension for the phone number.
  - `doNotContact` (Boolean, optional): Whether to exclude this phone number from communications.
- `addresses` (Object, optional): A list of addresses for the contact.
  - `label` (String, optional): The label for the address. - format: `billing | shipping | other`
  - `isPrimary` (Boolean, optional): Whether this is the primary address for the contact.
  - `address` (Address, required): The address details.
    - `addressLine1` (String, optional): The street address
    - `addressLine2` (String, optional): Suite or apartment #
    - `city` (String, optional): The city
    - `stateCode` (String, optional): 2-digit state abbreviation code
    - `zipCode` (String, optional): 5-digit zip code or postal code

#### Example Request
```json
{
  "externalId": "58810342",
  "firstName": "John",
  "lastName": "Doe",
  "displayName": "John Doe",
  "language": "en",
  "emails": [
    {
      "label": "work",
      "address": "johndoe@abc.com",
      "isPrimary": true
    }
  ],
  "phoneNumbers": [
    {
      "label": "mobile",
      "number": "333-444-5555",
      "isPrimary": true
    }
  ],
  "addresses": [
    {
      "label": "billing",
      "isPrimary": true,
      "address": {
        "addressLine1": "123 Main Street",
        "addressLine2": "Suite 123",
        "city": "Naples",
        "stateCode": "FL",
        "zipCode": "34102"
      }
    }
  ]
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `updatedAt` (Date): The date the record was last updated.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}
```



### Contact

Get a Contact

`GET {base_url}/api/v4/site/{site_id}/contact/{_id}`

#### Response Fields
- `_id` (String): The id of the contact. This field is auto generated by the system and is not required when creating a new contact, but it is required when updating an existing contact.
- `externalId` (String): The unique contact id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `firstName` (String): The first name of the contact.
- `lastName` (String): The last name of the contact.
- `displayName` (String): The name that will be displayed for the contact. If left blank, it will default to the first and last name.
- `language` (String): The preferred language for the contact. Uses ISO 639-1 language codes.
- `emails` (Object): A list of email addresses for the contact.
  - `label` (String): The label for the email address. - format: `personal | work | other`
  - `address` (Email, required): The email address.
  - `isPrimary` (Boolean): Whether this is the primary email address for the contact.
  - `doNotContact` (Boolean): Whether to exclude this email address from communications.
- `phoneNumbers` (Object): A list of phone numbers for the contact.
  - `label` (String): The label for the phone number. - format: `mobile | home | work | other`
  - `number` (Phone, required): The phone number.
  - `isPrimary` (Boolean): Whether this is the primary phone number for the contact.
  - `extension` (String): The extension for the phone number.
  - `doNotContact` (Boolean): Whether to exclude this phone number from communications.
- `addresses` (Object): A list of addresses for the contact.
  - `label` (String): The label for the address. - format: `billing | shipping | other`
  - `isPrimary` (Boolean): Whether this is the primary address for the contact.
  - `address` (Address, required): The address details.
    - `addressLine1` (String): The street address
    - `addressLine2` (String): Suite or apartment #
    - `city` (String): The city
    - `stateCode` (String): 2-digit state abbreviation code
    - `zipCode` (String): 5-digit zip code or postal code
- `createdAt` (Date): The date the contact was created.
- `updatedAt` (Date): The date the contact was last updated.

#### Example Response
```json
{
  "firstName": "John",
  "lastName": "Doe",
  "displayName": "John Doe",
  "language": "en",
  "emails": [
    {
      "label": "work",
      "address": "johndoe@abc.com",
      "isPrimary": true
    }
  ],
  "phoneNumbers": [
    {
      "label": "mobile",
      "number": "333-444-5555",
      "isPrimary": true
    }
  ],
  "addresses": [
    {
      "label": "billing",
      "isPrimary": true,
      "address": {
        "addressLine1": "123 Main Street",
        "addressLine2": "Suite 123",
        "city": "Naples",
        "stateCode": "FL",
        "zipCode": "34102"
      }
    }
  ],
  "createdAt": "2025-05-30T19:19:44.143Z",
  "updatedAt": "2025-05-30T19:19:44.143Z",
  "_id": "6839e415564d3cc2160d945e",
  "externalId": "58810342"
}
```



### Contacts

Get multiple Contacts

`GET {base_url}/api/v4/site/{site_id}/contacts?updated_after={updated_after}`

#### Query Parameters
- `updated_after` (Date, optional): A timestamp to be used as the start of the date range (exclusive) of the query. On subsequent requests, you should pass in the <b>nextUpdatedAfter</b> value that was in the response of the previous request. Queries look back a maximum of 7 days. A timestamp older than that is moved forward to the limit rather than rejected, so records that last changed before it are not returned. Omitting this parameter returns the last 7 days. An integration that sends back the <b>nextUpdatedAfter</b> of each response never reaches the limit. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`

#### Response Fields
- `recordsMatched` (Number): The number of records that matched the query parameters.
- `recordsReturned` (Number): The number of records that were returned.
- `nextUpdatedAfter` (Date): A timestamp to be used as the start of the date range (exclusive) of the next query for the same endpoint. This is used for pagination when querying with an updated_after parameter. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `queryTime` (Date): The time the query ran. nextUpdatedAfter is derived from it, so it is the same value whenever a full page was returned. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `limit` (Number): The maximum number of records a single response will return. When recordsReturned equals this, more records are likely waiting and another request should be made with the returned nextUpdatedAfter.
- `records` (Contact): The list of contacts that matched the query parameters.
  - `_id` (String): The id of the contact. This field is auto generated by the system and is not required when creating a new contact, but it is required when updating an existing contact.
  - `externalId` (String): The unique contact id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
  - `firstName` (String): The first name of the contact.
  - `lastName` (String): The last name of the contact.
  - `displayName` (String): The name that will be displayed for the contact. If left blank, it will default to the first and last name.
  - `language` (String): The preferred language for the contact. Uses ISO 639-1 language codes.
  - `emails` (Object): A list of email addresses for the contact.
    - `label` (String): The label for the email address. - format: `personal | work | other`
    - `address` (Email, required): The email address.
    - `isPrimary` (Boolean): Whether this is the primary email address for the contact.
    - `doNotContact` (Boolean): Whether to exclude this email address from communications.
  - `phoneNumbers` (Object): A list of phone numbers for the contact.
    - `label` (String): The label for the phone number. - format: `mobile | home | work | other`
    - `number` (Phone, required): The phone number.
    - `isPrimary` (Boolean): Whether this is the primary phone number for the contact.
    - `extension` (String): The extension for the phone number.
    - `doNotContact` (Boolean): Whether to exclude this phone number from communications.
  - `addresses` (Object): A list of addresses for the contact.
    - `label` (String): The label for the address. - format: `billing | shipping | other`
    - `isPrimary` (Boolean): Whether this is the primary address for the contact.
    - `address` (Address, required): The address details.
      - `addressLine1` (String): The street address
      - `addressLine2` (String): Suite or apartment #
      - `city` (String): The city
      - `stateCode` (String): 2-digit state abbreviation code
      - `zipCode` (String): 5-digit zip code or postal code
- `success` (Boolean): Whether the query completed successfully.



## Payments

### Add/Update Payment

Add or Update a Payment

`POST {base_url}/api/v4/site/{site_id}/payment/addUpdate`

#### Request Fields
- `_id` (String, optional): The id of the payment. This field is auto generated by the system and is not required when creating a new payment, but it is required when updating an existing payment.
- `externalId` (String, optional): The unique payment id from the source system/database. Required when `_id` is not passed in. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `displayName` (String, required): The secure friendly display name of the payment method. Example: `VISA **** 3421`.
- `amount` (MoneyCent, required): The amount that was paid. This is an integer number of cents, so 1035 means $10.35.
- `paidOn` (Date, required): The date and time of when the payment was made. - format: `YYYY-MM-DDTHH:mm:ssZ`
- `gatewayTransactionId` (String, optional): The unique id that was assigned to the payment record from the gateway when the payment was processed.
- `invoice` (Object, optional): A reference to the invoice record. On a write this is how the payment is applied to an invoice; it is echoed back on a read, alongside the fuller `allocations` list.
  - `externalId` (String, optional): The `externalId` used in the `Add/Update Invoice` call.
  - `_id` (String, optional): The id of the invoice.
- `allowMissingInvoice` (Boolean, optional): When `invoice.externalId` names an invoice that has not been sent yet, save the payment without applying it instead of rejecting it. An `Add/Update Invoice` call with that `externalId` within 30 days applies the payment to it. Without this, the payment is rejected with `Invoice was not found` and nothing is saved.
- `status` (String, optional): The current status of the payment. - format: `declined | authorized | captured | voided | settled | returned | refundFailed | refunded | refundSettled`
- `site` (String, optional): The _id of the site
- `type` (String, optional): The type of payment method used to make the payment. - format: `payment_card | ach | cash | check`
- `subType` (String, optional): The sub type of the payment method used to make the payment. - format: `checking | savings | visa | mastercard | discover | amex | cash | other`
- `totals` (Totals, optional): The total amounts of the payment.
  - `taxes` (MoneyCent, optional): The tax amount on the invoice. This is an integer number of cents, so 1035 means $10.35.
  - `discounts` (MoneyCent, optional): The amount to discount off of the total. This is an integer number of cents, so 1035 means $10.35.
  - `subtotal` (MoneyCent, optional): The invoice amount before taxes and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you. This is an integer number of cents, so 1035 means $10.35.
  - `total` (MoneyCent, required): The total amount of the invoice (including tax and subtracting discounts). This is an integer number of cents, so 1035 means $10.35.
- `allocations` (Object, optional): The allocations for the payment. This is an array of objects that specify how the payment was allocated to different orders or refunds.
  - `refType` (String, optional): The type of the reference.
  - `ref` (String, optional): The id of the reference.
  - `amount` (MoneyCent, optional): The amount allocated to the reference. This is an integer number of cents, so 1035 means $10.35.
- `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.

#### Example Request
```json
{
  "externalId": "65432325",
  "gatewayTransactionId": "53912387124235234",
  "type": "payment_card",
  "subType": "visa",
  "displayName": "VISA **** 5123",
  "amount": 3515,
  "paidOn": "2021-01-01T14:32:18Z",
  "status": "captured",
  "allocations": [
    {
      "refType": "Invoice",
      "ref": "61f32dc2f62bdc6a48951255",
      "amount": 3515
    }
  ]
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `updatedAt` (Date): The date the record was last updated.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}
```



### Void Payment

Void a Payment

`POST {base_url}/api/v4/site/{site_id}/payment/void`

#### Request Fields
- `id` (String, required): The payment id.
- `reason` (String, optional): Optional reason for the void.

#### Example Request
```json
{
  "id": "64fa4489fb1eaa8e5ae93475"
}
```

#### Response Fields
- `success` (Boolean): Whether the void processed successfully.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true
}
```



### Refund Payment

Refund a Payment

`POST {base_url}/api/v4/site/{site_id}/payment/refund`

#### Request Fields
- `id` (String, required): The payment id.
- `amount` (Number, required): The refunded amount in cents (e.g. 1035 = $10.35).
- `reason` (String, optional): Optional reason for the refund.

#### Example Request
```json
{
  "id": "64fa4489fb1eaa8e5ae93475",
  "amount": 1035
}
```

#### Response Fields
- `success` (Boolean): Whether the refund processed successfully.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true
}
```



### Payment

Get a Payment

`GET {base_url}/api/v4/site/{site_id}/payment/{_id}`

#### Response Fields
- `_id` (String): The id of the payment. This field is auto generated by the system and is not required when creating a new payment, but it is required when updating an existing payment.
- `externalId` (String): The unique payment id from the source system/database. Required when `_id` is not passed in. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `displayName` (String, required): The secure friendly display name of the payment method. Example: `VISA **** 3421`.
- `amount` (MoneyCent, required): The amount that was paid. This is an integer number of cents, so 1035 means $10.35.
- `paidOn` (Date, required): The date and time of when the payment was made. - format: `YYYY-MM-DDTHH:mm:ssZ`
- `status` (String): The current status of the payment. - format: `declined | authorized | captured | voided | settled | returned | refundFailed | refunded | refundSettled`
- `manualStatusChange` (Object): The latest status change a user made by hand in Hyfin, such as marking a payment declined. Use it to tell a manual change apart from one the payment gateway reported. Omitted when no one has changed the payment's status by hand.
  - `eventType` (String): The type of the transaction event whose status was changed, such as `sale` or `refund`.
  - `successful` (Boolean): Whether the change marked the event successful (`true`) or failed (`false`).
  - `changedBy` (String): The name of the user who made the change.
  - `changedAt` (Date): When the change was made.
  - `reason` (String): The reason the user gave for the change.
  - `transactionId` (String): The transaction id the user entered with the change.
- `customer` (String): The _id of the customer who made the payment.
- `site` (String): The _id of the site
- `type` (String): The type of payment method used to make the payment. - format: `payment_card | ach | cash | check`
- `subType` (String): The sub type of the payment method used to make the payment. - format: `checking | savings | visa | mastercard | discover | amex | cash | other`
- `totals` (Totals): The total amounts of the payment.
  - `taxes` (MoneyCent): The tax amount on the invoice. This is an integer number of cents, so 1035 means $10.35.
  - `discounts` (MoneyCent): The amount to discount off of the total. This is an integer number of cents, so 1035 means $10.35.
  - `subtotal` (MoneyCent): The invoice amount before taxes and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you. This is an integer number of cents, so 1035 means $10.35.
  - `total` (MoneyCent, required): The total amount of the invoice (including tax and subtracting discounts). This is an integer number of cents, so 1035 means $10.35.
- `isRefund` (Boolean): Whether the payment is a refund of another payment.
- `origPayment` (String): On a refund, the `_id` of the payment it refunded. Omitted on payments that are not refunds.
- `allocations` (Object): The allocations for the payment. This is an array of objects that specify how the payment was allocated to different orders or refunds.
  - `refType` (String): The type of the reference.
  - `ref` (String): The id of the reference.
  - `amount` (MoneyCent): The amount allocated to the reference. This is an integer number of cents, so 1035 means $10.35.
- `paymentTransactionEvents` (Object): The transaction events for the payment. This is an array of objects that specify the history of the payment transaction, such as when it was authorized, captured, refunded, etc.
  - `type` (String): The type of the transaction event.
  - `amount` (MoneyCent): The amount of the transaction event. This is an integer number of cents, so 1035 means $10.35.
  - `successful` (Boolean): Whether the transaction event was successful or not.
  - `createdAt` (Date): The date and time when the transaction event occurred.
  - `transactionId` (String): The gateway transaction id of the transaction event.

#### Example Response
```json
{
  "_id": "61f32dc2f62bdc6a48945067",
  "externalId": "62331255",
  "displayName": "VISA **** 5123",
  "site": "6201825a0cf5e23261a08646",
  "customer": "649dc5bb468bd5b5d863c7d1",
  "type": "payment_card",
  "subType": "visa",
  "amount": 3515,
  "totals": {
    "taxes": 0,
    "discounts": 0,
    "total": 3515
  },
  "paidOn": "2021-01-01T14:32:18.000Z",
  "status": "captured",
  "isRefund": false,
  "allocations": [
    {
      "refType": "Invoice",
      "ref": "61f32dc2f62bdc6a48951255",
      "amount": 3515
    }
  ],
  "paymentTransactionEvents": [
    {
      "type": "sale",
      "amount": 3515,
      "successful": true,
      "createdAt": "2021-01-01T14:32:18.000Z",
      "transactionId": "53912387124235234"
    }
  ]
}
```



### Payments

Get multiple Payments

`GET {base_url}/api/v4/site/{site_id}/payments?updated_after={updated_after}`

#### Query Parameters
- `updated_after` (Date, optional): A timestamp to be used as the start of the date range (exclusive) of the query. On subsequent requests, you should pass in the <b>nextUpdatedAfter</b> value that was in the response of the previous request. Queries look back a maximum of 7 days. A timestamp older than that is moved forward to the limit rather than rejected, so records that last changed before it are not returned. Omitting this parameter returns the last 7 days. An integration that sends back the <b>nextUpdatedAfter</b> of each response never reaches the limit. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`

#### Response Fields
- `recordsMatched` (Number): The number of records that matched the query parameters.
- `recordsReturned` (Number): The number of records that were returned.
- `nextUpdatedAfter` (Date): A timestamp to be used as the start of the date range (exclusive) of the next query for the same endpoint. This is used for pagination when querying with an updated_after parameter. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `queryTime` (Date): The time the query ran. nextUpdatedAfter is derived from it, so it is the same value whenever a full page was returned. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `limit` (Number): The maximum number of records a single response will return. When recordsReturned equals this, more records are likely waiting and another request should be made with the returned nextUpdatedAfter.
- `records` (Payment): The list of contacts that matched the query parameters.
  - `_id` (String): The id of the payment. This field is auto generated by the system and is not required when creating a new payment, but it is required when updating an existing payment.
  - `externalId` (String): The unique payment id from the source system/database. Required when `_id` is not passed in. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
  - `displayName` (String, required): The secure friendly display name of the payment method. Example: `VISA **** 3421`.
  - `amount` (MoneyCent, required): The amount that was paid. This is an integer number of cents, so 1035 means $10.35.
  - `paidOn` (Date, required): The date and time of when the payment was made. - format: `YYYY-MM-DDTHH:mm:ssZ`
  - `gatewayTransactionId` (String): The unique id that was assigned to the payment record from the gateway when the payment was processed.
  - `invoice` (Object): A reference to the invoice record. On a write this is how the payment is applied to an invoice; it is echoed back on a read, alongside the fuller `allocations` list.
    - `externalId` (String): The `externalId` used in the `Add/Update Invoice` call.
    - `_id` (String): The id of the invoice.
  - `allowMissingInvoice` (Boolean): When `invoice.externalId` names an invoice that has not been sent yet, save the payment without applying it instead of rejecting it. An `Add/Update Invoice` call with that `externalId` within 30 days applies the payment to it. Without this, the payment is rejected with `Invoice was not found` and nothing is saved.
  - `status` (String): The current status of the payment. - format: `declined | authorized | captured | voided | settled | returned | refundFailed | refunded | refundSettled`
  - `site` (String): The _id of the site
  - `type` (String): The type of payment method used to make the payment. - format: `payment_card | ach | cash | check`
  - `subType` (String): The sub type of the payment method used to make the payment. - format: `checking | savings | visa | mastercard | discover | amex | cash | other`
  - `totals` (Totals): The total amounts of the payment.
    - `taxes` (MoneyCent): The tax amount on the invoice. This is an integer number of cents, so 1035 means $10.35.
    - `discounts` (MoneyCent): The amount to discount off of the total. This is an integer number of cents, so 1035 means $10.35.
    - `subtotal` (MoneyCent): The invoice amount before taxes and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you. This is an integer number of cents, so 1035 means $10.35.
    - `total` (MoneyCent, required): The total amount of the invoice (including tax and subtracting discounts). This is an integer number of cents, so 1035 means $10.35.
  - `allocations` (Object): The allocations for the payment. This is an array of objects that specify how the payment was allocated to different orders or refunds.
    - `refType` (String): The type of the reference.
    - `ref` (String): The id of the reference.
    - `amount` (MoneyCent): The amount allocated to the reference. This is an integer number of cents, so 1035 means $10.35.
  - `deleted` (Boolean): This flag represents whether the record is deleted and no longer available to be used.
- `success` (Boolean): Whether the query completed successfully.



## Subscriptions

### Add/Update Subscription

Add or Update a Subscription

`POST {base_url}/api/v4/site/{site_id}/subscription/addUpdate`

#### Request Fields
- `_id` (String, optional): 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.
- `externalId` (String, optional): The unique subscription id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `description` (String, required): A short description of the products/services on the subscription used in the payment request displayed to the customer.
- `amount` (MoneyCent, required): The amount to charge for each billing period. This is an integer number of cents, so 1035 means $10.35.
- `frequency` (String, required): The billing frequency. - format: `Daily | Weekly | Bi-Weekly | Semi-Monthly | Monthly | Quarterly | Semi-Annually | Yearly`
- `frequencyUnits` (Integer, required): Number of frequency units between installments. Ex: `frequency = Yearly` and `frequencyUnits = 2` means every 2 years.
- `customer` (Customer, required): A reference to the customer record.
  - `_id` (String, optional): The id of the customer. This field is auto generated by the system and is not required when creating a new customer, but it is required when updating an existing customer.
  - `externalId` (String, optional): The unique customer id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
  - `displayName` (String, optional): The name that will be displayed for the customer.
  - `accountName` (String, optional): A business name or address for the customer, useful when the customer is a group. Required if more than one entry is provided in `contacts`.
  - `primaryContact` (Object, optional): The customers primary contact information. Required if no `contacts` are provided.
    - `firstName` (String, optional): The first name of the customer. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
    - `lastName` (String, optional): The last name of the customer. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
    - `displayName` (String, optional): The name that will be displayed for the contact. If left blank, it will default to the first and last name. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
    - `mobilePhone` (String, optional): The customers mobile phone number. Supports comma separated multiple phone numbers if necessary. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
    - `email` (String, optional): The customers email address. Supports comma separated multiple emails if necessary. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
    - `billingAddress` (Address, optional): The business address of this site/business.
      - `addressLine1` (String, optional): The street address
      - `addressLine2` (String, optional): Suite or apartment #
      - `city` (String, optional): The city
      - `stateCode` (String, optional): 2-digit state abbreviation code
      - `zipCode` (String, optional): 5-digit zip code or postal code
    - `shippingAddress` (Address, optional): The business address of this site/business.
      - `addressLine1` (String, optional): The street address
      - `addressLine2` (String, optional): Suite or apartment #
      - `city` (String, optional): The city
      - `stateCode` (String, optional): 2-digit state abbreviation code
      - `zipCode` (String, optional): 5-digit zip code or postal code
  - `contacts` (Object, optional): A list of customer contacts. Required if `primaryContact` is not passed in.
    - `_id` (String, optional): The id of a previously inserted contact.
    - `isPrimary` (Boolean, optional): A flag indicating whether this contact is the primary contact. If not passed in the request, the first contact will be set as the primary contact by default.
    - `roles` (String, optional): The role(s) that this contact fulfills for the customer. For example: "accounting", "technical", etc. This is for informational purposes only and does not impact functionality in any way.
  - `parentCustomer` (Object, optional): The parent customer, if applicable. A bare `_id` string is also accepted.
    - `_id` (String, optional): The id of the parent customer.
    - `externalId` (String, optional): The `externalId` of the parent customer, which can be sent instead of its `_id`.
  - `billToParentFlag` (Boolean, optional): A flag indicating whether the parent customer should be billed for this customer. Only applicable if `parentCustomer` is provided.
  - `notes` (String, optional): Internal customer notes. Visible to merchant only.
  - `attachmentRefs` (AttachmentRefs, optional): A list of attachments.
    - `internal` (Attachment, optional): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
      - `url` (URL, required): Source url of the attachment.
      - `fileName` (String, required): The name of the file including the extension.
      - `size` (Number, optional): Size of the attachment in bytes.
      - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
      - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
      - `ref` (String, optional): The _id of the attachment.
    - `external` (Attachment, optional): External attachments that are sent to the customer.
      - `url` (URL, required): Source url of the attachment.
      - `fileName` (String, required): The name of the file including the extension.
      - `size` (Number, optional): Size of the attachment in bytes.
      - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
      - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
      - `ref` (String, optional): The _id of the attachment.
  - `deleted` (Boolean, optional): Whether the customer record has been deleted and is no longer active.
- `startDate` (Date, optional): 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` (Integer, optional): The number of installments to be made. If left blank, the subscription continues indefinitely or until manually closed.
- `webhookUrl` (URL, optional): The url to post to when certain actions are performed on the subscription.
- `attachmentRefs` (AttachmentRefs, optional): A list of attachments.
  - `internal` (Attachment, optional): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number, optional): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String, optional): The _id of the attachment.
  - `external` (Attachment, optional): External attachments that are sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number, optional): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String, optional): The _id of the attachment.
- `billToCustomer` (Object, optional): The customer to bill, if different than the <b>customer</b>.
  - `_id` (String, optional): The unique _id of the customer to bill. If provided, the invoice will be billed to this customer and sent to their email and/or mobile phone number on file. Otherwise, this field will automatically be populated if the selected customer has a <b>parentCustomer</b> assigned and <b>billToParentFlag</b> is set.
- `billTo` (Object, optional): Optional overrides for the Bill To section of the invoice. If <b>billToCustomer</b> is provided, this object will be merged with the customer's information and can be used to override specific fields. If <b>billToCustomer</b> is not provided, the fields in this object will be used as the Bill To information on the invoice.
  - `name` (String, optional): Override the name displayed on the invoice in the Bill To section
  - `attn` (String, optional): Override the attention to (e.g. Attn: John Doe) displayed on the invoice in the Bill To section
  - `address` (Address, optional): Override the address displayed on the invoice in the Bill To section
    - `addressLine1` (String, optional): The street address
    - `addressLine2` (String, optional): Suite or apartment #
    - `city` (String, optional): The city
    - `stateCode` (String, optional): 2-digit state abbreviation code
    - `zipCode` (String, optional): 5-digit zip code or postal code
  - `emails` (Object, optional): Override the email addresses to send the invoice to
    - `name` (String, optional): The name of the email recipient.
    - `address` (String, optional): The email address of the recipient.
    - `as` (String, optional): Whether the email should be sent as a 'to', 'cc', or 'bcc' to the recipient.
  - `sms` (Object, optional): Override the phone numbers to text the invoice to
    - `name` (String, optional): The name of the SMS recipient.
    - `number` (String, optional): The phone number of the recipient.
- `soldTo` (Object, optional): Optional overrides for the Sold To / Customer section of the invoice.
  - `name` (String, optional): Override the name displayed on the invoice in the Sold To section
  - `attn` (String, optional): Override the attention to (e.g. Attn: John Doe) displayed on the invoice in the Sold To section
  - `address` (Address, optional): Override the address displayed on the invoice in the Sold To section
    - `addressLine1` (String, optional): The street address
    - `addressLine2` (String, optional): Suite or apartment #
    - `city` (String, optional): The city
    - `stateCode` (String, optional): 2-digit state abbreviation code
    - `zipCode` (String, optional): 5-digit zip code or postal code
- `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.

#### Example Request
```json
{
  "_id": "61f32dc2f62bdc6a48945067",
  "description": "Gold+ Plan",
  "amount": 3499,
  "frequency": "Monthly",
  "frequencyUnits": 1,
  "customer": {
    "externalId": "39772634",
    "primaryContact": {
      "firstName": "John",
      "lastName": "Doe",
      "mobilePhone": "111-222-3333",
      "email": "johndoe@abc.com"
    }
  },
  "webhookUrl": "https://yourcompany.com/webhook"
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `updatedAt` (Date): The date the record was last updated.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.
- `link` (URL): The link the customer uses to confirm their payment method for the subscription.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z",
  "link": "https//site.url/KA39T1A45JL"
}
```



### Subscription

Get a Subscription

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

#### Response Fields
- `_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.
- `externalId` (String): The unique subscription id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `frequency` (String, required): The billing frequency. - format: `Daily | Weekly | Bi-Weekly | Semi-Monthly | Monthly | Quarterly | Semi-Annually | Yearly`
- `frequencyUnits` (Integer, required): 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` (Integer): 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. - format: `pending | active | paused | failed | closed`
- `webhookUrl` (URL): The url to post to when certain actions are performed on the subscription.
- `attachmentRefs` (AttachmentRefs): A list of attachments.
  - `internal` (Attachment): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String): The _id of the attachment.
  - `external` (Attachment): External attachments that are sent to the customer.
    - `url` (URL, required): Source url of the attachment.
    - `fileName` (String, required): The name of the file including the extension.
    - `size` (Number): Size of the attachment in bytes.
    - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
    - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
    - `ref` (String): The _id of the attachment.
- `customer` (String): The _id of the customer
- `code` (String): The unique code used in the customer-facing link to the subscription.
- `lines` (Object): The line items billed by the subscription. A request that only sends `amount` and `description` gets a single recurring line built from them.
  - `name` (String): The name of the product or service.
  - `description` (String): A description of the product or service.
  - `qty` (Integer): The qty of units for the line item.
  - `unitPrice` (MoneyCent): The price per unit of the line item. This is an integer number of cents, so 1035 means $10.35.
  - `total` (MoneyCent): The total price of the line item. This is an integer number of cents, so 1035 means $10.35.
  - `item` (String): The _id of the item.
  - `isRecurring` (Boolean): Whether the line is billed on every invoice, or only on the first.
- `totalsRecurring` (Totals): The totals of each recurring invoice. `total` is the amount charged each billing period.
  - `taxes` (MoneyCent): The tax amount on the invoice. This is an integer number of cents, so 1035 means $10.35.
  - `discounts` (MoneyCent): The amount to discount off of the total. This is an integer number of cents, so 1035 means $10.35.
  - `subtotal` (MoneyCent): The invoice amount before taxes and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you. This is an integer number of cents, so 1035 means $10.35.
  - `total` (MoneyCent, required): The total amount of the invoice (including tax and subtracting discounts). This is an integer number of cents, so 1035 means $10.35.
- `totalsFirstInvoice` (Totals): The totals of the first invoice, which also includes any one-time lines.
  - `taxes` (MoneyCent): The tax amount on the invoice. This is an integer number of cents, so 1035 means $10.35.
  - `discounts` (MoneyCent): The amount to discount off of the total. This is an integer number of cents, so 1035 means $10.35.
  - `subtotal` (MoneyCent): The invoice amount before taxes and discounts. Optional, and validated on its own when sent: it must equal the sum of every <b>lines[].total</b>. Leave it out and it is derived for you. This is an integer number of cents, so 1035 means $10.35.
  - `total` (MoneyCent, required): The total amount of the invoice (including tax and subtracting discounts). This is an integer number of cents, so 1035 means $10.35.
- `billToCustomer` (String): The _id of the customer to bill.
- `billTo` (Object): Optional overrides for the Bill To section of the invoice. If <b>billToCustomer</b> is provided, this object will be merged with the customer's information and can be used to override specific fields. If <b>billToCustomer</b> is not provided, the fields in this object will be used as the Bill To information on the invoice.
  - `name` (String): Override the name displayed on the invoice in the Bill To section
  - `attn` (String): Override the attention to (e.g. Attn: John Doe) displayed on the invoice in the Bill To section
  - `address` (Address): Override the address displayed on the invoice in the Bill To section
    - `addressLine1` (String): The street address
    - `addressLine2` (String): Suite or apartment #
    - `city` (String): The city
    - `stateCode` (String): 2-digit state abbreviation code
    - `zipCode` (String): 5-digit zip code or postal code
  - `emails` (Object): Override the email addresses to send the invoice to
    - `name` (String): The name of the email recipient.
    - `address` (String): The email address of the recipient.
    - `as` (String): Whether the email should be sent as a 'to', 'cc', or 'bcc' to the recipient.
  - `sms` (Object): Override the phone numbers to text the invoice to
    - `name` (String): The name of the SMS recipient.
    - `number` (String): The phone number of the recipient.
- `soldTo` (Object): Optional overrides for the Sold To / Customer section of the invoice.
  - `name` (String): Override the name displayed on the invoice in the Sold To section
  - `attn` (String): Override the attention to (e.g. Attn: John Doe) displayed on the invoice in the Sold To section
  - `address` (Address): Override the address displayed on the invoice in the Sold To section
    - `addressLine1` (String): The street address
    - `addressLine2` (String): Suite or apartment #
    - `city` (String): The city
    - `stateCode` (String): 2-digit state abbreviation code
    - `zipCode` (String): 5-digit zip code or postal code
- `deleted` (Boolean): This flag represents whether the record is deleted and no longer available to be used.

#### Example Response
```json
{
  "_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": {}
  },
  "deleted": false
}
```



### Subscriptions

Get multiple Subscriptions

`GET {base_url}/api/v4/site/{site_id}/subscriptions?updated_after={updated_after}`

#### Query Parameters
- `updated_after` (Date, optional): A timestamp to be used as the start of the date range (exclusive) of the query. On subsequent requests, you should pass in the <b>nextUpdatedAfter</b> value that was in the response of the previous request. Queries look back a maximum of 7 days. A timestamp older than that is moved forward to the limit rather than rejected, so records that last changed before it are not returned. Omitting this parameter returns the last 7 days. An integration that sends back the <b>nextUpdatedAfter</b> of each response never reaches the limit. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`

#### Response Fields
- `recordsMatched` (Number): The number of records that matched the query parameters.
- `recordsReturned` (Number): The number of records that were returned.
- `nextUpdatedAfter` (Date): A timestamp to be used as the start of the date range (exclusive) of the next query for the same endpoint. This is used for pagination when querying with an updated_after parameter. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `queryTime` (Date): The time the query ran. nextUpdatedAfter is derived from it, so it is the same value whenever a full page was returned. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `limit` (Number): The maximum number of records a single response will return. When recordsReturned equals this, more records are likely waiting and another request should be made with the returned nextUpdatedAfter.
- `records` (Subscription): The list of contacts that matched the query parameters.
  - `_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.
  - `externalId` (String): The unique subscription id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
  - `description` (String, required): A short description of the products/services on the subscription used in the payment request displayed to the customer.
  - `amount` (MoneyCent, required): The amount to charge for each billing period. This is an integer number of cents, so 1035 means $10.35.
  - `frequency` (String, required): The billing frequency. - format: `Daily | Weekly | Bi-Weekly | Semi-Monthly | Monthly | Quarterly | Semi-Annually | Yearly`
  - `frequencyUnits` (Integer, required): Number of frequency units between installments. Ex: `frequency = Yearly` and `frequencyUnits = 2` means every 2 years.
  - `customer` (Customer, required): A reference to the customer record.
    - `_id` (String): The id of the customer. This field is auto generated by the system and is not required when creating a new customer, but it is required when updating an existing customer.
    - `externalId` (String): The unique customer id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
    - `displayName` (String): The name that will be displayed for the customer.
    - `accountName` (String): A business name or address for the customer, useful when the customer is a group. Required if more than one entry is provided in `contacts`.
    - `primaryContact` (Object): The customers primary contact information. Required if no `contacts` are provided.
      - `firstName` (String): The first name of the customer. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
      - `lastName` (String): The last name of the customer. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
      - `displayName` (String): The name that will be displayed for the contact. If left blank, it will default to the first and last name. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
      - `mobilePhone` (String): The customers mobile phone number. Supports comma separated multiple phone numbers if necessary. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
      - `email` (String): The customers email address. Supports comma separated multiple emails if necessary. At least one of `firstName`, `lastName`, `displayName`, `email`, or `mobilePhone` is required.
      - `billingAddress` (Address): The business address of this site/business.
        - `addressLine1` (String): The street address
        - `addressLine2` (String): Suite or apartment #
        - `city` (String): The city
        - `stateCode` (String): 2-digit state abbreviation code
        - `zipCode` (String): 5-digit zip code or postal code
      - `shippingAddress` (Address): The business address of this site/business.
        - `addressLine1` (String): The street address
        - `addressLine2` (String): Suite or apartment #
        - `city` (String): The city
        - `stateCode` (String): 2-digit state abbreviation code
        - `zipCode` (String): 5-digit zip code or postal code
    - `contacts` (Object): A list of customer contacts. Required if `primaryContact` is not passed in.
      - `_id` (String): The id of a previously inserted contact.
      - `isPrimary` (Boolean): A flag indicating whether this contact is the primary contact. If not passed in the request, the first contact will be set as the primary contact by default.
      - `roles` (String): The role(s) that this contact fulfills for the customer. For example: "accounting", "technical", etc. This is for informational purposes only and does not impact functionality in any way.
    - `parentCustomer` (Object): The parent customer, if applicable. A bare `_id` string is also accepted.
      - `_id` (String): The id of the parent customer.
      - `externalId` (String): The `externalId` of the parent customer, which can be sent instead of its `_id`.
    - `billToParentFlag` (Boolean): A flag indicating whether the parent customer should be billed for this customer. Only applicable if `parentCustomer` is provided.
    - `notes` (String): Internal customer notes. Visible to merchant only.
    - `attachmentRefs` (AttachmentRefs): A list of attachments.
      - `internal` (Attachment): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
        - `url` (URL, required): Source url of the attachment.
        - `fileName` (String, required): The name of the file including the extension.
        - `size` (Number): Size of the attachment in bytes.
        - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
        - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
        - `ref` (String): The _id of the attachment.
      - `external` (Attachment): External attachments that are sent to the customer.
        - `url` (URL, required): Source url of the attachment.
        - `fileName` (String, required): The name of the file including the extension.
        - `size` (Number): Size of the attachment in bytes.
        - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
        - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
        - `ref` (String): The _id of the attachment.
    - `deleted` (Boolean): Whether the customer record has been deleted and is no longer active.
  - `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` (Integer): The number of installments to be made. If left blank, the subscription continues indefinitely or until manually closed.
  - `webhookUrl` (URL): The url to post to when certain actions are performed on the subscription.
  - `attachmentRefs` (AttachmentRefs): A list of attachments.
    - `internal` (Attachment): Internal attachments that are only accessible within the merchant dashboard and never sent to the customer.
      - `url` (URL, required): Source url of the attachment.
      - `fileName` (String, required): The name of the file including the extension.
      - `size` (Number): Size of the attachment in bytes.
      - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
      - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
      - `ref` (String): The _id of the attachment.
    - `external` (Attachment): External attachments that are sent to the customer.
      - `url` (URL, required): Source url of the attachment.
      - `fileName` (String, required): The name of the file including the extension.
      - `size` (Number): Size of the attachment in bytes.
      - `mimetype` (String, required): The mimetype of the attachment. e.g. "application/pdf" or "image/png".
      - `externalId` (String, required): An external ID for the attachment. Useful for idempotency when uploading attachments.
      - `ref` (String): The _id of the attachment.
  - `billToCustomer` (Object): The customer to bill, if different than the <b>customer</b>.
    - `_id` (String): The unique _id of the customer to bill. If provided, the invoice will be billed to this customer and sent to their email and/or mobile phone number on file. Otherwise, this field will automatically be populated if the selected customer has a <b>parentCustomer</b> assigned and <b>billToParentFlag</b> is set.
  - `billTo` (Object): Optional overrides for the Bill To section of the invoice. If <b>billToCustomer</b> is provided, this object will be merged with the customer's information and can be used to override specific fields. If <b>billToCustomer</b> is not provided, the fields in this object will be used as the Bill To information on the invoice.
    - `name` (String): Override the name displayed on the invoice in the Bill To section
    - `attn` (String): Override the attention to (e.g. Attn: John Doe) displayed on the invoice in the Bill To section
    - `address` (Address): Override the address displayed on the invoice in the Bill To section
      - `addressLine1` (String): The street address
      - `addressLine2` (String): Suite or apartment #
      - `city` (String): The city
      - `stateCode` (String): 2-digit state abbreviation code
      - `zipCode` (String): 5-digit zip code or postal code
    - `emails` (Object): Override the email addresses to send the invoice to
      - `name` (String): The name of the email recipient.
      - `address` (String): The email address of the recipient.
      - `as` (String): Whether the email should be sent as a 'to', 'cc', or 'bcc' to the recipient.
    - `sms` (Object): Override the phone numbers to text the invoice to
      - `name` (String): The name of the SMS recipient.
      - `number` (String): The phone number of the recipient.
  - `soldTo` (Object): Optional overrides for the Sold To / Customer section of the invoice.
    - `name` (String): Override the name displayed on the invoice in the Sold To section
    - `attn` (String): Override the attention to (e.g. Attn: John Doe) displayed on the invoice in the Sold To section
    - `address` (Address): Override the address displayed on the invoice in the Sold To section
      - `addressLine1` (String): The street address
      - `addressLine2` (String): Suite or apartment #
      - `city` (String): The city
      - `stateCode` (String): 2-digit state abbreviation code
      - `zipCode` (String): 5-digit zip code or postal code
  - `deleted` (Boolean): This flag represents whether the record is deleted and no longer available to be used.
- `success` (Boolean): Whether the query completed successfully.



## Items

### Add/Update Item

Add or Update an Item

`POST {base_url}/api/v4/site/{site_id}/item/addUpdate`

#### Request Fields
- `_id` (String, optional): The id of the item. This field is auto generated by the system and is not required when creating a new item, but it is required when updating an existing item.
- `externalId` (String, optional): The unique item id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `name` (String, required): The name of the item.
- `description` (String, required): The description of the item.
- `unitPrice` (MoneyCent, required): The price per unit of the item. This is an integer number of cents, so 1035 means $10.35.
- `deleted` (Boolean, optional): This flag represents whether the record is deleted and no longer available to be used.

#### Example Request
```json
{
  "_id": "6839e415564d3cc2160d945e",
  "name": "Men's Large T-Shirt",
  "unitPrice": 1499,
  "deleted": false
}
```

#### Response Fields
- `success` (Boolean): Whether the record was added or updated successfully.
- `action` (String): Informs whether the record was added or updated. Will only be returned if `success` is `true`. - format: `added | updated`
- `_id` (String): The auto generated id assigned to the record.
- `updatedAt` (Date): The date the record was last updated.
- `errors` (String): A list of errors. Will only be returned if `success` is `false`.

#### Example Response
```json
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}
```



### Item

Get an Item

`GET {base_url}/api/v4/site/{site_id}/item/{_id}`

#### Response Fields
- `_id` (String): The id of the item. This field is auto generated by the system and is not required when creating a new item, but it is required when updating an existing item.
- `externalId` (String): The unique item id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
- `name` (String, required): The name of the item.
- `description` (String, required): The description of the item.
- `unitPrice` (MoneyCent, required): The price per unit of the item. This is an integer number of cents, so 1035 means $10.35.
- `createdAt` (Date): The date the item was created.
- `updatedAt` (Date): The date the item was last updated.
- `deleted` (Boolean): This flag represents whether the record is deleted and no longer available to be used.

#### Example Response
```json
{
  "_id": "6839e415564d3cc2160d945e",
  "externalId": "439772921",
  "name": "Garlic Soy Tikkudak Wings",
  "description": "Tikkudak is a specialty where fried chicken is baked in a charcoal oven to create a smoky and crispy flavor.",
  "unitPrice": 1500,
  "createdAt": "2025-05-30T19:19:44.143Z",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}
```



### Items

Get multiple Items

`GET {base_url}/api/v4/site/{site_id}/items?updated_after={updated_after}`

#### Query Parameters
- `updated_after` (Date, optional): A timestamp to be used as the start of the date range (exclusive) of the query. On subsequent requests, you should pass in the <b>nextUpdatedAfter</b> value that was in the response of the previous request. Queries look back a maximum of 7 days. A timestamp older than that is moved forward to the limit rather than rejected, so records that last changed before it are not returned. Omitting this parameter returns the last 7 days. An integration that sends back the <b>nextUpdatedAfter</b> of each response never reaches the limit. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`

#### Response Fields
- `recordsMatched` (Number): The number of records that matched the query parameters.
- `recordsReturned` (Number): The number of records that were returned.
- `nextUpdatedAfter` (Date): A timestamp to be used as the start of the date range (exclusive) of the next query for the same endpoint. This is used for pagination when querying with an updated_after parameter. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `queryTime` (Date): The time the query ran. nextUpdatedAfter is derived from it, so it is the same value whenever a full page was returned. - format: `YYYY-MM-DDTHH:mm:ss.SSSZ`
- `limit` (Number): The maximum number of records a single response will return. When recordsReturned equals this, more records are likely waiting and another request should be made with the returned nextUpdatedAfter.
- `records` (Item): The list of contacts that matched the query parameters.
  - `_id` (String): The id of the item. This field is auto generated by the system and is not required when creating a new item, but it is required when updating an existing item.
  - `externalId` (String): The unique item id from the source system/database. If we detect a record with the same `externalId`, it will be updated, otherwise it will be added.
  - `name` (String, required): The name of the item.
  - `description` (String, required): The description of the item.
  - `unitPrice` (MoneyCent, required): The price per unit of the item. This is an integer number of cents, so 1035 means $10.35.
  - `deleted` (Boolean): This flag represents whether the record is deleted and no longer available to be used.
- `success` (Boolean): Whether the query completed successfully.

Source: https://hyfin.app/docs/4.0.md