## Resources & HTTP commands

The Stripe CLI supports two ways to create, update, and list objects based on API resources: resource commands and HTTP commands.

**Resource commands** directly manage API resources and provide different arguments, flags, and functionality based on which API resource is used.

**HTTP commands** are convenient shorthand for HTTP requests to the Stripe API. These requests can operate on individual API objects or lists of objects.

## resources

Resource commands make API requests using the CLI for a given resource. The Stripe CLI has commands to interact with all types of Stripe API resources.

A complete list of available resources and examples are included in the
[API Reference Guide](https://docs.stripe.com/api.md). Select **Stripe CLI** from the language dropdown to see a complete example for each resource.

Use the `help` command on any resource to see what operations you can perform. For example, run `stripe customers --help` to see help for the [Customers](https://docs.stripe.com/api/customers.md) resource.

Use `stripe resources` to see a complete list of available resources.

> All commands support making live requests with the `--live` flag.

**Command:** `stripe {resource command}`

### Arguments

- `<operation>`
  Operation to perform on API object. Each type of API resource includes a set of operations that you can perform (such as `delete`, `list`, and `retrieve`).

### Flags

- `--param=value`
  Parameters to attach to the operation being performed.

- `-d, --data <value>`
  Additional data to send with an API request. Supports setting nested values (e.g `nested[param]=value`).

### Examples

**Listing supported operations**

```sh
stripe customers --help
```

```
Available Operations:
  create
  delete
  list
...
```

**Create a resource**

```sh
stripe customers create \
    --email=billing@example.com \
    --name="Jenny Rosen" \
    --description="My First Test Customer"
```

**Update a resource**

```sh
stripe customers update cus_9s6XKzkNRiz8i3 \
    -d "metadata[key]=value"
```

**Retrieve a resource**

```sh
stripe customers retrieve cus_9s6XKzkNRiz8i3
```

**Response**

```
{
  "id": "cus_9s6XKzkNRiz8i3",
  "object": "customer",
  "address": null,
  "balance": 0,
  "created": 1680893993,
  "currency": null,
  "default_source": null,
  "delinquent": false,
  "description": "My First Test Customer",
  "discount": null,
  "email": "billing@example.com",
  "invoice_prefix": "0759376C",
  "invoice_settings": {
    "custom_fields": null,
    "default_payment_method": null,
    "footer": null,
    "rendering_options": null
  },
  "livemode": false,
  "metadata": {},
  "name": "Jenny Rosen",
  "next_invoice_sequence": 1,
  "phone": null,
  "preferred_locales": [],
  "shipping": null,
  "tax_exempt": "none",
  "test_clock": null
}
```

## get

Make GET HTTP requests to retrieve an individual API object (or set of objects).

You can pipe the output of this command to other tools. For example, you could use [jq](https://stedolan.github.io/jq/) to extract information from JSON the API returns, and then use that information to trigger other API requests.

See the [API reference](https://docs.stripe.com/api.md) for a complete list of supported URL paths.

**Command:** `stripe get`

### Arguments

- `<id>`
  ID of the API object to retrieve.

- `<path>`
  URL path of the API object or set of objects to fetch.

### Flags

- `-c, --confirm`
  Skip the warning prompt and automatically confirm the command being entered.

- `--dark-style`
  Use a darker color scheme better suited for lighter command-line environments.

- `-d, --data <value>`
  Additional data to send with an API request. Supports setting nested values (e.g `nested[param]=value`).

- `-b, --ending-before <object_id>`
  Retrieve the previous page in the list. Pagination uses a cursor that depends on the ID of an object in the list.

- `-e, --expand <value>`
  Response attributes to expand inline (target nested values with `nested[param]=value`).

- `-i, --idempotency <key>`
  Set an idempotency key for the request, preventing the same request from replaying within 24 hours.

- `-l, --limit <number>`
  Number of objects to return, between 1 and 100 (default: 10).

- `--live`
  Make a live request (by default, runs in test mode).

- `-s, --show-headers`
  Show response HTTP headers.

- `-a, --starting-after <object_id>`
  Retrieve the next page in the list. Pagination uses a cursor that depends on the ID of an object in the list.

- `--stripe-account <account_id>`
  Specify the Stripe account to use for this request.

- `-v, --stripe-version <version>`
  Specify the Stripe API version to use for this request.

### Examples

**Get a specific charge by ID**

```sh
stripe get ch_1OKcnt2eZvKYlo2C99k9lfXl
```

**Response**

```
{
  "id": "ch_1OKcnt2eZvKYlo2C99k9lfXl",
  "object": "charge",
  "amount": 1000,
  "amount_captured": 1000,
  "amount_refunded": 0,
  "application": null,
  "application_fee": null,
  "application_fee_amount": null,
  "balance_transaction": "txn_1032Rp2eZvKYlo2CpErRBj09",
  "billing_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": null,
    "name": null,
    "phone": null
  },
  "calculated_statement_descriptor": "Stripe",
  "captured": true,
  "created": 1701937169,
  "currency": "usd",
  "customer": null,
  "description": "Created by docs.stripe.com/ demo",
  "disputed": false,
  "failure_balance_transaction": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {},
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "on_behalf_of": null,
  "outcome": {
    "network_status": "approved_by_network",
    "reason": null,
    "risk_level": "normal",
    "risk_score": 23,
    "seller_message": "Payment complete.",
    "type": "authorized"
  },
  "paid": true,
  "payment_intent": "pi_1Gt0RG2eZvKYlo2CtxkQK2rm",
  "payment_method": "pm_1OKcns2eZvKYlo2CKsdIIi44",
  "payment_method_details": {
    "card": {
      "amount_authorized": 1000,
      "brand": "visa",
      "checks": {
        "address_line1_check": null,
        "address_postal_code_check": null,
        "cvc_check": "pass"
      },
      "country": "US",
      "exp_month": 12,
      "exp_year": 2024,
      "extended_authorization": {
        "status": "disabled"
      },
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "funding": "credit",
      "incremental_authorization": {
        "status": "unavailable"
      },
      "installments": null,
      "last4": "4242",
      "mandate": null,
      "moto": null,
      "multicapture": {
        "status": "unavailable"
      },
      "network": "visa",
      "network_token": {
        "used": false
      },
      "overcapture": {
        "maximum_amount_capturable": 1000,
        "status": "unavailable"
      },
      "three_d_secure": null,
      "wallet": null
    },
    "type": "card"
  },
  "radar_options": {},
  "receipt_email": null,
  "receipt_number": "1684-0467",
  "receipt_url": "https://pay.stripe.com/receipts/payment/CAcaFwoVYWNjdF8xMDMyRDgyZVp2S1lsbzJDKP6nmbIGMga3cB9wS6A6LBZL8h0qdoMC7kO1KupX02DAl5VwFXa4PrlrciExsDqlMq4dJYzVswnEzUi4",
  "redaction": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/charges/ch_1OKcnt2eZvKYlo2C99k9lfXl/refunds"
  },
  "review": null,
  "shipping": null,
  "source_transfer": null,
  "statement_descriptor": null,
  "statement_descriptor_suffix": null,
  "status": "succeeded",
  "transfer_data": null,
  "transfer_group": null
}
```

**List the most recent 50 charges**

```sh
stripe get /v1/charges --limit 50
```

**Cancel past due subscriptions**

```sh
stripe get /v1/subscriptions -d status=past_due \
    | jq ".data[].id" \
    | xargs -I % -p stripe delete /subscriptions/%'
```

## post

Make POST HTTP requests to the Stripe API. The `post` command supports API features like idempotency keys and expandable objects.

See the [API reference](https://docs.stripe.com/api.md) for a complete list of supported URL paths.

**Command:** `stripe post`

### Arguments

- `<path>`
  URL path of the API object to either create or update.

### Flags

- `-c, --confirm`
  Skip the warning prompt and automatically confirm the command being entered.

- `--dark-style`
  Use a darker color scheme better suited for lighter command-line environments.

- `-d, --data <value>`
  Additional data to send with an API request. Supports setting nested values (e.g `nested[param]=value`).

- `-e, --expand <value>`
  Response attributes to expand inline (target nested values with `nested[param]=value`).

- `-i, --idempotency <key>`
  Set an idempotency key for the request, preventing the same request from replaying within 24 hours.

- `--live`
  Make a live request (by default, runs in test mode).

- `-s, --show-headers`
  Show response HTTP headers.

- `--stripe-account <account_id>`
  Specify the Stripe account to use for this request.

- `-v, --stripe-version <version>`
  Specify the Stripe API version to use for this request.

### Examples

**Create a payment intent**

```sh
stripe post /v1/payment_intents \
    -d amount=2000 \
    -d currency=usd \
    -d "payment_method_types[]=card"
```

**Response**

```
{
  "id": "pi_1Gt0Ix2eZvKYlo2CwZBLZZfa",
  "object": "payment_intent",
  "amount": 2000,
  "amount_capturable": 0,
  "amount_details": {
    "tip": {}
  },
  "amount_received": 0,
  "application": null,
  "application_fee_amount": null,
  "automatic_payment_methods": null,
  "canceled_at": null,
  "cancellation_reason": null,
  "capture_method": "automatic",
  "client_secret": "pi_1Gt0Ix2eZvKYlo2CwZBLZZfa_secret_3LwqYVg0STglik0tqpkBQodvA",
  "confirmation_method": "automatic",
  "created": 1591919971,
  "currency": "usd",
  "customer": null,
  "description": "Created by docs.stripe.com/ demo",
  "invoice": null,
  "last_payment_error": null,
  "latest_charge": null,
  "livemode": false,
  "metadata": {},
  "next_action": null,
  "on_behalf_of": null,
  "payment_method": null,
  "payment_method_configuration_details": null,
  "payment_method_options": {
    "card": {
      "installments": null,
      "mandate_options": null,
      "network": null,
      "request_three_d_secure": "automatic"
    }
  },
  "payment_method_types": [
    "card"
  ],
  "processing": null,
  "receipt_email": null,
  "redaction": null,
  "review": null,
  "setup_future_usage": null,
  "shipping": null,
  "statement_descriptor": null,
  "statement_descriptor_suffix": null,
  "status": "requires_payment_method",
  "transfer_data": null,
  "transfer_group": null
}
```

## delete

Make DELETE HTTP requests to the Stripe API.

See the [API reference](https://docs.stripe.com/api.md) for a complete list of supported URL paths.

**Command:** `stripe delete`

### Arguments

- `<path>`
  URL path of the API object to delete.

### Flags

- `-c, --confirm`
  Skip the warning prompt and automatically confirm the command being entered.

- `--dark-style`
  Use a darker color scheme better suited for lighter command-line environments.

- `-d, --data <value>`
  Additional data to send with an API request. Supports setting nested values (e.g `nested[param]=value`).

- `-e, --expand <value>`
  Response attributes to expand inline (target nested values with `nested[param]=value`).

- `-i, --idempotency <key>`
  Set an idempotency key for the request, preventing the same request from replaying within 24 hours.

- `--live`
  Make a live request (by default, runs in test mode).

- `-s, --show-headers`
  Show response HTTP headers.

- `--stripe-account <account_id>`
  Specify the Stripe account to use for this request.

- `-v, --stripe-version <version>`
  Specify the Stripe API version to use for this request.

### Examples

**Delete a customer**

```sh
stripe delete /v1/customers/cus_9s6XKzkNRiz8i3
```

```
Are you sure you want to perform the command: DELETE?
Enter 'yes' to confirm:
```

**Response**

```
{
  "id": "cus_9s6XKzkNRiz8i3",
  "object": "customer",
  "deleted": true
}
```

## fixtures

Use a JSON file to issue a series of API requests. This can be useful when generating sample data, executing specific flows, or testing API behavior.

The structure of the JSON file outlines the set of requests to perform, known as _fixture requests_. When you specify a request's `name`, the CLI stores the response so you can reference the output in subsequent requests. The `path` property specifies the Stripe URL route for the API resource used in the request (e.g. `/v1/customers`).

For example, to reference the response for the request named `json_path`:

- Accessing attributes in responses: `${name:json_path}`
- Accessing environment variables: `${.env:VARIABLE_NAME|<optional default value>}`

Fixture queries must start with `${` and end with `}` and can be included in fixture requests. `name` is the name of the request assigned as part of the fixture (`fixtures[].name`) and `json_path` is a dot-path to the specific variable requested. For example:

- Use `${cus_jenny_rosen:id}` to access a top-level attribute.
- Use `${cus_jenny_rosen:billing_details.address.country}` to access nested data.
- Use `{cus_jenny_rosen:subscriptions.data.#.id}` to access data within a list at index #.
- Use `${.env:PHONE}` to access environment variables (supports `.env` files).

Environment variables can specify default values with the pipe character (`|`). For example:

- `${.env:EMAIL|jane@stripe.com}`
- `${.env:CUSTOMER|cus_1234}`

**Command:** `stripe fixtures`

### Arguments

- `<filepath>`
  Use the JSON file at the given path that includes fixture requests to run.

### Fields

- `_meta`
  Metadata used by CLI during execution.
    - `template_version`
      Version of the template that is running (enables us to support potentially backwards-incompatible changes).

- `fixtures`
  List of requests to execute.
    - `name`
      Name of the request, used to later reference the response
    - `expected_error_type`
      Indicates that this request is expected to return an error of the specified [error type](https://docs.stripe.com/error-codes). When set, the fixture continues executing subsequent requests even if this request returns an error matching the specified type. If the error type does not match, the fixture fails. Common values include `card_error` and `invalid_request_error`.
    - `path`
      Stripe URL path for this request. URL paths can include variables from other fixture queries.
    - `method`
      HTTP method for the request: GET, POST, or DELETE.
    - `params`
      Parameters to include with the request. Accepted values include strings, integers, booleans, nested JSON structures, and fixture queries.

### Flags

- `--override [param]:[path1].[path2]=[value]`
  Override parameters in the fixture. Example: --override plan:product.name=overrideName

- `--add [param]:[path1].[path2]=[value]`
  Add parameters in the fixture. Example: --add customer:name=TestUser

- `--remove [param]:[path1].[path2]`
  Remove parameters from the fixture. Example: --remove customer:description

- `--skip [param]`
  Skip specific steps in the fixture. Example: --skip cus_jenny_rosen

### Examples

**Sample fixture**

```sh
{
  "_meta": {
    "template_version": 0
  },
  "fixtures": [
    {
      "name": "cus_jenny_rosen",
      "path": "/v1/customers",
      "method": "post",
      "params": {
        "name": "Jenny Rosen"
      }
    },
    {
      "name": "pi_jenny_rosen",
      "path": "/v1/payment_intents",
      "method": "post",
      "params": {
        "customer": "${cus_jenny_rosen:id}",
        "amount": 2000,
        "currency": "usd",
        "payment_method": "pm_card_visa",
        "capture_method": "manual",
        "return_url": "https://www.example.com",
        "confirm": true
      }
    },
    {
      "name": "pi_jenny_rosen_capture",
      "path": "/v1/payment_intents/${pi_jenny_rosen:id}/capture",
      "method": "post"
    }
  ]
}
```

**Run fixtures**

```sh
stripe fixtures ./fixtures.json
```

```
Setting up fixture for: cus_jenny_rosen
Setting up fixture for: pi_jenny_rosen
Setting up fixture for: pi_jenny_rosen_capture
```