Command reference

Every command group in the Plugipay CLI, with examples. Run plugipay <group> --help for inline docs, or plugipay <group> <subcommand> --help for per-command details.

auth

Identity and credential management.

plugipay auth login [--profile <name>] [--token <id:secret>]
plugipay auth logout [--profile <name>]
plugipay auth whoami

See Authentication for the full flow.

customers

CRUD for customer records.

plugipay customers list [--limit N] [--email <email>] [--since 7d]
plugipay customers get <id>
plugipay customers create --email <email> --name <name> [--metadata key=value ...]
plugipay customers update <id> [--email <email>] [--name <name>] [--metadata key=value ...]
plugipay customers delete <id>

Examples:

plugipay customers create --email alice@example.com --name "Alice Tan" \
  --metadata internalUserId=u_42 --metadata tier=pro

plugipay customers list --since 7d --limit 50 --output csv > new-customers.csv

plugipay customers update cus_01HXX --name "Alice Updated"

checkout

Manage checkout sessions — the one-time hosted payment flow.

plugipay checkout create --amount <int> --currency <code> [options]
plugipay checkout get <session_id>
plugipay checkout list [--status <state>] [--since 7d]
plugipay checkout expire <session_id>

Options for create:

--amount <int> — smallest currency unit (cents/sen). Required.
--currency <code> — ISO 4217 (IDR, USD, etc.). Required.
--description <text> — shown on the hosted page.
--success-url <url> — required.
--cancel-url <url> — required.
--customer-id <id> — attach to an existing customer.
--metadata key=value — up to 50, repeat the flag.
--expires-at <epoch> — override the default 24h expiry.

Example:

plugipay checkout create \
  --amount 250000 \
  --currency IDR \
  --description "Pro plan upgrade" \
  --customer-id cus_01HXX \
  --success-url https://example.com/success \
  --cancel-url https://example.com/cancel \
  --metadata invoiceId=inv_001 \
  --output json | jq -r '.url'

refunds

Issue refunds against payments.

plugipay refunds create --payment-id <id> [--amount <int>] [--reason <reason>] [--description <text>]
plugipay refunds get <id>
plugipay refunds list [--payment-id <id>] [--status <state>]

reason is one of: requested_by_customer, duplicate, fraudulent, other.

Examples:

# Full refund
plugipay refunds create --payment-id pay_01HXX --reason requested_by_customer

# Partial refund
plugipay refunds create --payment-id pay_01HXX --amount 100000 --reason duplicate

# List recent failed refunds
plugipay refunds list --status failed --since 7d

subscriptions

Manage recurring billing.

plugipay subscriptions list [--status active|trialing|past_due|canceled]
plugipay subscriptions get <id>
plugipay subscriptions create --customer-id <id> --plan-id <id> [options]
plugipay subscriptions cancel <id> [--at-period-end]
plugipay subscriptions pause <id> [--resume-at <date>]
plugipay subscriptions resume <id>
plugipay subscriptions update <id> [--plan-id <new_id>] [--metadata key=value]

plans

Create and manage subscription plans.

plugipay plans list
plugipay plans get <id>
plugipay plans create --name <name> --amount <int> --currency <code> --interval <interval> [options]
plugipay plans update <id> [options]
plugipay plans archive <id>

interval: day, week, month, year. Combine with --interval-count for every-N-period billing:

plugipay plans create --name "Quarterly Pro" --amount 750000 --currency IDR --interval month --interval-count 3

invoices

plugipay invoices list [--customer-id <id>] [--status open|paid|void]
plugipay invoices get <id>
plugipay invoices send <id>
plugipay invoices void <id>
plugipay invoices pay <id> --payment-method-id <pm_id>

receipts

Receipt records for completed payments.

plugipay receipts list [--payment-id <id>]
plugipay receipts get <id>
plugipay receipts send <id> --email <email>

ledger

Read-only view of the financial ledger.

plugipay ledger entries --since 7d [--type payment|refund|fee|payout]
plugipay ledger export --since 30d --output csv > ledger.csv
plugipay ledger summary --since 30d

webhooks

Manage webhook endpoints.

plugipay webhooks list
plugipay webhooks get <id>
plugipay webhooks add --url <url> --events <event,event,...>
plugipay webhooks update <id> [--url <url>] [--events <...>] [--disable] [--enable]
plugipay webhooks remove <id>
plugipay webhooks rotate-secret <id>

Test locally without exposing your dev box:

# Forward production webhooks to your local server
plugipay webhooks listen --forward-to http://localhost:3000/webhooks

# Trigger a test event
plugipay webhooks trigger --event payment.succeeded --to webhep_01HXX

api-keys

plugipay api-keys list
plugipay api-keys get <id>
plugipay api-keys create --name <name> --role <role>
plugipay api-keys revoke <id>

Roles: full_access, read_only, webhook_management_only, restricted (custom scopes).

plugipay api-keys create --name "Production server" --role full_access

The secret is printed once on create. Save it.

workspaces

plugipay workspaces list
plugipay workspaces get <id>
plugipay workspaces create --name <name>
plugipay workspaces update <id> --name <new_name>
plugipay workspaces switch <id>

account

plugipay account get
plugipay account update [--name <name>] [--email <email>]
plugipay account delete

events

The event stream — what fires when, with filters:

plugipay events list [--type <event.type>] [--since 1h] [--object-id <id>]
plugipay events get <id>
plugipay events tail [--type <event.type>]   # follow new events as they fire

events tail is useful for debugging webhooks:

plugipay events tail --type 'payment.*'

templates

Checkout page templates.

plugipay templates list
plugipay templates get <id>
plugipay templates create --name <name> --body @template.json
plugipay templates update <id> --body @template.json

checkout-settings

Workspace-wide checkout configuration.

plugipay checkout-settings get
plugipay checkout-settings update [--logo-url <url>] [--theme <theme>] [--collect-address]

adapters

Payment provider connections (Xendit, Midtrans, PayPal).

plugipay adapters list
plugipay adapters get <id>
plugipay adapters connect --provider xendit --secret-key <key> --webhook-token <token>
plugipay adapters disconnect <id>
plugipay adapters test <id>

clocks

Test clocks — advance simulated time for test-mode subscriptions.

plugipay clocks list
plugipay clocks create --name <name>
plugipay clocks advance <id> --by 30d
plugipay clocks delete <id>

Useful for testing dunning flows, subscription renewals, and trial expirations without waiting.

portal

Self-serve customer-facing billing portal sessions.

plugipay portal create --customer-id <id> --return-url <url>

Returns a short-lived URL where your customer can manage their own subscriptions, update payment methods, and download invoices.

billing

Workspace billing (Plugipay's bill to you, not yours to your customers).

plugipay billing get
plugipay billing invoices list
plugipay billing invoices get <id>
plugipay billing payment-methods list
plugipay billing payment-methods add --setup-intent-id <id>

uploads

Upload files (logos, brand assets, attachments).

plugipay uploads create --file ./logo.png --purpose brand_logo
plugipay uploads list
plugipay uploads delete <id>

onboarding

Multi-step workspace setup — usually run via the dashboard, but useful for scripting workspace provisioning:

plugipay onboarding status
plugipay onboarding submit-kyc --business-name "Acme Inc." --ein 12-3456789

admin-portal

Admin-only commands (for workspace owners and Plugipay support).

plugipay admin-portal kyc-inbox
plugipay admin-portal disputes

If you don't have admin permissions on the workspace, these return 403.

Global help

plugipay --help                    # top-level: list every command group
plugipay <group> --help            # group: list subcommands
plugipay <group> <sub> --help      # subcommand: list flags

Every help screen is auto-generated from the command definitions, so it's never out of date.

Scripting & automation — CI patterns, batch operations, jq pipelines.
API reference — the underlying HTTP API each command calls.