sumup-cli

SumUp CLI tool allows you to manage your SumUp account, create checkouts, and much more all from your terminal.

Getting Started

Installation

Choose one of the following installation methods:

# Homebrew
brew install sumup/cli/sumup

# mise
mise use -g github:sumup/sumup-cli@latest

# Go
go install github.com/sumup/sumup-cli/cmd/sumup

The CLI expects an API key via the SUMUP_API_KEY environment variable by default. You can also pass --api-key explicitly.

export SUMUP_API_KEY=your_api_key

Shell Completion

Generate a completion script for your shell and load it:

# bash
source <(sumup completion bash)

# zsh
source <(sumup completion zsh)

# fish
sumup completion fish > ~/.config/fish/completions/sumup.fish

Release archives also include pre-generated bash, zsh, and fish completion scripts plus a man page (man/man1/sumup.1.gz).

Managing Merchant Context

To avoid repeating the --merchant-code flag in every command, you can set a merchant context:

# Set the merchant context interactively
sumup context set

# View the current merchant context
sumup context get

# Unset the merchant context
sumup context unset

Once set, all commands that accept --merchant-code will use the context value by default. You can still override it by providing the flag explicitly.

Create a Checkout

sumup checkouts create \
  --reference order-123 \
  --amount 19.99 \
  --currency EUR \
  --merchant-code M123 \
  --description "Ticket purchase" \
  --return-url https://example.com/return \
  --redirect-url https://example.com/3ds \
  --customer-id cst_42 \
  --purpose "Event"

Manage Readers

List readers for a merchant:

sumup readers list --merchant-code M123

Pair a new reader with a pairing code:

sumup readers add \
  --merchant-code M123 \
  --pairing-code ABCDEF \
  --name "Front counter"

Trigger a checkout on a reader (this example charges EUR 14.99 and offers tip rates):

sumup readers checkout \
  --merchant-code M123 \
  --reader-id reader_42 \
  --amount 14.99 \
  --currency EUR \
  --tip-rate 0.10 \
  --tip-rate 0.15 \
  --tip-rate 0.20 \
  --description "In-person order #123"

For Pix payments on Brazilian merchants, add --payment-type pix.

When using affiliate attribution, pass both --affiliate-app-id and --affiliate-key. Use --affiliate-foreign-transaction-id to include an optional transaction reference.

Trigger a checkout on a SumUp Go reader. --client-transaction-id is required and used as the idempotency key:

sumup readers go-checkout \
  --merchant-code M123 \
  --amount 14.99 \
  --currency EUR \
  --client-transaction-id 19e12390-72cf-4f9f-80b5-b0c8a67fa43f \
  reader_42

Check the last known status of a paired reader:

sumup readers status \
  --merchant-code M123 \
  reader_42

Read or update Solo reader menu lock settings. Updates require the reader to be online; offline reads return the last saved settings when available.

sumup readers settings get --merchant-code M123 reader_42
sumup readers settings update --merchant-code M123 --menu-lock-enabled=false reader_42

Set SUMUP_READER_MENU_LOCK_PASSCODE to a four-digit PIN to include it in an update. When enabling menu lock on a reader without a PIN, provide the PIN in the same update.

Create a Merchant Token

Create a short-lived merchant token for a SumUp SDK. The command requires --json and returns the access token and its remaining lifetime. Without --json, it exits before creating a token:

sumup --json tokens create --merchant-code M123 --action checkout

OpenAPI Command Coverage

The CLI keeps its user-facing command implementations handwritten, but derives an operation catalog from the OpenAPI document shipped with the exact sumup-go version pinned in go.mod. The catalog records operation IDs, SDK clients and methods, HTTP paths, parameters, and request-body metadata.

Run the generator after updating sumup-go:

make generate

Each API leaf binds its generated OpenAPI operation ID directly in the command definition. Tests enforce a one-to-one relationship between the pinned SDK, the generated catalog, and the CLI command tree, so an SDK upgrade fails CI until every new endpoint has exactly one corresponding command.

Developer Portal Code Samples

Generate a deterministic, portal-compatible JSON catalog containing one CLI code sample for every OpenAPI operation exposed by the CLI:

VERSION=v0.1.0 make generate-codesamples

The catalog is written to code-samples.json by default. Set CODESAMPLES_OUT to use a different path. The generated file uses the same versioned schema as the SDK sample catalogs and is not committed to this repository. Published releases automatically open or update a pull request that writes the catalog to src/codesamples/cli.json in sumup/sumup-developer.