stripe-cli: `trigger` with customizable data

Description of the desired feature

The trigger command can be used to create sample events of various types. Many users would like to be customize the events.

For example, one could trigger a charge.captured event for an existing charge object:

$ stripe trigger charge.captured --charge ch_123

Or one could trigger a customer.subscription.created for a specific customer, with custom metadata going into the subscription object:

$ stripe trigger customer.subscription.created --customer cus_123 -d metadata[key]=value

At the moment, none of the above is possible.

Current implementation of the trigger command

Under the hood, the trigger command works by sending a series of API requests. E.g. to trigger a charge.captured event, the CLI will send two requests to Stripe:

1. A charge creation request with captured=false, to create a new uncaptured charge object
2. A charge capture request for the newly created object

These series of API requests are defined using as JSON files (“fixtures” files) that are embedded in the executable, e.g. https://github.com/stripe/stripe-cli/blob/master/triggers/charge.captured.json.

Difficulties in providing a generic interface to customize data

Due to the large number of possible event types and scenarios, it’s not feasible to customize the behavior of the CLI per event type – that would be near impossible to maintain in the long term. We want to keep the interface of the trigger command generic. However, because each “trigger” is defined as an arbitrary sequence of API requests, it is difficult to provide a generic CLI interface to customize the data that goes into each request.

For instance, for the case of capturing an existing charge object, the trigger command would have to omit the first request (the charge creation request) when the --charge flag is provided.

For the case of providing custom metadata when creating a subscription, it’s even more complicated: under the hood, the trigger command needs to create a new customer and a new plan before it can create the new subscription. If custom metadata is provided on the command line, it’s not clear which resource (the plan, the customer or the subscription) should receive the custom metadata.

Creating your own fixtures files

It’s not a perfect solution, but you can create your own fixtures files (i.e. sequences of API requests) with your own custom data and have the CLI play them with the stripe fixtures command.

E.g. in order to capture an existing charge object, you could create a my_fixture.json file with the following contents:

{
  "_meta": {
    "template_version": 0
  },
  "fixtures": [
    {
      "name": "capture",
      "path": "/v1/charges/ch_123/capture",
      "method": "post"
    }
  ]
}

then play it with stripe fixtures my_fixture.json. This would send a single request to capture the ch_123 charge.

You can take a look at the various existing fixtures in https://github.com/stripe/stripe-cli/tree/master/triggers and use them as templates to write your own files.

In the future, we will clearly document the syntax of the fixtures files.

Feedback

We realize having to write your own fixtures files is more cumbersome than a single command line invocation, and are looking into ways of improving the experience here. Please feel free to reply with this issue with feedback or suggestions!