> 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/terminal-lifecycle-concepts.md). # Terminal Lifecycle (Concepts) A terminal moves through a simple lifecycle: creation, configuration, active use, updates, and retirement. This page explains the typical phases and the API calls commonly used at each step. Use the top-level terminal creation pattern: * `POST /Terminals` Include `locationId` in the request body when creating a terminal rather than calling a nested location terminal creation URL. #### Overview A typical terminal lifecycle looks like this: 1. Create the terminal 2. Configure or update terminal settings 3. Use the terminal in active operations 4. Manage related webhook configuration if applicable 5. Retire or delete the terminal when it is no longer needed The allowed methods for an individual terminal resource are: * `GET /Terminals/{id}` * `PUT /Terminals/{id}` * `DELETE /Terminals/{id}` Do not use `PATCH /Terminals/{id}` unless and until the OpenAPI spec explicitly supports it. #### Terminal type: physical vs. virtual Every terminal is created with a `type` of either `virtual` or `physical` (see [Create Terminal](/entity-management/terminal-management/create-terminal.md)). These are not interchangeable labels — they represent genuinely different acceptance environments, and Bead applies different standing tender-type policy to each: | Type | Acceptance environment | Standing tender default | | ---------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `virtual` | Online or remote acceptance — hosted checkout, eCommerce, invoicing, or any flow with no customer physically present. | All approved tender types enabled by default. | | `physical` | In-person acceptance — point-of-sale or service counter, where a customer is typically physically present and waiting. | BTC (on-chain) disabled by default. On-chain confirmation is long-running and generally unsuitable for a customer waiting at a counter; other approved tenders remain enabled. | Because these two policies cannot coexist on a single terminal, `type` is not cosmetic — it is set once at creation (see Create Terminal) and cannot be changed later. See [Choosing Tender Types by Payment Environment](/reference-guide/payment-flows/choosing-tender-types-by-payment-environment.md) for the full framework on matching tender types to acceptance environment, and [Managing Tender Types](/entity-management/terminal-management/managing-tender-types.md) for how the approved tender set flows down to a terminal. **Multi-terminal merchants.** A merchant that accepts payments in more than one environment needs a separate terminal per environment — a merchant with both physical point-of-sale and online checkout needs at least one `physical` terminal and one `virtual` terminal. It is common for a single merchant to have several terminals across locations, channels, and use cases. #### Phases **1. Create** Create a terminal with: * `POST /Terminals` Provide the required terminal details in the request body, including `locationId` and `type`. Use this phase when you are provisioning a terminal for a location and preparing it for operational use. Decide `type` (`virtual` or `physical`) at this point — see [Terminal Lifecycle (Concepts)](/entity-management/terminal-management/terminal-lifecycle-concepts.md#terminal-type-physical-vs-virtual) above — since it cannot be changed after creation. **2. Retrieve** Retrieve terminal details with: * `GET /Terminals/{id}` Use this to confirm the current terminal record, review configuration, or verify identifiers before making updates. **3. Update** Update an existing terminal with: * `PUT /Terminals/{id}` Use this when you need to change terminal settings or maintain the terminal record. `type` cannot be changed via this endpoint — create a new terminal if a different type is needed. If webhook configuration is managed separately in your implementation, use the webhook-specific endpoint documented for that purpose, for example: * `PUT /Terminals/{id}/webhook` Do not use malformed references such as: * `PUT /Terminals/{id}PUT` * `PATCH /Terminals/{id}` **4. Active Use** Once created and configured, the terminal can be used in the flows supported by your implementation, such as payment and operational workflows tied to that terminal. During active use, you may periodically retrieve the terminal record to confirm its current configuration: * `GET /Terminals/{id}` And update it as needed: * `PUT /Terminals/{id}` **5. Retirement** When a terminal is no longer needed, remove it with: * `DELETE /Terminals/{id}` Before deleting a terminal, confirm it is no longer required by any active workflow, integration, or reporting dependency. #### Recommended Lifecycle Pattern A common lifecycle sequence is: 1. Create the terminal with `POST /Terminals`, choosing `type` deliberately for the acceptance environment it will serve 2. Confirm the record with `GET /Terminals/{id}` 3. Update settings with `PUT /Terminals/{id}` as needed 4. Maintain any related webhook configuration through its documented endpoint 5. Delete the terminal with `DELETE /Terminals/{id}` when it is retired #### Endpoint Notes Use these endpoint forms on this page: * `POST /Terminals` * `GET /Terminals/{id}` * `PUT /Terminals/{id}` * `DELETE /Terminals/{id}` If webhook management applies, reference the webhook endpoint exactly as documented elsewhere in the terminal management docs. Avoid these incorrect forms: * `PATCH /Terminals/{id}` * `PUT /Terminals/{id}PUT` #### Summary The terminal lifecycle is centered on a straightforward create, retrieve, update, and delete pattern. Create terminals at the top level with `POST /Terminals`, choosing `type` (`virtual` or `physical`) deliberately since it is permanent, include `locationId` in the request body, update terminals with `PUT /Terminals/{id}`, and retire them with `DELETE /Terminals/{id}`. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/entity-management/terminal-management/terminal-lifecycle-concepts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.