> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/entity-management/terminal-management.md).

# Terminal Management

Use the Terminal Management API to provision and manage terminals that are used to create payments and receive terminal-scoped configuration such as webhooks and enablement settings.

A terminal belongs to a location and merchant and is typically the final provisioning step before payment traffic begins.

{% hint style="warning" %}
**Boarding creates the location and terminals for you.** When a merchant application is boarded through [Onboarding](https://developers.bead.xyz/onboarding.md), Bead creates the merchant, its location, and its terminals as part of boarding. Do not create your own location or terminal for a merchant that is still in onboarding, or before the application reaches `boarded`. Use [Create Terminal](https://developers.bead.xyz/entity-management/terminal-management/create-terminal.md) to add further terminals to a merchant that has already been boarded.
{% endhint %}

#### How records are organized

Each partner is its own ISO instance. There is no root above it that spans partners, so one partner cannot see or manage another partner's records. Any partner tiers sit beneath that ISO. Under a partner, a merchant owns its locations, and a location owns its terminals. See [Advanced Partner Hierarchy](https://developers.bead.xyz/reference-guide/core-concepts/advanced-partner-hierarchy.md) for how tiers are structured.

#### What you can do

* Create terminals under the correct merchant and location
* Retrieve terminal details for configuration and troubleshooting
* Update terminal settings and webhook configuration
* Retrieve or reset a terminal's payments API key
* Disable or delete terminals that should no longer process payments
* Use terminal identifiers in Payments, Reporting, and Settlement workflows

#### Life-cycle at a glance

* **Create:** `POST /Terminals`
* **Read:** `GET /Terminals/{id}`
* **Update:** `PUT /Terminals/{id}`
* **Retrieve payments API key:** `GET /Terminals/{id}/api-keys`
* **Reset payments API key:** `POST /Terminals/{id}/api-keys`
* **Disable:** `PUT /Terminals/{id}` with `isEnabled=false`
* **Delete:** `DELETE /Terminals/{id}`

#### Common terminal attributes

Typical terminal records include values such as:

* `id`
* `merchantId`
* `locationId`
* `name`
* `isEnabled`
* webhook configuration fields
* created and updated timestamps

Refer to the endpoint-specific schemas and examples for the exact request and response models supported in your environment.

#### Typical workflow

1. Confirm the merchant has been boarded and identify its location. Boarding creates the first location and terminals.
2. If you need another terminal, create it under the correct location.
3. Save the returned `terminalId`.
4. Configure webhook behavior if your integration uses event notifications.
5. Use the `terminalId` when creating payments.
6. Update, disable, or delete the terminal as your deployment changes over time.

#### Create a terminal

Create a terminal after the merchant is boarded and the location is available.

```http
POST /Terminals
```

Use the returned terminal record and save the `id` for downstream payment and administration workflows.

#### Get a terminal

Retrieve a terminal when you need to inspect configuration, confirm status, or troubleshoot behavior.

```http
GET /Terminals/{id}
```

#### Update a terminal

Use `PUT`, not `PATCH`, when updating a terminal.

```http
PUT /Terminals/{id}
```

If you are updating a terminal record, send the fields required by the current endpoint contract and examples for this path.

#### Terminal payments API key

Each terminal has its own payments API key. Your backend sends it in the `X-Api-Key` header to create payments and read payment status for that terminal. The full key is returned as `apiKey.secret` when the terminal is created. To get it again, call `GET /Terminals/{id}/api-keys`. To replace it, call `POST /Terminals/{id}/api-keys`. See [Reset Terminal API Key](https://developers.bead.xyz/entity-management/terminal-management/reset-terminal-api-key.md) for both calls.

#### Disable a terminal

To disable a terminal without deleting it, update the terminal using `PUT /Terminals/{id}` and set `isEnabled=false` in the request body where supported by the endpoint model.

```http
PUT /Terminals/{id}
```

This is useful when you want to stop new payment activity while preserving the terminal record for audit, reporting, or later reactivation.

#### Delete a terminal

Delete a terminal only when you no longer need the record for operational use.

```http
DELETE /Terminals/{id}
```

Before deleting a terminal, confirm it is not still referenced by active workflows or deployment tooling.

#### Webhooks and terminal configuration

Terminal records may include webhook-related configuration used to route payment status events to your systems.

When using terminal-level webhook configuration:

* confirm the endpoint is reachable and monitored
* validate event handling in sandbox before production rollout
* design your webhook consumer to process retries safely and idempotently

See [Webhook Management](https://developers.bead.xyz/entity-management/terminal-management/webhook-management.md) for setup details.

#### Operational guidance

* Keep a clear mapping between partner, merchant, location, and terminal records.
* Treat terminal changes as production-impacting configuration updates.
* Prefer disabling a terminal before deleting it when you may need to preserve operational continuity or investigate prior activity.
* Store terminal identifiers in your internal systems so payments and support workflows can reference them consistently.

#### Related APIs

Terminal Management works closely with:

* **Merchant Management** for parent merchant records
* **Location Management** for parent location records
* **Payments** for payment creation using `terminalId`
* **Reporting** and **Settlement** for downstream operational visibility

#### Troubleshooting

* **Terminal not found**\
  Confirm the `id` is correct and belongs to the expected environment.
* **Update method rejected**\
  Use `PUT /Terminals/{id}` for updates. Do not use `PATCH /Terminals/{id}`.
* **Terminal cannot be used for payments**\
  Confirm the terminal is enabled, correctly associated to the expected merchant and location, and referenced with the correct `terminalId` in the payment request.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.bead.xyz/entity-management/terminal-management.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
