Skip to content

Rippling: Create a new off-cycle payroll run

Rippling restApi.createPayrollRunsOffCycle: arguments, response, policy and SDK examples.

← Rest API operations · Get started

Operation rippling.rest_api.create_payroll_runs_off_cycle

Provider route: POST /payroll-runs/off-cycle/. Alter supplies the connection’s credentials and routing.

Install @alter-ai/sdk @alter-ai/rippling with npm, or alter-sdk-rippling with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { RipplingIntegration } from "@alter-ai/rippling";
async function execute(input: Parameters<RipplingIntegration["restApi"]["createPayrollRunsOffCycle"]>[0]) {
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
const provider = new RipplingIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
const call = await provider.restApi.createPayrollRunsOffCycle(input);
const result = await call.wait();
return result.bodyJson();
} finally {
await app.close();
}
}
import os
from alter_sdk import App
from alter_sdk_rippling import RipplingIntegration
async def execute(arguments):
async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
provider = RipplingIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
call = await provider.rest_api.create_payroll_runs_off_cycle(arguments)
result = await call.wait()
return result.body_json()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
bodyobjectOptionalOpaque native JSON: the provider publishes a response-shaped request model. Input fields are not verified. Internal_Testing entitlement required. Never retry automatically.
Additional keys: allowed

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$objectRoot
errorsarrayRequired within parentOne error per unconfirmed run creation. Empty on full success; reconcile before retrying.
errors[]ModelEach itemExpand Create a new off-cycle payroll run — response body — errors item
runsarrayRequired within parentConfirmed created draft runs. Empty when no creation could be confirmed.
runs[]ModelEach itemExpand Create a new off-cycle payroll run — response body — runs item
statusstringRequired within parentSUCCESS, PARTIAL_SUCCESS, or FAILED. FAILED means no run creation was confirmed.
Known values: SUCCESS, PARTIAL_SUCCESS, FAILED

Referenced models: Create a new off-cycle payroll run — response body — errors item, Create a new off-cycle payroll run — response body — runs item

Create a new off-cycle payroll run — response body — errors item
FieldTypePresenceDescription and constraints
$objectRoot
codestringRequired within parentStable error code; an exception does not prove that no run was created.
Known values: RUN_CREATION_OUTCOME_UNKNOWN
company_entity_idJSONRequired within parent
company_entity_id (anyOf 1)stringAlternativeHRIS company entity relationship ID for the attempted run. Null if the relationship cannot be resolved.
company_entity_id (anyOf 2)nullAlternative
employment_splitstringRequired within parentEmployment category for the attempted run.
messagestringRequired within parentSafe description of the unconfirmed creation outcome and retry guidance.
worker_idsarrayRequired within parentRole IDs in the run whose creation could not be confirmed.
worker_ids[]stringEach item
Create a new off-cycle payroll run — response body — runs item
FieldTypePresenceDescription and constraints
$objectRoot
check_datestringRequired within parentPayment date selected for this run.
company_entity_idJSONRequired within parent
company_entity_id (anyOf 1)stringAlternativeHRIS company entity relationship ID for this run, matching company_entity_id on payroll run retrieval. Null if the relationship cannot be resolved.
company_entity_id (anyOf 2)nullAlternative
country_codestringRequired within parentCountry code of the payroll entity.
employment_splitstringRequired within parentWorker eligibility category used to split this run, such as employees or contractors.
pay_periodobjectRequired within parentPay period for this run.
pay_period.end_datestringRequired within parentEnd date of this run's pay period.
pay_period.start_datestringRequired within parentStart date of this run's pay period.
run_configurationobjectRequired within parentCalculation configuration used for this run.
run_configuration.pay_basisstringRequired within parentAmount basis used by the created run. This API currently creates gross-pay runs.
run_idstringRequired within parentIdentifier of the created draft payroll run.
run_statusstringRequired within parentStatus of the created payroll run.
run_typestringRequired within parentType of the created payroll run.
worker_idsarrayRequired within parentRole IDs included in this run.
worker_ids[]stringEach item

SDK function policy ID: rippling.rest_api.create_payroll_runs_off_cycle. Catalog operation: create-payroll-runs/off-cycle. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["payroll-runs/off-cycle.read-write"]

Provider entitlements: ["Internal_Testing"]

Pinned headers: {"Rippling-Api-Version": "2024-08-01"}

Source limitations: ["upstream_response_shaped_request_schema"]

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.