> ## Documentation Index
> Fetch the complete documentation index at: https://jobticket-docs.ticket-plus.app/llms.txt
> Use this file to discover all available pages before exploring further.
# List Billing Items
> Retrieve a paginated, filterable list of the charges that make up your company's invoices.
Billing items are the individual line charges behind your company's invoices. Each item ties a **charge** — such as a per-employee transit ticket — to a **billing period** and its net, tax, and gross amounts.
Use this endpoint to see how much your company is charged, which employees received a ticket, the price of each charge, and the period it falls in. Filter on `chargeType=ticket-charge` together with a `period` to reconstruct exactly which employees were billed a ticket in a given month — the basis for your payroll data.
This endpoint requires the `view-billing` permission. See [Authorization](/v1/authorization#permissions).
```bash cURL theme={null}
curl --request GET \
--url "https://v1-api.ticket-plus.app/billing/items?chargeType=ticket-charge&period=2024-05-01&page=1&perPage=10" \
--header "Authorization: Basic "
```
```python Python theme={null}
import requests
import base64
credentials = base64.b64encode(b":").decode()
res = requests.get(
"https://v1-api.ticket-plus.app/billing/items",
params={"chargeType": "ticket-charge", "period": "2024-05-01", "page": 1, "perPage": 10},
headers={"Authorization": f"Basic {credentials}"},
)
print(res.json())
```
```javascript Node.js theme={null}
const credentials = Buffer.from(":").toString("base64");
const res = await fetch(
"https://v1-api.ticket-plus.app/billing/items?chargeType=ticket-charge&period=2024-05-01&page=1&perPage=10",
{ headers: { Authorization: `Basic ${credentials}` } }
);
console.log(await res.json());
```
```json 200 theme={null}
{
"data": {
"data": [
{
"id": 1024,
"billing": {
"period": "2024-05-01",
"total": { "label": "€29.00", "value": 2900 },
"tax": { "label": "€5.51", "value": 551 },
"overall": { "label": "€34.51", "value": 3451 }
},
"charge": {
"type": "ticket-charge",
"employee": {
"profile": {
"id": 42,
"firstName": "Anna",
"lastName": "Müller",
"email": "anna.mueller@example.com",
"hrId": "emp_HR_001"
},
"exists": true
},
"plan": {
"type": "split-pay-plan",
"companyAmount": { "label": "€20.00", "value": 2000 },
"employeeAmount": { "label": "€9.00", "value": 900 }
}
},
"billedAt": "2024-05-01T00:00:00Z",
"resource": "billing-item",
"_links": {
"self": { "href": "https://v1-api.ticket-plus.app/billing/items/1024", "type": "application/json" },
"employee": { "href": "https://v1-api.ticket-plus.app/employees/42", "type": "application/json" }
}
}
],
"page": 1,
"perPage": 10,
"totalPages": 4,
"total": 38
}
}
```
## Query Parameters
Page number to return. Starts at `1`.
Number of results per page. Maximum is `100`.
Sort direction. Allowed values: `asc`, `desc`.
Field to sort results by. Allowed values: `id`, `billingPeriod`, `billedAt`.
Filter to a single charge type. Allowed values: `service-charge`, `ticket-charge`, `hr-integration-charge`, `hr-payroll-integration-charge`, `api-charge`. Use `ticket-charge` to list the per-employee transit ticket charges used for payroll.
Filter to a single billing period in `YYYY-MM-DD` format — the first day of the billed month, e.g. `2024-05-01`.
## Response
Array of billing item objects.
Unique billing item identifier.
The billing period this charge belongs to and its monetary amounts.
Billing period in `YYYY-MM-DD` format — the first day of the billed month.
Net amount, before tax.
Formatted display string, e.g. `"€29.00"`.
Raw net amount, in cents (no decimals).
Tax amount applied to this charge.
Formatted display string, e.g. `"€5.51"`.
Raw tax amount, in cents (no decimals).
Gross amount — net plus tax. This is what is invoiced.
Formatted display string, e.g. `"€34.51"`.
Raw gross amount, in cents (no decimals).
What the charge is for, and the employee it applies to where relevant.
The kind of charge. Allowed values: `service-charge`, `ticket-charge`, `hr-integration-charge`, `hr-payroll-integration-charge`, `api-charge`. A `ticket-charge` is a per-employee transit ticket charge — these are what you use to build payroll. The other types are company-level platform fees not tied to a single employee.
The employee this charge applies to. `null` for company-level charges not tied to an employee.
Snapshot of the employee as billed. Fields may be `null` if the employee was removed after being billed.
JobTicket employee ID. `null` if the employee no longer exists.
Employee's first name at the time of billing.
Employee's last name at the time of billing.
Employee's email at the time of billing.
The employee's ID in your HR system. Use this to match the charge back to your payroll records.
`true` if the employee still exists in JobTicket; `false` if they have since been removed.
The subscription plan that produced this charge, and how its cost is split between company and employee. `null` for charges not tied to a plan, such as company-level platform fees.
Plan type. Allowed values: `fully-subsidized-plan` (company pays the full amount), `deferred-plan` (cost is deferred), `split-pay-plan` (cost is split between company and employee).
The portion of the charge paid by the company.
Formatted display string, e.g. `"€29.00"`.
Raw amount paid by the company, in cents (no decimals).
The portion of the charge paid by the employee. Zero for a `fully-subsidized-plan`.
Formatted display string, e.g. `"€0.00"`.
Raw amount paid by the employee, in cents (no decimals).
ISO 8601 timestamp of when the charge was billed.
Resource type label. Always `"billing-item"`.
HAL hypermedia links.
Link to this billing item resource.
URL of this billing item.
Media type.
Link to the charged employee. Present only for per-employee charges.
URL of the employee resource.
Media type.
Current page number returned.
Number of results per page.
Total number of pages available.
Total number of billing items matching your filters.
## OpenAPI
````yaml GET /billing/items
openapi: 3.0.3
info:
title: JobTicket API
description: >-
The JobTicket B2B API lets you read employee data, manage HR integrations,
and access employee documents programmatically. All endpoints use HTTP Basic
Auth — pass your API key credentials from the Developer Portal as the
username and password.
version: 1.0.0
servers:
- url: https://v1-api-staging.ticket-plus.app
description: Staging server
- url: https://v1-api.ticket-plus.app
description: Production Server
security:
- basicAuth: []
externalDocs:
url: https://jobticket-docs.ticket-plus.app
description: View our documentation to get more info
paths:
/billing/items:
get:
tags:
- Billing Items
summary: Paginate Billing Items
description: >-
Returns a paginated list of billing items — the individual charges that
make up your company's invoices. Each item ties a charge (such as a
per-employee ticket charge) to a billing period and its monetary
amounts. Filter by `chargeType` and `period` to isolate the charges you
need; filter on `ticket-charge` to reconstruct which employees received
a ticket in a given month for payroll. Requires the `view-billing`
permission.
parameters:
- schema:
type: integer
minimum: 0
default: 1
nullable: true
in: query
name: page
required: false
description: Page number to return. Starts at `1`.
- schema:
type: integer
minimum: 0
maximum: 100
default: 10
nullable: true
in: query
name: perPage
required: false
description: Number of results per page. Maximum is `100`.
- schema:
type: string
enum:
- asc
- desc
default: desc
nullable: true
in: query
name: sortOrder
required: false
description: 'Sort direction. Allowed values: `asc`, `desc`.'
- schema:
type: string
enum:
- id
- billingPeriod
- billedAt
default: billedAt
nullable: true
in: query
name: sortField
required: false
description: >-
Field to sort results by. Allowed values: `id`, `billingPeriod`,
`billedAt`.
- schema:
type: string
enum:
- service-charge
- ticket-charge
- hr-integration-charge
- hr-payroll-integration-charge
- api-charge
nullable: true
in: query
name: chargeType
required: false
description: >-
Filter to a single charge type. Use `ticket-charge` to list the
per-employee transit ticket charges used for payroll. Allowed
values: `service-charge`, `ticket-charge`, `hr-integration-charge`,
`hr-payroll-integration-charge`, `api-charge`.
- schema:
type: string
nullable: true
in: query
name: period
required: false
description: >-
Filter to a single billing period. Format `YYYY-MM-DD` (the first
day of the billed month, e.g. `2024-05-01`).
responses:
'200':
description: A paginated list of billing items.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/BillingItem'
page:
type: integer
description: Current page number returned.
perPage:
type: integer
description: Number of results per page.
totalPages:
type: integer
description: Total number of pages available.
total:
type: integer
description: Total number of billing items matching your filters.
required:
- data
- page
- perPage
- totalPages
- total
required:
- data
security:
- basicAuth: []
components:
schemas:
BillingItem:
type: object
description: A single charge on your company's invoice, tied to a billing period.
properties:
id:
type: integer
description: Unique billing item identifier.
billing:
type: object
description: The billing period this charge belongs to and its monetary amounts.
properties:
period:
type: string
description: >-
Billing period in `YYYY-MM-DD` format (the first day of the
billed month, e.g. `2024-05-01`).
total:
type: object
description: Net amount, before tax.
properties:
label:
type: string
description: Formatted display string, e.g. `"€29.00"`.
value:
type: integer
description: Raw net amount, in cents (no decimals).
required:
- label
- value
tax:
type: object
description: Tax amount applied to this charge.
properties:
label:
type: string
description: Formatted display string, e.g. `"€5.51"`.
value:
type: integer
description: Raw tax amount, in cents (no decimals).
required:
- label
- value
overall:
type: object
description: Gross amount — net plus tax. This is what is invoiced.
properties:
label:
type: string
description: Formatted display string, e.g. `"€34.51"`.
value:
type: integer
description: Raw gross amount, in cents (no decimals).
required:
- label
- value
required:
- period
- total
- tax
- overall
charge:
type: object
description: >-
What the charge is for, and the employee it applies to where
relevant.
properties:
type:
type: string
enum:
- service-charge
- ticket-charge
- hr-integration-charge
- hr-payroll-integration-charge
- api-charge
description: >-
The kind of charge. `ticket-charge` is a per-employee transit
ticket charge — use these to build payroll. Other types
(`service-charge`, `hr-integration-charge`,
`hr-payroll-integration-charge`, `api-charge`) are company-level
platform fees not tied to a single employee.
employee:
type: object
nullable: true
description: >-
The employee this charge applies to. `null` for company-level
charges that are not tied to an employee (e.g.
`service-charge`).
properties:
profile:
type: object
description: >-
Snapshot of the employee as billed. Fields may be `null` if
the employee was deleted after being billed.
properties:
id:
type: integer
nullable: true
description: >-
JobTicket employee ID. `null` if the employee no longer
exists.
firstName:
type: string
nullable: true
description: Employee's first name at the time of billing.
lastName:
type: string
nullable: true
description: Employee's last name at the time of billing.
email:
type: string
nullable: true
description: Employee's email at the time of billing.
hrId:
type: string
nullable: true
description: >-
The employee's ID in your HR system — use this to match
the charge back to your payroll records.
required:
- id
- firstName
- lastName
- email
- hrId
exists:
type: boolean
description: >-
`true` if the employee still exists in JobTicket; `false` if
they have since been removed.
required:
- profile
- exists
plan:
type: object
nullable: true
description: >-
The subscription plan that produced this charge, and how its
cost is split between company and employee. `null` for charges
not tied to a plan (e.g. company-level platform fees).
properties:
type:
type: string
enum:
- fully-subsidized-plan
- deferred-plan
- split-pay-plan
description: >-
Plan type. `fully-subsidized-plan` — the company pays the
full amount. `deferred-plan` — the cost is deferred.
`split-pay-plan` — the cost is split between company and
employee.
companyAmount:
type: object
description: The portion of the charge paid by the company.
properties:
label:
type: string
description: Formatted display string, e.g. `"€29.00"`.
value:
type: integer
description: Raw amount paid by the company, in cents (no decimals).
required:
- label
- value
employeeAmount:
type: object
description: >-
The portion of the charge paid by the employee. Zero for a
`fully-subsidized-plan`.
properties:
label:
type: string
description: Formatted display string, e.g. `"€0.00"`.
value:
type: integer
description: Raw amount paid by the employee, in cents (no decimals).
required:
- label
- value
required:
- type
required:
- type
billedAt:
type: string
description: ISO 8601 timestamp of when the charge was billed.
resource:
type: string
description: Resource type label. Always `"billing-item"`.
_links:
type: object
description: HAL hypermedia links.
properties:
self:
type: object
description: Link to this billing item resource.
properties:
href:
type: string
description: URL of this billing item.
type:
type: string
description: Media type.
required:
- href
- type
employee:
type: object
description: >-
Link to the charged employee. Present only for per-employee
charges.
properties:
href:
type: string
description: URL of the employee resource.
type:
type: string
description: Media type.
required:
- href
- type
required:
- self
required:
- id
- billing
- charge
- billedAt
- resource
- _links
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic Auth using your API key credentials. Use the username and
password issued from the Developer Portal. Encode them as
`Base64(username:password)` and pass in the `Authorization: Basic
` header.
````