Create a pay run

POST

/pay_runs

curl --request POST \
  --url https://api.usepayloom.com/api/v1/pay_runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "jurisdiction": "GH", "period_start": "2026-04-15", "period_end": "2026-04-15", "pay_date": "2026-04-15", "as_of_date": "2026-04-15" }'

• Production
• Staging — demo data, `plm_test_` keys

Requires the payruns.run scope. The run is created in draft.

Authorizations

• ApiKey

Parameters

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.

Request Body^required

Media typeapplication/json

object

jurisdiction

required

string

Example

GH

period_start

required

string format: date

period_end

required

string format: date

pay_date

required

string format: date

as_of_date

The date whose statutory rules price the run. Defaults to period_end.

string format: date

Responses

201

Created

Media typeapplication/json

object

id

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.

Media typeapplication/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.

Media typeapplication/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.

Media typeapplication/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).

Media typeapplication/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"
  }
}