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). 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 for the full framework on matching tender types to acceptance environment, and Managing Tender Types 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) 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}.