Balance Update API docs

data/actions.json

@@ -452,6 +452,22 @@
     "extra_msg": "",
     "subject_types": []
   },
+  {
+    "key": "PFI_EXPORT",
+    "value": "PFI_EXPORT",
+    "msg": "Exported Credit Requests",
+    "help_text": "When an Administrator exports data about Credit Requests.",
+    "extra_msg": "",
+    "subject_types": []
+  },
+  {
+    "key": "PO_EXPORT",
+    "value": "PO_EXPORT",
+    "msg": "Exported Payment Orders",
+    "help_text": "When an Administrator exports data about Payment Orders.",
+    "extra_msg": "",
+    "subject_types": []
+  },
   {
     "key": "EDITED_OWN_PROFILE",
     "value": "EDITED_OWN_PROFILE",

pages/api.yml

@@ -54,6 +54,10 @@ endpoint_sections:
     title: Appointments (Lessons)
     id: appointments
     layout: /appointments/appointments.yml
+  -
+    title: Balance Updates
+    id: balance_updates
+    layout: /balance_updates/balance_updates.yml
   -
     title: Branch
     id: branch

pages/balance_updates/balance-update-object.json

@@ -0,0 +1,41 @@
+{
+  "id": 182,
+  "created": "2025-09-30T15:03:58.676657+01:00",
+  "creator": {
+    "id": 6,
+    "first_name": "Thomas",
+    "last_name": "Jackson",
+    "email": "[email protected]",
+    "role_type": "Administrator"
+  },
+  "credit_amount": "-567.50",
+  "description": "Invoice raised",
+  "method": "auto",
+  "related_item": {
+    "id": 54,
+    "display_id": "INV-54",
+    "date_sent": "2025-09-30T15:03:58.623171+01:00",
+    "gross": "567.50",
+    "net": "472.92",
+    "tax": "94.58",
+    "client": {
+      "id": 42,
+      "first_name": "Nicole",
+      "last_name": "Beggs",
+      "email": "[email protected]",
+      "role_type": "Client",
+      "url": "https://secure.tutorcruncher.com/api/clients/42/"
+    },
+    "status": "unpaid",
+    "url": "https://secure.tutorcruncher.com/api/invoices/54/"
+  },
+  "role": {
+    "id": 42,
+    "first_name": "Nicole",
+    "last_name": "Beggs",
+    "email": "[email protected]",
+    "role_type": "Client",
+    "url": "https://secure.tutorcruncher.com/api/clients/42/"
+  },
+  "update_type": "invoice_creation"
+}

pages/balance_updates/balance-update-object.md

@@ -0,0 +1,4 @@
+### Balance Update Object
+
+A Balance Update represents a change in a Users balance. It can be created manually by an Admin or automatically 
+when certain actions occur, such as when a payment is processed.

pages/balance_updates/balance-update-object.yml

@@ -0,0 +1,109 @@
+attributes:
+  -
+    name: id
+    type: integer
+    description: Unique identifier for the balance update.
+  -
+    name: created
+    type: datetime
+    description: The date and time when the balance update was created.
+  -
+    name: creator
+    type: object
+    description: The user who created this balance update.
+    children:
+      - name: id
+        type: integer
+        description: Unique identifier for the object.
+      - name: first_name
+        type: string
+        description: The User's first name.
+      - name: last_name
+        type: string
+        description: The User's last name.
+      - name: email
+        type: string
+        description: The User's email address.
+      - name: role_type
+        type: string
+        description: The role type of the Balance Update creator.
+      - name: url
+        type: string
+        description: URL to the Creator's object. (This field will not be present if the creator is an Administrator)
+  -
+    name: credit_amount
+    type: decimal
+    description: The amount of credit being added or removed from the client's balance.
+  -
+    name: description
+    type: string
+    description: A description explaining the reason for the balance update.
+  -
+    name: method
+    type: string
+    description: The payment method used for the balance update. Options for this field are ['cash', 'cheque', 'credit_card', 'transferwise', 'debit_card', 'bank_transfer', 'direct_debit', 'bonus_credit', 'manual', 'voucher', 'correction'].
+  -
+    name: related_item
+    type: object
+    description: Any related object that this balance update is associated with (nullable).
+  -
+    name: role
+    type: object
+    description: The user whose balance is being updated.
+    children:
+      - name: id
+        type: integer
+        description: Unique identifier for the object.
+      - name: first_name
+        type: string
+        description: User's first name.
+      - name: last_name
+        type: string
+        description: User's last name.
+      - name: email
+        type: string
+        description: User's email address.
+      - name: role_type
+        type: string
+        description: The role type of the User.
+      - name: url
+        type: string
+        description: URL to the User's object.
+  -
+    name: update_type
+    type: string
+    description: The type of update being performed (e.g., "via_api", "manual").
+
+filters:
+  -
+    name: client
+    type: integer
+    description: Filter by the Balance Updates linked Client (id).
+  -
+    name: contractor
+    type: integer
+    description: Filter by the Balance Updates linked Tutor (id).
+  -
+    name: method
+    type: string
+    description: Filter by the Balance Updates method. Options for this field are ['cash', 'cheque', 'credit_card', 'transferwise', 'debit_card', 'bank_transfer', 'direct_debit', 'bonus_credit', 'manual', 'voucher', 'correction']'
+  -
+    name: update_type
+    type: string
+    description: Filter by the Balance Updates update_type. Options for this field are ['proforma_invoice_paid', 'invoice_creation', 'invoice_payment', 'po_creation', 'po_payment', 'adjustment', 'refund', 'stripe_bank_transfer_refund', 'voucher', 'credit_note', 'debit_note', 'via_api', 'top_up', 'app_fee']'
+  -
+    name: credit_amount_gte
+    type: decimal
+    description: Filter by Balance Updates with a credit_amount greater than or equal to this value.
+  -
+    name: credit_amount_lte
+    type: decimal
+    description: Filter by Balance Updates with a credit_amount less than or equal to this value.
+  -
+    name: created_gte
+    type: datetime
+    description: Filter by Balance Updates created on or after this date and time.
+  -
+    name: created_lte
+    type: datetime
+    description: Filter by Balance Updates created on or before this date and time.

pages/balance_updates/balance_updates.yml

@@ -0,0 +1,33 @@
+sections:
+  -
+    title: Balance Update Object
+    id: balance-update-object
+    description: /balance_updates/balance-update-object.md
+    attributes: /balance_updates/balance-update-object.yml
+    response: /balance_updates/balance-update-object.json
+    response_title: OBJECT
+  -
+    title: List all Balance Updates
+    id: list-all-balance-updates
+    description: /balance_updates/list-all-balance-updates.md
+    filters: /balance_updates/balance-update-object.yml
+    code: /balance_updates/list-all-balance-updates.py
+    code_type: GET
+    code_url: /api/balance_updates/
+    response: /balance_updates/list-all-balance-updates.json
+  -
+    title: Get a balance update
+    id: get-a-balance-update
+    description: /balance_updates/get-a-balance-update.md
+    code: /balance_updates/get-a-balance-update.py
+    code_type: GET
+    code_url: /api/balance_updates/{id}/
+    response: /balance_updates/get-a-balance-update.json
+  -
+    title: Create a balance update
+    id: create-a-balance-update
+    description: /balance_updates/create-a-balance-update.md
+    code: /balance_updates/create-a-balance-update.py
+    code_type: POST
+    code_url: /api/balance_updates/
+    response: /balance_updates/create-a-balance-update.json

pages/balance_updates/create-a-balance-update.json

@@ -0,0 +1,25 @@
+{
+  "id": 385,
+  "created": "2025-09-25T10:00:00.000000+01:00",
+  "creator": {
+    "id": 64,
+    "first_name": "Billy",
+    "last_name": "Holiday",
+    "email": "[email protected]",
+    "role_type": "Administrator"
+  },
+  "credit_amount": "100.00",
+  "description": "This is a test description about why the credit was added to this client",
+  "method": "cash",
+  "related_item": null,
+  "role": {
+    "id": 67,
+    "first_name": "Billy",
+    "last_name": "Holiday",
+    "email": "[email protected]",
+    "role_type": "Client",
+    "url": "https://secure.tutorcruncher.com/api/clients/67/"
+  },
+  "update_type": "via_api"
+}
+

pages/balance_updates/create-a-balance-update.md

@@ -0,0 +1,10 @@
+### Creating a Balance Update
+
+Creating a Balance Update can be completed by simply supplying the `role`, `credit_amount` and `method` as the 
+`description` and `send_receipt` fields are optional. The `credit_amount` field must always be a positive value, 
+however if the method is set to `"correction"` then `credit_amount` can be a negative value. If `send_receipt` is set 
+to `True` then the `Payment receipt` email will be sent to the client if the email definition is enabled.
+
+The possible values for the `method` field are:
+`cash`, `cheque`, `credit_card`, `transferwise`, `debit_card`, `bank_transfer`, `direct_debit`, `bonus_credit`, 
+`manual`, `voucher`, `correction`.

pages/balance_updates/create-a-balance-update.py

@@ -0,0 +1,12 @@
+import pprint, requests
+
+headers = {'Authorization': 'token <API KEY>'}
+data = {
+    "role": 67,
+    "credit_amount": 100,
+    "method": "cash",
+    "description": "Client paid by cash.",
+    "send_receipt": True,
+}
+response = requests.post('https://secure.tutorcruncher.com/api/balance_updates/', json=data, headers=headers)
+pprint.pprint(response.json())

pages/balance_updates/get-a-balance-update.json

@@ -0,0 +1,41 @@
+{
+  "id": 182,
+  "created": "2025-09-30T15:03:58.676657+01:00",
+  "creator": {
+    "id": 6,
+    "first_name": "Thomas",
+    "last_name": "Jackson",
+    "email": "[email protected]",
+    "role_type": "Administrator"
+  },
+  "credit_amount": "-567.50",
+  "description": "Invoice raised",
+  "method": "auto",
+  "related_item": {
+    "id": 54,
+    "display_id": "INV-54",
+    "date_sent": "2025-09-30T15:03:58.623171+01:00",
+    "gross": "567.50",
+    "net": "472.92",
+    "tax": "94.58",
+    "client": {
+      "id": 42,
+      "first_name": "Nicole",
+      "last_name": "Beggs",
+      "email": "[email protected]",
+      "role_type": "Client",
+      "url": "https://secure.tutorcruncher.com/api/clients/42/"
+    },
+    "status": "unpaid",
+    "url": "https://secure.tutorcruncher.com/api/invoices/54/"
+  },
+  "role": {
+    "id": 42,
+    "first_name": "Nicole",
+    "last_name": "Beggs",
+    "email": "[email protected]",
+    "role_type": "Client",
+    "url": "https://secure.tutorcruncher.com/api/clients/42/"
+  },
+  "update_type": "invoice_creation"
+}

pages/balance_updates/get-a-balance-update.md

@@ -0,0 +1,3 @@
+### Get a Balance Update
+
+Returns the details of an existing Balance Update. You only need to specify the unique `id` of the Balance Update to get the correct details.

pages/balance_updates/get-a-balance-update.py

@@ -0,0 +1,5 @@
+import pprint, requests
+
+headers = {'Authorization': 'token <API KEY>'}
+r = requests.get('https://secure.tutorcruncher.com/api/balance_updates/<id>/', headers=headers)
+pprint.pprint(r.json())

pages/balance_updates/list-all-balance-updates.json

@@ -0,0 +1,17 @@
+{
+  "count": 1,
+  "next": null,
+  "previous": null,
+  "results": [
+    {
+      "id": 182,
+      "created": "2025-09-30T15:03:58.676657+01:00",
+      "credit_amount": "-567.50",
+      "method": "auto",
+      "role": 42,
+      "update_type": "invoice_creation",
+      "url": "https://secure.tutorcruncher.com/api/balance-updates/182/"
+    }
+  ]
+}
+

pages/balance_updates/list-all-balance-updates.md

@@ -0,0 +1,3 @@
+### List all Balance Updates
+
+Returns a list of all your Balance Updates. The Balance Updates are sorted by date created, with the most recently created first.

pages/balance_updates/list-all-balance-updates.py

@@ -0,0 +1,5 @@
+import pprint, requests
+
+headers = {'Authorization': 'token <API KEY>'}
+r = requests.get('https://secure.tutorcruncher.com/api/balance_updates/', headers=headers)
+pprint.pprint(r.json())