Close a terminal session

POST

/v1/terminal_sessions/{id}/close

const url = 'https://terminal.api.example.com/v1/terminal_sessions/example/close';
const options = {method: 'POST'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://terminal.api.example.com/v1/terminal_sessions/example/close

Called by the terminal when the cashier stops work. An active or recoverable_interrupted session closes. Closing a closed session answers it unchanged, so it is safe to repeat. Takes no body.

Authorizations

TerminalCertificate

Parameters

Path Parameters

required

string

The object’s id.

Responses

200

The session, closed.

application/json

object

required

The session’s id, used in the path of its heartbeat, resume and close.

string

object

required

string

Allowed value: terminal_session

livemode

required

Always true. A terminal is a live device; there are no test terminals.

boolean

terminal_id

required

The terminal that opened it, the only one that can use it.

string

status

required

active while it takes heartbeats; recoverable_interrupted once it missed them, until it is resumed or its recovery_deadline passes; expired and closed are final.

string

Allowed values: active recoverable_interrupted expired closed

opened_at

required

When it was opened, as a Unix timestamp.

integer

last_heartbeat_at

required

The last time the terminal showed it was alive on it, by opening, a heartbeat or a resume, as a Unix timestamp.

integer

interrupted_at

required

When it was interrupted for missing its heartbeats, while it is recoverable_interrupted.

integer | null

recovery_deadline

required

The last moment it can be resumed, while it is recoverable_interrupted.

integer | null

expires_at

required

When it ends, however well it heartbeats, as a Unix timestamp.

integer

expired_at

required

When it expired, once it is expired.

integer | null

closed_at

required

When it was closed, once it is closed.

integer | null

Example

{
  "id": "6d0f3b8e-2c4a-4f7e-9b1d-8a5c3e7f2b10",
  "object": "terminal_session",
  "livemode": true,
  "terminal_id": "3f6c2a9e-8b41-4d7a-9e25-0c1b7d4f8a63",
  "status": "closed",
  "opened_at": 1791000000,
  "last_heartbeat_at": 1791028800,
  "interrupted_at": null,
  "recovery_deadline": null,
  "expires_at": 1791043200,
  "expired_at": null,
  "closed_at": 1791028815
}

401

authentication_failure with terminal_credential_refused: the certificate does not count, or the terminal is suspended or retired. See Pairing a terminal.

application/json

object

error

required

object

type

required

string

Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure

code

required

A stable name for this refusal. Branch on this, never on message.

string

message

required

For the developer reading a log. May be reworded.

string

param

required

The field or parameter at fault, when there is one.

string | null

request_id

required

string | null

Example

{
  "error": {
    "type": "validation_failure"
  }
}

404

not_found with resource_missing: this terminal has no session with this id. Another terminal’s session reads the same.

application/json

object

error

required

object

type

required

string

Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure

code

required

A stable name for this refusal. Branch on this, never on message.

string

message

required

For the developer reading a log. May be reworded.

string

param

required

The field or parameter at fault, when there is one.

string | null

request_id

required

string | null

Example

{
  "error": {
    "type": "validation_failure"
  }
}

422

invariant_violation with session_expired: the session has already expired, so there is nothing to close.

application/json

object

error

required

object

type

required

string

Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure

code

required

A stable name for this refusal. Branch on this, never on message.

string

message

required

For the developer reading a log. May be reworded.

string

param

required

The field or parameter at fault, when there is one.

string | null

request_id

required

string | null

Example

{
  "error": {
    "type": "validation_failure"
  }
}

503

dependency_failure with service_unavailable: the platform did not answer, or failed part-way. Whether the call took effect is not known. Retry the same request: a heartbeat is safe to repeat, and if a retry is refused because the session is already as the call would leave it (for example session_closed after a close), the first call took effect.

application/json

object

error

required

object

type

required

string

Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure

code

required

A stable name for this refusal. Branch on this, never on message.

string

message

required

For the developer reading a log. May be reworded.

string

param

required

The field or parameter at fault, when there is one.

string | null

request_id

required

string | null

Example

{
  "error": {
    "type": "validation_failure"
  }
}