Resource commands

Resource commands work with entities in your Paddle account, like products, customers, and subscriptions. They're generated from the Paddle API, and each command matches an API operation.

Learn how resource commands work on this page, then use the API reference to see what each command does, which fields it accepts, and what it returns.

Mapping to the API

The structure of resource commands follows this pattern:

paddle <resource> <operation> [ID] [flags]

Each part of the command comes from the API:

Here's how some API operations map to full CLI commands:

Run paddle <resource> --help to see every operation for a resource in your installed version of the CLI. For details about each operation, see the API reference.

New API operations and query parameters come to the CLI in a new version. If your version doesn't have a command for an operation yet, update the CLI, or use paddle api to call the endpoint directly:

paddle api /subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/history

Paddle IDs

Commands that work with one entity, like get, update, or cancel, take its Paddle ID as an argument:

paddle customers get ctm_01hv6y1jedq4p1n0yqn5ba3ky4

When a command takes more than one ID, pass them in the order they appear in the endpoint path. For example, paddle addresses get takes the customer ID, then the address ID, like GET /customers/{customer_id}/addresses/{address_id}:

paddle addresses get ctm_01hv6y1jedq4p1n0yqn5ba3ky4 add_01hv8gq3318ktkfengj2r75gfx

Only IDs in the endpoint path are arguments. To check which IDs a command takes, and in what order, run it with --help.

To find an ID, run a list command, like paddle customers list, or copy it from the Paddle dashboard.

Query parameters

Query parameters become flags in the CLI, with underscores changed to hyphens. For example, per_page becomes --per-page, and order_by becomes --order-by.

paddle customers list --status active --email jo@example.com
paddle transactions list --subscription-id sub_01h3h3a9sfpr5syq38tq0sd4sp --per-page 10

Put values that contain square brackets in quotes, like --order-by 'billed_at[ASC]'.

Where the API accepts a comma-separated list, the flag does too:

paddle products list --status active,archived --include prices

Resource commands only accept exact dates. To filter by a date range, like transactions billed before a date, use paddle api:

paddle api /transactions --query 'billed_at[LT]=2026-10-01T00:00:00Z'

Request bodies

Commands that send a request body, like create, update, and cancel, take it as JSON with --json. Pass it inline, or from a file with @:

paddle products create --json '{"name": "AeroEdit Student", "tax_category": "standard"}'
paddle products create --json @product.json

The CLI checks that your JSON is valid before it sends anything.

Fields in the request body are the same as in the API reference. To see them in your terminal, use --help for a readable list or --schema for the full JSON schema:

paddle products create --help
paddle products create --schema

Output

The CLI can return results as a table, JSON, or CSV. In a terminal, results show as a table. When you send output to another program or a file, the CLI uses JSON instead.

Choose a different format with --output, or -o for short:

paddle products get pro_01htz88xpr0mm7b3ta2pjkr7w2 --output json
paddle customers list -o csv > customers.csv

Tables truncate nested fields, like a subscription's items or scheduled_change. To see their full values, use --output json. In a terminal, the JSON is indented for easier reading.

JSON output is the same as the Paddle API response, with meta.environment added to show which account the command ran against, sandbox or production.

To change the default, run paddle output json or set the PADDLE_OUTPUT environment variable.

Filter results

Use --jq to filter or reshape results with a jq expression. You don't need jq installed.

paddle customers list --jq '.data | map({id, email})'
paddle customers list --jq '.data | length'

The filter runs before the CLI formats results. It works with tables and CSV too.

Pagination

List commands return one page of results. Use --per-page to set how many results to return, and --after to get the next page. When there are more results, the CLI prints the command for the next page.

paddle customers list --per-page 50
paddle customers list --per-page 50 --after ctm_01hv6y1jedq4p1n0yqn5ba3ky4

In JSON output, the command for the next page is in meta.pagination.next_command. For more on how pagination works, see Pagination.

Delete and cancel

Commands that delete or cancel something, like paddle subscriptions cancel, ask you to confirm before they run. In a terminal, type y at the prompt.

When there's no prompt, like in a script or when an AI agent runs the CLI, pass the same ID again with --confirm:

paddle notification-settings delete ntfset_01j82d983j814ypzx7m1fw2jpz --confirm ntfset_01j82d983j814ypzx7m1fw2jpz