Send your first Stripe API request

This guide walks you through a simple interaction with the Stripe API—creating a customer. For a better understanding of Stripe API objects and how they fit together, take a tour of the API or visit the API reference. If you’re ready to start accepting payments, see our quickstart.

You can begin exploring Stripe APIs using the Stripe Shell. The Stripe Shell allows you to execute Stripe CLI commands directly within the Stripe docs site. As it operates in a sandbox environment only, you don’t have to worry about initiating any real money-moving transactions.

1. To create a customer using the Stripe Shell, enter the following command:

   Command Line

   stripe customers create --email=jane.smith@email.com --name="Jane Smith" --description="My First Stripe Customer"

   If everything worked, the command line displays the following response:

   {
     "id": 
   "cus_LfctGLAICpokzr",
     "object": 
   "customer",

   See all 31 lines

2. (Optional) Run the same command by passing in your API secret key in a sandbox:

   Command Line

   stripe customers create --email=jane.smith@email.com --name="Jane Smith" --description="My First Stripe Customer" --api-key sk_test_BQokikJOvBiI2HlWgH4olfQ2

   If everything worked, the command line displays the following response:

   {
     "id": 
   "cus_LfdZgLFhah76qf",
     "object": 
   "customer",

   See all 32 lines

Whenever you make a call to Stripe APIs, Stripe creates and stores API and Events objects for your Stripe user account. The API key you specify for the request determines whether the objects are stored in a sandbox environment or in live mode. For example, the last request used your API secret key, so Stripe stored the objects in a sandbox.

• To view the API request log:

  • Open the Logs page.
  • Click 200 OK POST /v1 customers.

• To view the Event log:

  • Open the Events page.
  • Click jane.smith@email.com is a new customer.

Stripe supports different types of API keys for different use cases. You’re responsible for managing these keys safely. In particular, treat secret keys and restricted API keys (RAKs) as sensitive and don’t expose them outside your server environment. To keep your business safe, read and understand best practices for managing secret API keys.

Develop and test and your application with sandbox keys, not live-mode keys, to make sure you don’t accidentally modify your live customers or charges.

Find your API keys in the Stripe dashboard. If you can’t view your API keys but need to manage keys for your app, ask the owner of your Stripe account to add you to their team with the proper permissions.

If you’re logged in to Stripe, our documentation includes your test API keys in some places to illustrate API usage. Only you can see these values. If you’re not logged in, our code examples include randomly generated API keys.