List Billing Items - JobTicket+ JobTicket B2B API

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 <base64(clientId:clientSecret)>"

import requests
import base64

credentials = base64.b64encode(b"<clientId>:<clientSecret>").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())

const credentials = Buffer.from("<clientId>:<clientSecret>").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());

{
  "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": "[email protected]",
              "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
  }
}

GET

billing

items

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 <base64(clientId:clientSecret)>"

import requests
import base64

credentials = base64.b64encode(b"<clientId>:<clientSecret>").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())

const credentials = Buffer.from("<clientId>:<clientSecret>").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());

{
  "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": "[email protected]",
              "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
  }
}

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.

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 <base64(clientId:clientSecret)>"

import requests
import base64

credentials = base64.b64encode(b"<clientId>:<clientSecret>").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())

const credentials = Buffer.from("<clientId>:<clientSecret>").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());

{
  "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": "[email protected]",
              "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

integer

default:"1"

Page number to return. Starts at 1.

perPage

integer

default:"10"

Number of results per page. Maximum is 100.

sortOrder

string

default:"desc"

Sort direction. Allowed values: asc, desc.

sortField

string

default:"billedAt"

Field to sort results by. Allowed values: id, billingPeriod, billedAt.

chargeType

string

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.

period

string

Filter to a single billing period in YYYY-MM-DD format — the first day of the billed month, e.g. 2024-05-01.

Response

data

object

required

Show properties

data

object[]

required

Array of billing item objects.

Show billing item object

integer

required

Unique billing item identifier.

billing

object

required

The billing period this charge belongs to and its monetary amounts.

Show properties

period

string

required

Billing period in YYYY-MM-DD format — the first day of the billed month.

total

object

required

Net amount, before tax.

Show properties

label

string

required

Formatted display string, e.g. "€29.00".

value

integer

required

Raw net amount, in cents (no decimals).

tax

object

required

Tax amount applied to this charge.

Show properties

label

string

required

Formatted display string, e.g. "€5.51".

value

integer

required

Raw tax amount, in cents (no decimals).

overall

object

required

Gross amount — net plus tax. This is what is invoiced.

Show properties

label

string

required

Formatted display string, e.g. "€34.51".

value

integer

required

Raw gross amount, in cents (no decimals).

charge

object

required

What the charge is for, and the employee it applies to where relevant.

Show properties

type

string

required

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.

employee

object | null

The employee this charge applies to. null for company-level charges not tied to an employee.

Show properties

profile

object

required

Snapshot of the employee as billed. Fields may be null if the employee was removed after being billed.

Show properties

integer | null

required

JobTicket employee ID. null if the employee no longer exists.

firstName

string | null

required

Employee’s first name at the time of billing.

lastName

string | null

required

Employee’s last name at the time of billing.

string | null

required

Employee’s email at the time of billing.

hrId

string | null

required

The employee’s ID in your HR system. Use this to match the charge back to your payroll records.

exists

boolean

required

true if the employee still exists in JobTicket; false if they have since been removed.

plan

object | null

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.

Show properties

type

string

required

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).

companyAmount

object

The portion of the charge paid by the company.

Show properties

label

string

required

Formatted display string, e.g. "€29.00".

value

integer

required

Raw amount paid by the company, in cents (no decimals).

employeeAmount

object

The portion of the charge paid by the employee. Zero for a fully-subsidized-plan.

Show properties

label

string

required

Formatted display string, e.g. "€0.00".

value

integer

required

Raw amount paid by the employee, in cents (no decimals).

billedAt

string

required

ISO 8601 timestamp of when the charge was billed.

resource

string

required

Resource type label. Always "billing-item".

_links

object

required

HAL hypermedia links.

Show properties

self

object

required

Link to this billing item resource.

Show properties

href

string

required

URL of this billing item.

type

string

required

Media type.

employee

object

Link to the charged employee. Present only for per-employee charges.

Show properties

href

string

required

URL of the employee resource.

type

string

required

Media type.

page

integer

required

Current page number returned.

perPage

integer

required

Number of results per page.

totalPages

integer

required

Total number of pages available.

total

integer

required

Total number of billing items matching your filters.

Authorizations

Authorization

string

header

required

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 <token> header.

Query Parameters

page

integer | null

default:1

Page number to return. Starts at 1.

Required range: x >= 0

perPage

integer | null

default:10

Number of results per page. Maximum is 100.

Required range: 0 <= x <= 100

sortOrder

enum<string> | null

default:desc

Sort direction. Allowed values: asc, desc.

Available options:

asc,

desc

sortField

enum<string> | null

default:billedAt

Field to sort results by. Allowed values: id, billingPeriod, billedAt.

Available options:

id,

billingPeriod,

billedAt

chargeType

enum<string> | null

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.

Available options:

service-charge,

ticket-charge,

hr-integration-charge,

hr-payroll-integration-charge,

api-charge

period

string | null

Filter to a single billing period. Format YYYY-MM-DD (the first day of the billed month, e.g. 2024-05-01).

Response

200 - application/json

A paginated list of billing items.

data

object

required

Show child attributes

Trigger HR Sync Get Billing Item

​Query Parameters

​Response

Authorizations

Query Parameters

Response

Query Parameters

Response