Calculate a pay run

POST

/pay_runs/{pay_run_id}/calculate

const url = 'https://api.usepayloom.com/api/v1/pay_runs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/calculate';
const options = {method: 'POST', 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 POST \
  --url https://api.usepayloom.com/api/v1/pay_runs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/calculate \
  --header 'Authorization: Bearer <token>'

Prices every employee in the run’s jurisdiction. Runs of 200 employees or fewer calculate in the request and return calculated; larger runs calculate in the background and return calculating — poll the pay run until its status reads calculated (a failure falls back to draft). Safe to repeat: recalculation reverses the prior run’s year-to-date contributions before re-pricing, so it never double-counts.

Fails with 409 invalid_transition on a paid run (reopen it in the console first) and 422 kyc_not_verified until the organization is verified. Requires the payruns.run scope.

Authorizations

ApiKey

Parameters

Path Parameters

pay_run_id

required

string format: uuid

Header Parameters

Idempotency-Key

string

<= 255 characters

A client-generated unique string (a UUID works). Retrying with the same key and body replays the original response instead of acting twice.

Responses

200

application/json

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

Example

{
  "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"
  }
}

404

No such resource in this organization.

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"
  }
}

409

A request with this Idempotency-Key is still in progress.

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"
  }
}

Headers

Retry-After

integer

422

Validation failed, or the Idempotency-Key was reused for a different request (idempotency_key_reuse).

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"
  }
}