Debugging your Stripe Invoicing integration with Workbench

Stripe invoicing enables you to create and manage invoices for one-time or recurring payments. Whether caused by infrastructure issues or coding bugs, integration failures do sometimes happen, which can prevent invoices from being paid in a timely manner.

Using the new Stripe Workbench tool, this post shows you how to debug and fix errors in your invoice integration.

Stripe Workbench

Workbench is a context-aware tool that allows you to build and debug your Stripe integrations from anywhere in the Dashboard. In response to feedback from Stripe developers, this new feature centralizes previously disparate developer tooling into one central and constantly accessible location. Among other things, you can use Workbench to inspect API objects and run requests on them using the built-in Shell.

To get started, navigate to the Workbench page in your Dashboard and turn the feature on.

Workbench is organized by tabs, each showing you a different aspect of your integration. A natural starting spot to explore is the Overview tab, where you can see:

• API keys and versions.
• activity trends in your integration.
• recent errors.
• useful references to help you get unblocked and submit feedback.

The Invoice Object

Invoices are sent by merchants to customers for payment, in exchange for goods and services. In its simplest form, an invoice has a number of key parameters including a Customer and an associated Payment Method.

A common developer error with Invoice integrations is not properly sending all the required parameters as part of your API call. The following example shows how Workbench makes it easy to debug such errors.

Debugging errors in your integration

In Workbench, the recent errors section of the Overview tab gives an early indication of potential problems with your integration. To dig deeper, you can look at the Errors tab, which gives a holistic view of errors over the last week.

The leftmost pane of the Errors tab contains a list of all the errors. You can choose each individual error for more details, including the actual API request that caused it.

This example shows that there was a parameter_missing error. The details show that the Invoice create call was missing a Customer object. As previously mentioned, this prevents the Invoice from being created since there’s no customer to charge

Fixing the error

Now that you’ve located the error, navigate to the Shell tab for options to fix it. The Shell allows you to run Stripe CLI commands from within the dashboard. This saves you having to run the CLI in a separate terminal window.

To address the error above, you need a Customer object. You can get that by running the Stripe customers list command in the Shell prompt at the bottom of the screen. In the response, expand the list of Customers and copy one of the IDs by clicking on the clipboard icon next to it.

Still within the Shell tab, the API Explorer offers a surface for understanding endpoints in the Stripe API and their associated parameters. This helps you learn about the different objects in the API and what actions can be performed on them. It saves you from having to switch back and forth between a CLI window and the Stripe docs. Use the API explorer to build out whatever command you’re looking to test and then run it.

To remediate the invoice creation bug, follow these steps:

1. Find the Invoices object and its corresponding Create endpoint in the dropdown list.

2. Paste the Customer ID that you previously copied in the corresponding customer parameter field

3. The Shell prompt auto-populates as you modify fields in the API explorer. You can use this to learn how to construct CLI commands.

4. Another feature in the API explorer is the Print SDK request option at the bottom, which allows you to generate code in the SDK language of your choosing. You can then reuse this code in your integration, saving you time and potential errors.

5. Run the command by clicking on the Run button in the lower right corner. Your invoice is now created. Check the response in the Shell and make sure there are no errors.

Inspecting the fix

To take a deeper look at the resulting invoice, copy its ID from the Shell and switch to the Inspector tab. This pane provides a way of drilling into any Stripe object down to its JSON representation. The data map feature shows you a hierarchical view of the object, so you can see all the dependencies it has. In this case, you see the newly created Invoice and its attached Customer object.

The Inspector also provides a Logs tab where you can see details of the API calls associated with the invoice.

The Events tab in the Inspector shows the various events that get fired as invoices move through their lifecycle, from creation to payment.

Going a step further

After fixing the invoice creation process, it’s worth checking that it can actually be paid. To check, run the Pay command on the invoice using the API Explorer once again.

Looking at the Events list again, you can see that new ones have been added. Notably, the invoice payment was successful but for $0. Trial periods are a common use case for zero-dollar invoices.

As previously mentioned, the example in this article looks at the base case. In order to actually process payments of non-zero monetary value, invoices require Invoice Items as well, to specify which products or services were sold.

Follow these steps to create Invoice Items using Workbench:

1. Start by creating a Product using the API explorer, to represent the goods or services being sold. Make sure to specify a name and price.

To specify a price, use the default_price_data hash and add a unit_amount.

2. After running the command, copy the Product ID and Price ID (default_price) from the response.

3. Next, create an Invoice Item with these parameters:

   1. the Price ID from the previous step
   2. a Customer ID: you can re-use your previous customer or create a new one.
   3. A new Invoice ID: your previous invoice has been paid, so it can no longer be used.

Run the command in the API explorer

4. Using the Inspector, you can verify that the Invoice has been updated with an item.

Wrapping Up

Workbench offers a powerful new suite of tools for identifying errors in your invoice integration, understanding their causes and fixing them - all without ever exiting your Stripe dashboard.

This post highlights how you can leverage Workbench to not only debug your invoicing integration, but also inspect all its associated objects. The parameter_missing example can be extended to more complex use cases, but the approach stays the same.

For more details on Invoices, check out how you can use Workbench to analyze their lifecycle.