List pay runs

GET

/pay_runs

const url = 'https://api.usepayloom.com/api/v1/pay_runs?limit=25&status=draft';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.usepayloom.com/api/v1/pay_runs?limit=25&status=draft' \
  --header 'Authorization: Bearer <token>'

Requires the payruns.read scope.

Authorizations

ApiKey

Parameters

Query Parameters

limit

integer

default: 25 >= 1 <= 100

starting_after

string format: uuid

The next_cursor from the previous page.

updated_since

string format: date-time

ISO 8601 timestamp; returns only records updated at or after it.

status

string

Allowed values: draft calculated approved paid

Responses

200

application/json

object

object

string

Allowed value: list

data

Array<object>

object

string format: uuid

object

string

Allowed value: pay_run

status

Lifecycle is draft → (calculating →) calculated → approved → paid; volume runs price in the background and read calculating meanwhile. A paid run is immutable; later corrections arrive as retro adjustments on the next open run rather than by rewriting history.

string

Allowed values: draft calculating calculated approved paid

jurisdiction

string

currency

string

period_start

string format: date

period_end

string format: date

pay_date

string format: date

as_of_date

The date whose statutory rules priced this run.

string format: date

payslip_count

integer

totals

object

gross

object

amount_minor

required

Integer amount in the currency’s minor unit. 50000 GHS = 500.00.

integer

currency

required

string

net

object

amount_minor

required

Integer amount in the currency’s minor unit. 50000 GHS = 500.00.

integer

currency

required

string

employee_deductions

object

amount_minor

required

Integer amount in the currency’s minor unit. 50000 GHS = 500.00.

integer

currency

required

string

employer_cost

Sits ON TOP of gross — do not add it into gross.

object

amount_minor

required

Integer amount in the currency’s minor unit. 50000 GHS = 500.00.

integer

currency

required

string

approved_at

string format: date-time

nullable

paid_at

string format: date-time

nullable

created_at

string format: date-time

updated_at

string format: date-time

has_more

boolean

next_cursor

string format: uuid

nullable

Example

{
  "object": "list",
  "data": [
    {
      "object": "pay_run",
      "status": "draft",
      "totals": {
        "gross": {
          "currency": "GHS"
        },
        "net": {
          "currency": "GHS"
        },
        "employee_deductions": {
          "currency": "GHS"
        },
        "employer_cost": {
          "currency": "GHS"
        }
      }
    }
  ]
}

401

Missing, invalid, revoked or expired key.

application/json

object

error

object

code

required

string

Allowed values: missing_token invalid_token revoked expired insufficient_scope organization_not_operable not_found invalid_request validation_failed rate_limited

message

required

string

details

object

key

additional properties

any

Example

{
  "error": {
    "code": "missing_token"
  }
}

403

The key is valid but lacks the required scope.

application/json

object

error

object

code

required

string

Allowed values: missing_token invalid_token revoked expired insufficient_scope organization_not_operable not_found invalid_request validation_failed rate_limited

message

required

string

details

object

key

additional properties

any

Example

{
  "error": {
    "code": "missing_token"
  }
}