## 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
```