Skip to content

chore: update CLI code samples #905

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
matoous merged 1 commit into from
Aug 15, 2026
+371 −0
Merged

chore: update CLI code samples #905

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
371 changes: 371 additions & 0 deletions src/codesamples/cli.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,371 @@
{
"schemaVersion": 1,
"language": "bash",
"sdk": {
"module": "github.com/sumup/sumup-cli",
"version": "v0.2.0"
},
"openAPIVersion": "1.0.0",
"samples": [
{
"id": "CreateApplePaySession",
"operationId": "CreateApplePaySession",
"summary": "Create an Apple Pay session",
"description": "Creates an Apple Pay merchant session for the specified checkout.\n\nUse this endpoint after the customer selects Apple Pay and before calling\n`ApplePaySession.completeMerchantValidation(...)` in the browser.\nSumUp validates the merchant session request and returns the Apple Pay\nsession object that your frontend should pass to Apple's JavaScript API.",
"httpMethod": "PUT",
"path": "/v0.2/checkouts/{checkout_id}/apple-pay-session",
"sample": "sumup checkouts apple-pay-session \"$CHECKOUT_ID\" \\\n --context \"example.com\" \\\n --target \"https://apple-pay-gateway-cert.apple.com/paymentservices/startSession\"\n"
},
{
"id": "CreateCheckout",
"operationId": "CreateCheckout",
"summary": "Create a checkout",
"description": "Creates a new payment checkout resource. The unique `checkout_reference` created by this request, is used for further manipulation of the checkout.\n\nFor 3DS checkouts, add the `redirect_url` parameter to your request body schema.\nTo use the [Hosted Checkout](https://developer.sumup.com/online-payments/checkouts/hosted-checkout/) page, set the `hosted_checkout.enabled` to `true`.\n\nFollow by processing a checkout to charge the provided payment instrument.",
"httpMethod": "POST",
"path": "/v0.1/checkouts",
"sample": "sumup checkouts create \\\n --reference \"order-123\" \\\n --amount \"10.00\" \\\n --currency \"EUR\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "CreateCustomer",
"operationId": "CreateCustomer",
"summary": "Create a customer",
"description": "Creates a new saved customer resource which you can later manipulate and save payment instruments to.",
"httpMethod": "POST",
"path": "/v0.1/customers",
"sample": "sumup customers create \\\n --email \"customer@example.com\"\n"
},
{
"id": "CreateMerchantMember",
"operationId": "CreateMerchantMember",
"summary": "Create a member",
"description": "Create a merchant member.",
"httpMethod": "POST",
"path": "/v0.1/merchants/{merchant_code}/members",
"sample": "sumup members create \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\" \\\n --email \"member@example.com\" \\\n --password \"$MEMBER_PASSWORD\" \\\n --role \"role_employee\"\n"
},
{
"id": "CreateMerchantRole",
"operationId": "CreateMerchantRole",
"summary": "Create a role",
"description": "Create a custom role for the merchant. Roles are defined by the set of permissions that they grant to the members that they are assigned to.",
"httpMethod": "POST",
"path": "/v0.1/merchants/{merchant_code}/roles",
"sample": "sumup roles create \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\" \\\n --name \"Example\" \\\n --permission \"members_access\"\n"
},
{
"id": "CreateReader",
"operationId": "CreateReader",
"summary": "Create a Reader",
"description": "Create a new Reader for the merchant account.",
"httpMethod": "POST",
"path": "/v0.1/merchants/{merchant_code}/readers",
"sample": "sumup readers add \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\" \\\n --pairing-code \"4WLFDSBF\" \\\n --name \"Example\"\n"
},
{
"id": "CreateReaderCheckout",
"operationId": "CreateReaderCheckout",
"summary": "Create a Reader Checkout",
"description": "Creates a Checkout for a Reader.\n\nThis process is asynchronous and the actual transaction may take some time to be started on the device.\n\n\nThere are some caveats when using this endpoint:\n* The target device must be online, otherwise checkout won't be accepted\n* After the checkout is accepted, the system has 60 seconds to start the payment on the target device. During this time, any other checkout for the same device will be rejected.\n\n\n**Note**: If the target device is a Solo, it must be in version 3.3.24.3 or higher.",
"httpMethod": "POST",
"path": "/v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout",
"sample": "sumup readers checkout \"$READER_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\" \\\n --amount \"10.00\" \\\n --currency \"EUR\"\n"
},
{
"id": "CreateReaderTerminate",
"operationId": "CreateReaderTerminate",
"summary": "Terminate a Reader Checkout",
"description": "Terminate a Reader Checkout stops the current transaction on the target device.\n\nThis process is asynchronous and the actual termination may take some time to be performed on the device.\n\n\nThere are some caveats when using this endpoint:\n* The target device must be online, otherwise terminate won't be accepted\n* The action will succeed only if the device is waiting for cardholder action: e.g: waiting for card, waiting for PIN, etc.\n* There is no confirmation of the termination.\n\nIf a transaction is successfully terminated and `return_url` was provided on Checkout, the transaction status will be sent as `failed` to the provided URL.\n\n\n**Note**: If the target device is a Solo, it must be in version 3.3.28.0 or higher.",
"httpMethod": "POST",
"path": "/v0.1/merchants/{merchant_code}/readers/{reader_id}/terminate",
"sample": "sumup readers terminate \"$READER_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "DeactivateCheckout",
"operationId": "DeactivateCheckout",
"summary": "Deactivate a checkout",
"description": "Deactivates an identified checkout resource. If the checkout has already been processed it can not be deactivated.",
"httpMethod": "DELETE",
"path": "/v0.1/checkouts/{checkout_id}",
"sample": "sumup checkouts deactivate \"$CHECKOUT_ID\"\n"
},
{
"id": "DeactivatePaymentInstrument",
"operationId": "DeactivatePaymentInstrument",
"summary": "Deactivate a payment instrument",
"description": "Deactivates an identified card payment instrument resource for a customer.",
"httpMethod": "DELETE",
"path": "/v0.1/customers/{customer_id}/payment-instruments/{token}",
"sample": "sumup customers payment-instruments deactivate \"$CUSTOMER_ID\" \"$PAYMENT_INSTRUMENT_TOKEN\"\n"
},
{
"id": "DeleteMerchantMember",
"operationId": "DeleteMerchantMember",
"summary": "Delete a member",
"description": "Deletes a merchant member.",
"httpMethod": "DELETE",
"path": "/v0.1/merchants/{merchant_code}/members/{member_id}",
"sample": "sumup members delete \"$MEMBER_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "DeleteMerchantRole",
"operationId": "DeleteMerchantRole",
"summary": "Delete a role",
"description": "Delete a custom role.",
"httpMethod": "DELETE",
"path": "/v0.1/merchants/{merchant_code}/roles/{role_id}",
"sample": "sumup roles delete \"$ROLE_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "DeleteReader",
"operationId": "DeleteReader",
"summary": "Delete a reader",
"description": "Delete a reader.",
"httpMethod": "DELETE",
"path": "/v0.1/merchants/{merchant_code}/readers/{reader_id}",
"sample": "sumup readers delete \"$READER_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "GetCheckout",
"operationId": "GetCheckout",
"summary": "Retrieve a checkout",
"description": "Retrieves an identified checkout resource. Use this request after processing a checkout to confirm its status and inform the end user respectively.",
"httpMethod": "GET",
"path": "/v0.1/checkouts/{checkout_id}",
"sample": "sumup checkouts get \"$CHECKOUT_ID\"\n"
},
{
"id": "GetCustomer",
"operationId": "GetCustomer",
"summary": "Retrieve a customer",
"description": "Retrieves an identified saved customer resource through the unique `customer_id` parameter, generated upon customer creation.",
"httpMethod": "GET",
"path": "/v0.1/customers/{customer_id}",
"sample": "sumup customers get \"$CUSTOMER_ID\"\n"
},
{
"id": "GetMerchant",
"operationId": "GetMerchant",
"summary": "Get Merchant",
"description": "Returns a Merchant for a valid Merchant code.",
"httpMethod": "GET",
"path": "/v1/merchants/{merchant_code}",
"sample": "sumup merchants get \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "GetMerchantMember",
"operationId": "GetMerchantMember",
"summary": "Retrieve a member",
"description": "Retrieve a merchant member.",
"httpMethod": "GET",
"path": "/v0.1/merchants/{merchant_code}/members/{member_id}",
"sample": "sumup members get \"$MEMBER_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "GetMerchantRole",
"operationId": "GetMerchantRole",
"summary": "Retrieve a role",
"description": "Retrieve a custom role by ID.",
"httpMethod": "GET",
"path": "/v0.1/merchants/{merchant_code}/roles/{role_id}",
"sample": "sumup roles get \"$ROLE_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "GetPaymentMethods",
"operationId": "GetPaymentMethods",
"summary": "Get available payment methods",
"description": "Get payment methods available for the given merchant to use with a checkout.",
"httpMethod": "GET",
"path": "/v0.1/merchants/{merchant_code}/payment-methods",
"sample": "sumup checkouts payment-methods \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "GetPerson",
"operationId": "GetPerson",
"summary": "Get Person",
"description": "Returns a single Person related to a Merchant.",
"httpMethod": "GET",
"path": "/v1/merchants/{merchant_code}/persons/{person_id}",
"sample": "sumup merchants persons get \"$PERSON_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "GetReader",
"operationId": "GetReader",
"summary": "Retrieve a Reader",
"description": "Retrieve a Reader.",
"httpMethod": "GET",
"path": "/v0.1/merchants/{merchant_code}/readers/{reader_id}",
"sample": "sumup readers get \"$READER_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "GetReaderStatus",
"operationId": "GetReaderStatus",
"summary": "Get a Reader Status",
"description": "Provides the last known status for a Reader.\n\nThis endpoint allows you to retrieve updates from the connected card reader, including the current screen being displayed during the payment process and the device status (battery level, connectivity, and update state).\n\nSupported States\n\n* `IDLE` – Reader ready for next transaction\n* `SELECTING_TIP` – Waiting for tip input\n* `WAITING_FOR_CARD` – Awaiting card insert/tap\n* `WAITING_FOR_PIN` – Waiting for PIN entry\n* `WAITING_FOR_SIGNATURE` – Waiting for customer signature\n* `UPDATING_FIRMWARE` – Firmware update in progress\n\nDevice Status\n\n* `ONLINE` – Device connected and operational\n* `OFFLINE` – Device disconnected (last state persisted)\n\n**Note**: If the target device is a Solo, it must be in version 3.3.39.0 or higher.",
"httpMethod": "GET",
"path": "/v0.1/merchants/{merchant_code}/readers/{reader_id}/status",
"sample": "sumup readers status \"$READER_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "GetReceipt",
"operationId": "GetReceipt",
"summary": "Retrieve receipt details",
"description": "Retrieves receipt specific data for a transaction.",
"httpMethod": "GET",
"path": "/v1.1/receipts/{transaction_id}",
"sample": "sumup receipts get \"$TRANSACTION_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "GetTransactionV2.1",
"operationId": "GetTransactionV2.1",
"summary": "Retrieve a transaction",
"description": "Retrieves the full details of an identified transaction. The transaction resource is identified by a query parameter and *one* of following parameters is required:\n- `id`\n- `transaction_code`\n- `foreign_transaction_id`\n- `client_transaction_id`",
"httpMethod": "GET",
"path": "/v2.1/merchants/{merchant_code}/transactions",
"sample": "sumup transactions get \"$TRANSACTION_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "ListCheckouts",
"operationId": "ListCheckouts",
"summary": "List checkouts",
"description": "Lists created checkout resources according to the applied `checkout_reference`.",
"httpMethod": "GET",
"path": "/v0.1/checkouts",
"sample": "sumup checkouts list\n"
},
{
"id": "ListMemberships",
"operationId": "ListMemberships",
"summary": "List memberships",
"description": "List memberships of the current user.",
"httpMethod": "GET",
"path": "/v0.1/memberships",
"sample": "sumup memberships list\n"
},
{
"id": "ListMerchantMembers",
"operationId": "ListMerchantMembers",
"summary": "List members",
"description": "Lists merchant members.",
"httpMethod": "GET",
"path": "/v0.1/merchants/{merchant_code}/members",
"sample": "sumup members list \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "ListMerchantRoles",
"operationId": "ListMerchantRoles",
"summary": "List roles",
"description": "List merchant's custom roles.",
"httpMethod": "GET",
"path": "/v0.1/merchants/{merchant_code}/roles",
"sample": "sumup roles list \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "ListPaymentInstruments",
"operationId": "ListPaymentInstruments",
"summary": "List payment instruments",
"description": "Lists all payment instrument resources that are saved for an identified customer.",
"httpMethod": "GET",
"path": "/v0.1/customers/{customer_id}/payment-instruments",
"sample": "sumup customers payment-instruments list \"$CUSTOMER_ID\"\n"
},
{
"id": "ListPayoutsV1",
"operationId": "ListPayoutsV1",
"summary": "List payouts",
"description": "Lists payout and payout-deduction records for the specified merchant account within the requested date range.\n\nThe response can include:\n- regular payouts (`type = PAYOUT`)\n- deduction records for refunds, chargebacks, direct debit returns, or balance adjustments\n\nResults are sorted by payout date in the requested `order`.",
"httpMethod": "GET",
"path": "/v1.0/merchants/{merchant_code}/payouts",
"sample": "sumup payouts list \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\" \\\n --start-date \"2026-01-01\" \\\n --end-date \"2026-01-31\"\n"
},
{
"id": "ListPersons",
"operationId": "ListPersons",
"summary": "List Persons",
"description": "Returns the Persons related to a Merchant.",
"httpMethod": "GET",
"path": "/v1/merchants/{merchant_code}/persons",
"sample": "sumup merchants persons list \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "ListReaders",
"operationId": "ListReaders",
"summary": "List Readers",
"description": "List all readers of the merchant.",
"httpMethod": "GET",
"path": "/v0.1/merchants/{merchant_code}/readers",
"sample": "sumup readers list \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "ListTransactionsV2.1",
"operationId": "ListTransactionsV2.1",
"summary": "List transactions",
"description": "Lists detailed history of all transactions associated with the merchant profile.",
"httpMethod": "GET",
"path": "/v2.1/merchants/{merchant_code}/transactions/history",
"sample": "sumup transactions list \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "ProcessCheckout",
"operationId": "ProcessCheckout",
"summary": "Process a checkout",
"description": "Processing a checkout will attempt to charge the provided payment instrument for the amount of the specified checkout resource initiated in the `Create a checkout` endpoint.\n\nFollow this request with `Retrieve a checkout` to confirm its status.",
"httpMethod": "PUT",
"path": "/v0.1/checkouts/{checkout_id}",
"sample": "sumup checkouts process \"$CHECKOUT_ID\" \\\n --payment-type \"card\" \\\n --customer-id \"$CUSTOMER_ID\" \\\n --token \"$PAYMENT_INSTRUMENT_TOKEN\"\n"
},
{
"id": "RefundTransaction",
"operationId": "RefundTransaction",
"summary": "Refund a transaction",
"description": "Refunds an identified transaction either in full or partially.",
"httpMethod": "POST",
"path": "/v1.0/merchants/{merchant_code}/payments/{transaction_id}/refunds",
"sample": "sumup transactions refund \"$TRANSACTION_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\"\n"
},
{
"id": "UpdateCheckout",
"operationId": "UpdateCheckout",
"summary": "Update a checkout",
"description": "Updates an identified checkout resource.",
"httpMethod": "PATCH",
"path": "/v0.1/checkouts/{checkout_id}",
"sample": "sumup checkouts update \"$CHECKOUT_ID\" \\\n --description \"Updated order\"\n"
},
{
"id": "UpdateCustomer",
"operationId": "UpdateCustomer",
"summary": "Update a customer",
"description": "Updates an identified saved customer resource's personal details.\n\nThe request only overwrites the parameters included in the request, all other parameters will remain with their initially assigned values.",
"httpMethod": "PUT",
"path": "/v0.1/customers/{customer_id}",
"sample": "sumup customers update \"$CUSTOMER_ID\" \\\n --email \"updated-customer@example.com\"\n"
},
{
"id": "UpdateMerchantMember",
"operationId": "UpdateMerchantMember",
"summary": "Update a member",
"description": "Update the merchant member.",
"httpMethod": "PUT",
"path": "/v0.1/merchants/{merchant_code}/members/{member_id}",
"sample": "sumup members update \"$MEMBER_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\" \\\n --role \"role_employee\"\n"
},
{
"id": "UpdateMerchantRole",
"operationId": "UpdateMerchantRole",
"summary": "Update a role",
"description": "Update a custom role.",
"httpMethod": "PATCH",
"path": "/v0.1/merchants/{merchant_code}/roles/{role_id}",
"sample": "sumup roles update \"$ROLE_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\" \\\n --name \"Payment reviewer\"\n"
},
{
"id": "UpdateReader",
"operationId": "UpdateReader",
"summary": "Update a Reader",
"description": "Update a Reader.",
"httpMethod": "PATCH",
"path": "/v0.1/merchants/{merchant_code}/readers/{reader_id}",
"sample": "sumup readers update \"$READER_ID\" \\\n --merchant-code \"$SUMUP_MERCHANT_CODE\" \\\n --name \"Example\"\n"
}
]
}