Skip to content

Commit 59b2e55

Browse files
DanJezeph15DanJezeph15
authored
Balance Update API docs (#207)
* Object + list + filter + get docs * Creating a balance update docs * Add send_receipt details in * Children fields for client and creator on a BalanceUpdate * Add role type * Update docs * Update actions.json * Update filters * Update docs * Last piece I missed
1 parent 8193c2f commit 59b2e55

15 files changed

+328
-0
lines changed

‎data/actions.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -452,6 +452,22 @@
452452
"extra_msg": "",
453453
"subject_types": []
454454
},
455+
{
456+
"key": "PFI_EXPORT",
457+
"value": "PFI_EXPORT",
458+
"msg": "Exported Credit Requests",
459+
"help_text": "When an Administrator exports data about Credit Requests.",
460+
"extra_msg": "",
461+
"subject_types": []
462+
},
463+
{
464+
"key": "PO_EXPORT",
465+
"value": "PO_EXPORT",
466+
"msg": "Exported Payment Orders",
467+
"help_text": "When an Administrator exports data about Payment Orders.",
468+
"extra_msg": "",
469+
"subject_types": []
470+
},
455471
{
456472
"key": "EDITED_OWN_PROFILE",
457473
"value": "EDITED_OWN_PROFILE",

‎pages/api.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,10 @@ endpoint_sections:
5454
title: Appointments (Lessons)
5555
id: appointments
5656
layout: /appointments/appointments.yml
57+
-
58+
title: Balance Updates
59+
id: balance_updates
60+
layout: /balance_updates/balance_updates.yml
5761
-
5862
title: Branch
5963
id: branch

‎pages/balance_updates/balance-update-object.json‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"id": 182,
3+
"created": "2025-09-30T15:03:58.676657+01:00",
4+
"creator": {
5+
"id": 6,
6+
"first_name": "Thomas",
7+
"last_name": "Jackson",
8+
"email": "[email protected]",
9+
"role_type": "Administrator"
10+
},
11+
"credit_amount": "-567.50",
12+
"description": "Invoice raised",
13+
"method": "auto",
14+
"related_item": {
15+
"id": 54,
16+
"display_id": "INV-54",
17+
"date_sent": "2025-09-30T15:03:58.623171+01:00",
18+
"gross": "567.50",
19+
"net": "472.92",
20+
"tax": "94.58",
21+
"client": {
22+
"id": 42,
23+
"first_name": "Nicole",
24+
"last_name": "Beggs",
25+
"email": "[email protected]",
26+
"role_type": "Client",
27+
"url": "https://secure.tutorcruncher.com/api/clients/42/"
28+
},
29+
"status": "unpaid",
30+
"url": "https://secure.tutorcruncher.com/api/invoices/54/"
31+
},
32+
"role": {
33+
"id": 42,
34+
"first_name": "Nicole",
35+
"last_name": "Beggs",
36+
"email": "[email protected]",
37+
"role_type": "Client",
38+
"url": "https://secure.tutorcruncher.com/api/clients/42/"
39+
},
40+
"update_type": "invoice_creation"
41+
}

‎pages/balance_updates/balance-update-object.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
### Balance Update Object
2+
3+
A Balance Update represents a change in a Users balance. It can be created manually by an Admin or automatically
4+
when certain actions occur, such as when a payment is processed.

‎pages/balance_updates/balance-update-object.yml‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
attributes:
2+
-
3+
name: id
4+
type: integer
5+
description: Unique identifier for the balance update.
6+
-
7+
name: created
8+
type: datetime
9+
description: The date and time when the balance update was created.
10+
-
11+
name: creator
12+
type: object
13+
description: The user who created this balance update.
14+
children:
15+
- name: id
16+
type: integer
17+
description: Unique identifier for the object.
18+
- name: first_name
19+
type: string
20+
description: The User's first name.
21+
- name: last_name
22+
type: string
23+
description: The User's last name.
24+
- name: email
25+
type: string
26+
description: The User's email address.
27+
- name: role_type
28+
type: string
29+
description: The role type of the Balance Update creator.
30+
- name: url
31+
type: string
32+
description: URL to the Creator's object. (This field will not be present if the creator is an Administrator)
33+
-
34+
name: credit_amount
35+
type: decimal
36+
description: The amount of credit being added or removed from the client's balance.
37+
-
38+
name: description
39+
type: string
40+
description: A description explaining the reason for the balance update.
41+
-
42+
name: method
43+
type: string
44+
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'].
45+
-
46+
name: related_item
47+
type: object
48+
description: Any related object that this balance update is associated with (nullable).
49+
-
50+
name: role
51+
type: object
52+
description: The user whose balance is being updated.
53+
children:
54+
- name: id
55+
type: integer
56+
description: Unique identifier for the object.
57+
- name: first_name
58+
type: string
59+
description: User's first name.
60+
- name: last_name
61+
type: string
62+
description: User's last name.
63+
- name: email
64+
type: string
65+
description: User's email address.
66+
- name: role_type
67+
type: string
68+
description: The role type of the User.
69+
- name: url
70+
type: string
71+
description: URL to the User's object.
72+
-
73+
name: update_type
74+
type: string
75+
description: The type of update being performed (e.g., "via_api", "manual").
76+
77+
filters:
78+
-
79+
name: client
80+
type: integer
81+
description: Filter by the Balance Updates linked Client (id).
82+
-
83+
name: contractor
84+
type: integer
85+
description: Filter by the Balance Updates linked Tutor (id).
86+
-
87+
name: method
88+
type: string
89+
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']'
90+
-
91+
name: update_type
92+
type: string
93+
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']'
94+
-
95+
name: credit_amount_gte
96+
type: decimal
97+
description: Filter by Balance Updates with a credit_amount greater than or equal to this value.
98+
-
99+
name: credit_amount_lte
100+
type: decimal
101+
description: Filter by Balance Updates with a credit_amount less than or equal to this value.
102+
-
103+
name: created_gte
104+
type: datetime
105+
description: Filter by Balance Updates created on or after this date and time.
106+
-
107+
name: created_lte
108+
type: datetime
109+
description: Filter by Balance Updates created on or before this date and time.

‎pages/balance_updates/balance_updates.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
sections:
2+
-
3+
title: Balance Update Object
4+
id: balance-update-object
5+
description: /balance_updates/balance-update-object.md
6+
attributes: /balance_updates/balance-update-object.yml
7+
response: /balance_updates/balance-update-object.json
8+
response_title: OBJECT
9+
-
10+
title: List all Balance Updates
11+
id: list-all-balance-updates
12+
description: /balance_updates/list-all-balance-updates.md
13+
filters: /balance_updates/balance-update-object.yml
14+
code: /balance_updates/list-all-balance-updates.py
15+
code_type: GET
16+
code_url: /api/balance_updates/
17+
response: /balance_updates/list-all-balance-updates.json
18+
-
19+
title: Get a balance update
20+
id: get-a-balance-update
21+
description: /balance_updates/get-a-balance-update.md
22+
code: /balance_updates/get-a-balance-update.py
23+
code_type: GET
24+
code_url: /api/balance_updates/{id}/
25+
response: /balance_updates/get-a-balance-update.json
26+
-
27+
title: Create a balance update
28+
id: create-a-balance-update
29+
description: /balance_updates/create-a-balance-update.md
30+
code: /balance_updates/create-a-balance-update.py
31+
code_type: POST
32+
code_url: /api/balance_updates/
33+
response: /balance_updates/create-a-balance-update.json

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

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"id": 385,
3+
"created": "2025-09-25T10:00:00.000000+01:00",
4+
"creator": {
5+
"id": 64,
6+
"first_name": "Billy",
7+
"last_name": "Holiday",
8+
"email": "[email protected]",
9+
"role_type": "Administrator"
10+
},
11+
"credit_amount": "100.00",
12+
"description": "This is a test description about why the credit was added to this client",
13+
"method": "cash",
14+
"related_item": null,
15+
"role": {
16+
"id": 67,
17+
"first_name": "Billy",
18+
"last_name": "Holiday",
19+
"email": "[email protected]",
20+
"role_type": "Client",
21+
"url": "https://secure.tutorcruncher.com/api/clients/67/"
22+
},
23+
"update_type": "via_api"
24+
}
25+

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
### Creating a Balance Update
2+
3+
Creating a Balance Update can be completed by simply supplying the `role`, `credit_amount` and `method` as the
4+
`description` and `send_receipt` fields are optional. The `credit_amount` field must always be a positive value,
5+
however if the method is set to `"correction"` then `credit_amount` can be a negative value. If `send_receipt` is set
6+
to `True` then the `Payment receipt` email will be sent to the client if the email definition is enabled.
7+
8+
The possible values for the `method` field are:
9+
`cash`, `cheque`, `credit_card`, `transferwise`, `debit_card`, `bank_transfer`, `direct_debit`, `bonus_credit`,
10+
`manual`, `voucher`, `correction`.

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
import pprint, requests
2+
3+
headers = {'Authorization': 'token <API KEY>'}
4+
data = {
5+
"role": 67,
6+
"credit_amount": 100,
7+
"method": "cash",
8+
"description": "Client paid by cash.",
9+
"send_receipt": True,
10+
}
11+
response = requests.post('https://secure.tutorcruncher.com/api/balance_updates/', json=data, headers=headers)
12+
pprint.pprint(response.json())

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

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"id": 182,
3+
"created": "2025-09-30T15:03:58.676657+01:00",
4+
"creator": {
5+
"id": 6,
6+
"first_name": "Thomas",
7+
"last_name": "Jackson",
8+
"email": "[email protected]",
9+
"role_type": "Administrator"
10+
},
11+
"credit_amount": "-567.50",
12+
"description": "Invoice raised",
13+
"method": "auto",
14+
"related_item": {
15+
"id": 54,
16+
"display_id": "INV-54",
17+
"date_sent": "2025-09-30T15:03:58.623171+01:00",
18+
"gross": "567.50",
19+
"net": "472.92",
20+
"tax": "94.58",
21+
"client": {
22+
"id": 42,
23+
"first_name": "Nicole",
24+
"last_name": "Beggs",
25+
"email": "[email protected]",
26+
"role_type": "Client",
27+
"url": "https://secure.tutorcruncher.com/api/clients/42/"
28+
},
29+
"status": "unpaid",
30+
"url": "https://secure.tutorcruncher.com/api/invoices/54/"
31+
},
32+
"role": {
33+
"id": 42,
34+
"first_name": "Nicole",
35+
"last_name": "Beggs",
36+
"email": "[email protected]",
37+
"role_type": "Client",
38+
"url": "https://secure.tutorcruncher.com/api/clients/42/"
39+
},
40+
"update_type": "invoice_creation"
41+
}

0 commit comments

Comments
 (0)