---
title: "Payload types"
description: "The REST response envelope — PayloadTime, GetPayload, ListPayload, BatchPayload, SuccessPayload, and the Payload union, with a note on the v2 vs v3 envelope status."
canonical_url: "https://bitrix24.github.io/b24jssdk/docs/working-with-the-rest-api/types-payloads"
last_updated: "2026-07-03"
---
# Payload types

> The REST response envelope — PayloadTime, GetPayload, ListPayload, BatchPayload, SuccessPayload, and the Payload union, with a note on the v2 vs v3 envelope status.

The types in `types/payloads.ts` model the JSON envelope Bitrix24 wraps around every REST response. Most application code never touches these directly — the `actions.v{2,3}.*` helpers unwrap them and hand you [`SuccessPayload`](#successpayload) via `AjaxResult.getData()`. They are documented here because they are re-exported from `@bitrix24/b24jssdk` and describe the raw wire shape.

> [!NOTE]
> The Bitrix24 REST API always wraps a **successful** response in `{ result, time }` — this holds for both `restApi:v2` and `restApi:v3`. The differences below are confined to the *list* and *batch* envelopes, whose extra pagination fields are v2-only.

## `PayloadTime`

The timing block attached to every response envelope. Present on both v2 and v3.

```ts-type
type PayloadTime = {
  readonly start: number
  readonly finish: number
  readonly duration: number
  readonly processing: number
  readonly date_start: ISODate
  readonly date_finish: ISODate
  readonly operating_reset_at: number  // timestamp when part of the method limit is released
  readonly operating: number           // execution time counted against the method limit
}
```

## `GetPayload`

The envelope for a single-item read — the common `{ result, time }` shape.

```ts-type
type GetPayload<P> = {
  readonly result: P
  readonly time: PayloadTime
}
```

## `ListPayload`

The envelope for a **v2** list method. `total` and `next` are the v2 offset-pagination fields.

```ts-type
type ListPayload<P> = {
  readonly result: P[]
  readonly total: number
  readonly next?: number
  readonly time: PayloadTime
}
```

> [!CAUTION]
> `total` and `next` are **v2-only**. `restApi:v3` uses cursor-based paging and has no direct counterpart for them in the same envelope. In source, `ListPayload` still carries a `@todo ! add api3` marker — the v3 list envelope variant is **not yet modelled** as a distinct type. You should not need it: `actions.v{2,3}.callList` / `fetchList` walk pages internally, so consumers read the aggregated result, not `next` / `total`.

## `BatchPayload` / `BatchPayloadResult`

The envelope for a batch request. Results, errors, totals, next-offsets, and per-call timing are keyed either by the caller's command keys or positionally.

```ts-type
type BatchPayloadResult<C> = {
  readonly result:
    | { readonly [P in keyof C]?: C[P] }
    | ReadonlyArray<C[keyof C]>
  readonly result_error:
    | { readonly [P in keyof C]?: string }
    | readonly string[]
  readonly result_total:
    | { readonly [P in keyof C]?: number }
    | readonly number[]
  readonly result_next:
    | { readonly [P in keyof C]?: number }
    | readonly number[]
  readonly result_time:
    | { readonly [P in keyof C]?: PayloadTime }
    | readonly PayloadTime[]
}

type BatchPayload<C> = {
  readonly result: BatchPayloadResult<C>
  readonly time: PayloadTime
}
```

> [!CAUTION]
> `BatchPayloadResult` describes the **v2** batch envelope and carries a `@todo ! add api3` marker in source; the v3 batch variant is not yet modelled here. Prefer `actions.v{2,3}.batch` / `batchByChunk`, which parse this envelope for you.

## `SuccessPayload`

The public shape of a successful response, as returned by `AjaxResult.getData()`. This is the type most consumers actually see.

```ts-type
type SuccessPayload<P> = {
  readonly result: P
  readonly time: PayloadTime
}
```

`SuccessPayload` is intentionally the common `{ result, time }` shape — identical for v2 and v3. The v2-only list fields (`next`, `total`) are **deliberately excluded**: they have no `restApi:v3` counterpart, and the SDK's `callList` / `fetchList` helpers handle pagination internally, so consumers never read them off the envelope.

## `Payload`

The full discriminated envelope a raw response can be — either an error description (v2 or v3) or one of the success envelopes above.

```ts-type
type Payload<P> =
  | TypeDescriptionErrorV3   // v3 error envelope
  | TypeDescriptionError     // v2 error envelope
  | GetPayload<P>
  | ListPayload<P>
  | BatchPayload<P>
```

> [!NOTE]
> `Payload` carries a `@todo ! add api3 tail / add / update and etc` marker in source: the v3-specific success variants (tail paging, add/update responses) are still being filled in. The error arms already model both versions — `TypeDescriptionError` (v2) and `TypeDescriptionErrorV3` (v3), both defined in [`types/auth.ts`](https://github.com/bitrix24/b24jssdk/blob/main/packages/jssdk/src/types/auth.ts){rel="[\"nofollow\"]"}.

## Related

- [`IResult` / `AjaxResult`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/types-iresult.md) — `AjaxResult.getData()` returns `SuccessPayload<T>` on success.
- [`AjaxResult`](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/core-ajax-result.md) — decodes the raw `Payload` envelope, including the error arms.
- [Common types](https://bitrix24.github.io/b24jssdk/raw/docs/working-with-the-rest-api/types-common.md) — `ISODate` and the scalar aliases used inside these envelopes.

## Sitemap

See the full [sitemap](/b24jssdk/sitemap.md) for all pages.