# System pages

Assigns site pages to system roles — cart, checkout, customer account and others — reads the assignments, returns a page URL by role, and removes roles one at a time or all at once. The pages themselves stay on the site when a role is removed.

Bitrix24 API: `landing.syspage.get`, `landing.syspage.set`, `landing.syspage.getSpecialPage`, `landing.syspage.deleteForSite`
Scope: `landing`

## Operations

- [List site system pages](./system-pages-list.md) — `GET /v1/sites/:id/system-pages`
- [Assign a system page](./system-pages-set.md) — `PUT /v1/sites/:id/system-pages/:type`
- [Get a system page URL](./system-pages-url.md) — `GET /v1/sites/:id/system-pages/:type/url`
- [Remove a system page](./system-pages-delete-delete.md) — `DELETE /v1/sites/:id/system-pages/:type`
- [Remove all site system pages](./system-pages-delete.md) — `DELETE /v1/sites/:id/system-pages`

## Roles

The role is passed in the request path as `type` and comes back in the `type` response field. Values not in the table below are rejected with `400 INVALID_PARAMS` before any call to Bitrix24.

| Role | Page |
|------|----------|
| `mainpage` | Home page |
| `catalog` | Product catalog |
| `personal` | Customer account |
| `cart` | Cart |
| `order` | Checkout |
| `payment` | Order payment |
| `compare` | Product comparison |
| `feedback` | Feedback |

## Key fields

Fields of a single binding. They are returned in every element of the list, assign and single-role remove responses.

| Field | Description |
|------|----------|
| `type` | Role from the table above |
| `pageId` | ID of the page assigned to the role. Site pages: [`GET /v1/pages?filter[siteId]=:id`](/docs/entities/pages/list) |
| `title` | Page title |
| `deleted` | The page is in the trash |
| `active` | The page is published |

## Before you start

1. **One page per role, any number of roles per page.** Assigning to an occupied role replaces the page on it. The same page can hold several roles at once.
2. **Only a page of the same site can be assigned.** A page from another site returns `400 INVALID_PARAMS`, and a nonexistent page returns `404 ENTITY_NOT_FOUND`. The page does not need to be published before assignment.
3. **The trash does not remove a role.** A page moved to the trash keeps its role with `deleted: true`, and its URL by role is still returned. A role is removed only explicitly.
4. **Writes are verified by rereading.** After a change, write methods reread the site bindings and return them. If the change was not saved, the response is `422 BITRIX_ERROR`, not `200`.
5. **Repeats behave differently.** Reassigning the same page and removing all roles again both return `200`. Removing a single role again returns `404 ENTITY_NOT_FOUND`.
6. **Site in a separate scope: knowledge base, workgroup or the `MAINPAGE` scope.** For such a site, pass the `scope` query parameter set to `KNOWLEDGE`, `GROUP` or `MAINPAGE` — without it the site is not found and `404` is returned. For an ordinary site, omit `scope`.

## Typical workflow

1. Find the site: [`GET /v1/sites`](/docs/entities/sites/list).
2. Find the site pages: [`GET /v1/pages?filter[siteId]=:id`](/docs/entities/pages/list).
3. Check which roles are already taken: [`GET /v1/sites/:id/system-pages`](./system-pages-list.md).
4. Assign a page to a role: [`PUT /v1/sites/:id/system-pages/cart`](./system-pages-set.md) with `pageId`.
5. Get the page URL by role to use in a link: [`GET /v1/sites/:id/system-pages/cart/url`](./system-pages-url.md).

## Limits

| Limit | Value |
|-------|----------|
| Bindings per site | At most eight — one per role. The list has no pagination |
| Roles per call | One when assigning and removing. [`DELETE /v1/sites/:id/system-pages`](./system-pages-delete.md) removes all at once |
| Request rate | General API limits — [Limits and optimization](/docs/optimization) |

## See also

- [Sites](/docs/entities/sites)
- [Pages](/docs/entities/pages)
- [Page system roles](/docs/entities/pages/system-pages)
- [Page public URL](/docs/entities/pages/public-url)
- [Limits and optimization](/docs/optimization)