Path: api/v1/invoices
This API is JSON:API compliant.
This endpoint supports the following methods:
GET
This endpoint requires an OAuth bearer token, and returns errors in a standard shape. See API Conventions for authentication, error responses and paging, which apply to every endpoint.
The resource type for this endpoint is Invoice
The identifier is invno
Relationships
A relationship links this Invoice to another resource. By default only the related resource's type and id are returned. Relationships marked Includable can be embedded in the response via the include query parameter (see Includes below). To set or change a relationship, send a resource identifier (type and id) for it. Postable means the relationship can be set when creating the resource (POST); Patchable means it can be changed when updating an existing resource (PATCH). Some relationships are Postable but not Patchable — they can be set at creation but not changed afterwards. A value sent for a relationship that is not Postable/Patchable in that context is not applied.
| Relationship | Type | Returns | Includable | Postable | Patchable |
|---|---|---|---|---|---|
| customer | CardFile | object | ✓ | ✗ | ✗ |
| jobs | Job | array | ✗ | ✗ | ✗ |
| user | CardFile | object | ✓ | ✗ | ✗ |
Includes
Use the include query parameter to embed Includable relationships in a single response, for example:GET /api/v1/invoices/{invno}?include=user,customer
Embedded resources are returned in a top-level included array, not nested inside the relationship. Match each one back to its relationship by type and id.
For example, requesting include=user returns the user reference under relationships and the full resource in the included array. The reference and the included entry share the same type and id:
GET /api/v1/invoices/{invno}?include=user
{
"data": {
"type": "Invoice",
"id": "1001",
"relationships": {
"user": {
"data": { "type": "CardFile", "id": "2002" }
}
}
},
"included": [
{
"type": "CardFile",
"id": "2002",
"attributes": { ... }
}
]
}
Attributes
The Invoice resource type attributes are as follows:
| Attribute | Type | Description |
|---|---|---|
| accountFee | object | The account fee amount, tax and tax code on the invoice. See the accountFee section below. |
| amount | number | The invoice amount. |
| branchCode | string | The branch code. Branches are optional in Jim2 - this is only set when your site is configured to use branches. |
| companyCode | string | The company code. |
| currencyCode | string | The currency code. |
| exchRate | number | The currency exchange rate applied to the invoice. |
| gLDeptCode | string | The GL department code. GL departments are optional in Jim2 - this is only set when your site is configured to use GL departments. |
| invNo | integer | The invoice number (unique identifier). |
| invoiceDate | string (DateTime in ISO format) | The invoice date. |
| invoiceDetails | object | The customer (bill-to) address, ship-to address and freight details for the invoice. See the invoiceDetails section below. |
| invoiceType | string | The invoice type. |
| rateLocked | boolean | Whether the invoice's currency exchange rate is locked. |
| status | string | The invoice status. |
| subBranchCode | string | The sub-branch code. Sub-branches are optional in Jim2 - this is only set when your site is configured to use sub-branches. |
| tax | number | The tax amount on the invoice. |
| taxPaid | boolean | Whether the invoice prices are tax-paid (tax-inclusive). |
Attributes of the accountFee object.
| Attribute | Type | Description |
|---|---|---|
| amount | number | The amount. |
| tax | number | The tax on the amount. |
| taxCode | string | The tax code applied to the amount. |
Attributes of the invoiceDetails object.
| Attribute | Type | Description |
|---|---|---|
| customer | object | The customer (bill-to) name and address details on the invoice. See the invoiceDetails.customer section below. |
| freight | object | The freight charge, tax and dispatch details on the invoice. See the invoiceDetails.freight section below. |
| ship | object | The ship-to name and address details on the invoice. See the invoiceDetails.ship section below. |
Attributes of the invoiceDetails.customer object.
| Attribute | Type | Description |
|---|---|---|
| attn | string | The customer contact (attention) name. |
| country | string | The customer country. |
| isAddressResidential | boolean | Whether the customer address is residential. |
| name | string | The customer name. |
| orderNo | string | The customer's order number. |
| postCode | string | The customer post code. |
| state | string | The customer state. |
| streetAddress | string | The customer street address. |
| suburb | string | The customer suburb. |
Attributes of the invoiceDetails.freight object.
| Attribute | Type | Description |
|---|---|---|
| amount | number | The freight charge amount. |
| dispatch | array of object | The dispatch / consignment details for the shipment. See the invoiceDetails.freight.dispatch section below. |
| tax | number | The tax on the freight charge. |
| taxCode | string | The tax code applied to the freight charge. |
Attributes of the invoiceDetails.ship object.
| Attribute | Type | Description |
|---|---|---|
| attn | string | The delivery (ship-to) contact (attention) name. |
| country | string | The delivery country. |
| isAddressResidential | boolean | Whether the delivery address is residential. |
| name | string | The delivery (ship-to) name. |
| postCode | string | The delivery post code. |
| state | string | The delivery state. |
| streetAddress | string | The delivery street address. |
| suburb | string | The delivery suburb. |
Attributes of each element in the invoiceDetails.freight.dispatch array.
| Attribute | Type | Description |
|---|---|---|
| noOfCartons | integer | The number of cartons in the shipment. |
| shipRef | string | The carrier consignment / shipping reference. |
| shipVia | string | The carrier or method the goods are shipped via. |
Path: api/v1/invoices?filter[customer.id]=11&filter[shipVia]=Machship&filter[invDate][-gt]2025-01-01T00%3A00%3A00%2B00%3A00 Response: This example shows the maximum set of fields the endpoint can return, all populated. A real response only contains the data that applies to that record, so fields that are empty or not relevant are omitted — do not assume every field shown here will be present in every response. This is a list. To keep the example readable, only the first item below is written out; the later items have been trimmed down in this documentation. In a real response each item comes back with the data applicable to that record (as described above). Side-loading related resources with the include query parameter is not supported on list endpoints: an include parameter is ignored here and no included section is returned. To retrieve a related resource, request it directly using the id shown in each item's relationships, or use the single-resource (get by id) endpoint, which does support include.
Example GET (Return all)
{
"data": [
{
"attributes": {
"accountFee": {
"amount": 20.0,
"tax": 2.0,
"taxCode": "G"
},
"amount": 110.0,
"branchCode": "4HB",
"companyCode": "HAPPEN",
"currencyCode": "AUD",
"exchRate": 1.0,
"gLDeptCode": "OTH",
"invNo": 2,
"invoiceDate": "2025-12-04T13:55:00",
"invoiceDetails": {
"customer": {
"attn": "Simple Cust Contact for custom",
"country": "Australia",
"isAddressResidential": true,
"name": "Simple cust #7",
"orderNo": null,
"postCode": "2850",
"state": "NSW",
"streetAddress": "Simple Cust Address",
"suburb": "AARONS PASS"
},
"freight": {
"amount": 15.0,
"dispatch": [
{
"shipVia": "Machship",
"shipRef": "MACH-2001",
"noOfCartons": null
}
],
"tax": 1.5,
"taxCode": "G"
},
"ship": {
"attn": "Simple Cust Contact for custom",
"country": "Australia",
"isAddressResidential": false,
"name": "Simple cust #7",
"postCode": "2850",
"state": "NSW",
"streetAddress": "Simple Cust Address",
"suburb": "AARONS PASS"
}
},
"invoiceType": "Invoice",
"rateLocked": true,
"status": "FINISH",
"subBranchCode": "SA",
"tax": 10.0,
"taxPaid": true
},
"id": "2",
"relationships": {
"customer": {
"data": {
"id": "11",
"type": "CardFile"
}
},
"jobs": {
"data": [
{
"id": "2",
"type": "Job"
},
{
"id": "10",
"type": "Job"
}
]
},
"user": {
"data": {
"id": "1",
"type": "CardFile"
}
}
},
"type": "Invoice"
},
{
"id": "3",
"type": "Invoice",
"attributes": {
"status": "FINISH",
"invNo": 3
}
}
]
}
Path: api/v1/invoices/1234?include=customer,user Response: This example shows the maximum set of fields the endpoint can return, all populated. A real response only contains the data that applies to that record, so fields that are empty or not relevant are omitted — do not assume every field shown here will be present in every response.
Example GET (Return specific)
{
"data": {
"id": "1234",
"type": "Invoice",
"attributes": {
"invNo": 1234,
"invoiceType": "Invoice",
"invoiceDate": "2023-11-20T11:45:00",
"status": "FINISH",
"amount": 200.00,
"tax": 20.00,
"taxPaid": true,
"currencyCode": "AUD",
"exchRate": 1.0,
"rateLocked": true,
"accountFee": {
"amount": 200.0,
"tax": 10.0,
"taxCode": "G"
},
"companyCode": "HAPPEN",
"gLDeptCode": "OTH",
"branchCode": "4HB",
"subBranchCode": "SA",
"invoiceDetails": {
"customer": {
"attn": "Joe",
"name": "Soap",
"isAddressResidential": true,
"streetAddress": "1 Nowhere Rd",
"suburb": "Nowhere",
"state": "NSW",
"postCode": "0000",
"country": "AUS",
"orderNo": null
},
"ship": {
"attn": "Jane",
"name": "Doe",
"isAddressResidential": false,
"streetAddress": "2 Somewhere St",
"suburb": "Somewhere",
"state": "VIC",
"postCode": "0001",
"country": "AUS"
},
"freight": {
"amount": 200.0,
"tax": 10.0,
"taxCode": "G",
"dispatch": [
{
"shipVia": "Machship",
"shipRef": "MACH-1234",
"noOfCartons": null
}
]
}
}
},
"relationships": {
"user": {
"data": {
"type": "CardFile",
"id": "12457"
}
},
"customer": {
"data": {
"type": "CardFile",
"id": "12458"
}
},
"jobs": {
"data": [
{
"type": "Job",
"id": "15"
},
{
"type": "Job",
"id": "28"
}
]
}
},
"links": {
"self": "/{URL ROOT}/api/v1/invoices/1234"
}
},
"included": [
{
"type": "CardFile",
"id": "12458",
"attributes": {
"cardNo": 12458,
"cardCode": "ACME",
"contact": "Jane Smith",
"name": "Acme Corporation Pty Ltd",
"aBN": "53 004 085 616",
"aCN": "004 085 616",
"shipVia": "Courier Express",
"shipAmount": 25.00,
"branchCode": "SYD",
"subBranchCode": "SYD-NORTH",
"gLDeptCode": "SALES",
"customer": {
"terms": "30 Days",
"priceLevel": "Retail",
"custPONo": "PO-44821",
"currencyCode": "AUD",
"creditHold": "OFF( Auto )",
"creditLimit": 50000.00,
"accFeePerc": 2.50,
"bPayRefNo": "1234567890",
"backorder": "Allow Backorders",
"requiredDays": 7,
"requiredHours": 0,
"taxPaid": false,
"taxExclCode": "GST",
"taxInclCode": "GSTINC",
"batchInvGroupBy": "Customer",
"sendStatementVia": "Email",
"sendInvVia": "Email",
"groups": [
{ "type": "Region", "id": 1, "name": "East Coast" }
]
},
"address": {
"isAddressResidential": false,
"streetAddress": "12 Industrial Ave",
"suburb": "Chatswood",
"state": "NSW",
"postCode": "2067",
"country": "Australia"
},
"delAddress": {
"isAddressResidential": false,
"streetAddress": "14 Industrial Ave",
"suburb": "Chatswood",
"state": "NSW",
"postCode": "2067",
"country": "Australia"
}
},
"relationships": {
"contacts": {
"data": [
{ "type": "CardFileContact", "id": "12458-1" }
]
},
"accountManager": {
"data": { "type": "CardFile", "id": "7" }
},
"parent": {
"data": { "type": "CardFile", "id": "9001" }
}
}
},
{
"type": "CardFile",
"id": "12457",
"attributes": {
"cardNo": 12457,
"cardCode": "STAFF.JB",
"contact": "Joe Bloggs",
"name": "Joe Bloggs",
"aBN": "51 824 753 556",
"aCN": "824 753 556",
"shipVia": "Australia Post",
"shipAmount": 12.50,
"branchCode": "SYD",
"subBranchCode": "SYD-NORTH",
"gLDeptCode": "SALES",
"customer": {
"terms": "14 Days",
"priceLevel": "Wholesale",
"custPONo": "PO-STAFF-01",
"currencyCode": "AUD",
"creditHold": "OFF( Auto )",
"creditLimit": 10000.00,
"accFeePerc": 1.50,
"bPayRefNo": "9876543210",
"backorder": "No Part Ship (Supply requested Quantity)",
"requiredDays": 14,
"requiredHours": 8,
"taxPaid": true,
"taxExclCode": "GST",
"taxInclCode": "GSTINC",
"batchInvGroupBy": "Ship",
"sendStatementVia": "Email & Print",
"sendInvVia": "Email & Print",
"groups": [
{ "type": "Region", "id": 2, "name": "Internal Staff" }
]
},
"address": {
"isAddressResidential": false,
"streetAddress": "Level 2, 88 Market Street",
"suburb": "Sydney",
"state": "NSW",
"postCode": "2000",
"country": "Australia"
},
"delAddress": {
"isAddressResidential": false,
"streetAddress": "Level 2, 88 Market Street",
"suburb": "Sydney",
"state": "NSW",
"postCode": "2000",
"country": "Australia"
}
},
"relationships": {
"contacts": {
"data": [
{ "type": "CardFileContact", "id": "12457-1" }
]
},
"accountManager": {
"data": { "type": "CardFile", "id": "7" }
},
"parent": {
"data": { "type": "CardFile", "id": "9001" }
}
}
}
]
}