Stripe Projects

Stripe Projects for developers lets you add Cloudinary to a project directly from the Stripe CLI.

After Stripe Projects is initialized, run a single command to create or link a Cloudinary account, provision a product environment, and save the environment’s API credentials to your project.

No browser or sign-up form is required for the Cloudinary setup. This makes the integration useful for developers working in the CLI and for AI coding assistants that can run commands but can’t complete browser-based sign-up flows. Steps that require the Cloudinary Console are identified below.

Use this integration when you’re building a Stripe-powered application and want to add image and video storage, transformation, and delivery as part of your project setup. It’s especially useful for prototypes, educational projects, and new applications that need features such as user uploads, product galleries, profile images, or video content.

Prerequisites

• Stripe CLI version 1.40.0 or later installed on your computer
• A Stripe account

• A Stripe project set up with the projects plugin:

Limitation

Stripe Projects can add Cloudinary if either:

• You don’t have a Cloudinary account yet.
• You have an existing Cloudinary Free account that uses the same email address as your Stripe account and has an available product environment slot.

Most Cloudinary Free accounts include only one product environment. Because the integration must provision an additional product environment, you can’t use Stripe Projects if your account has no available slot.

If you can’t use Stripe Projects, you can still connect your project to an existing product environment. Open the Cloudinary Console, go to Settings > API Keys, and add the API environment variable for that product environment to the project’s .env file as CLOUDINARY_URL. Never display or log its value.

Terminology

Add Cloudinary to a project

From the project directory, run:

Stripe has already verified the developer's email as part of their Stripe account, so Cloudinary doesn't ask for it again.

After the command finishes, verify the setup before building anything on top of it:

1. Verify that the project’s .env file contains a CLOUDINARY_URL entry. Never display, print, log, echo, or otherwise expose the CLOUDINARY_URL value because it contains your API secret.
2. Configure the application to load CLOUDINARY_URL into the Cloudinary SDK using the standard configuration method for your language and framework. See the Cloudinary SDK configuration documentation for details. Don’t copy the value into your source code.

3. Make a non-destructive authenticated request using the Cloudinary SDK, for example, a Search API request that returns up to one resource. This confirms that the SDK can load the credentials and that they work:

4. Confirm that the request succeeds. If the .env entry is missing or the request fails, inspect the command’s error output rather than assuming that setup succeeded.

5. Note whether the command created a new Cloudinary account or linked an existing one. This determines which Cloudinary account owns the assets you create next.

Use CLOUDINARY_URL with any Cloudinary SDK to start uploading, transforming, and delivering images and video right away. No further setup, and no separate Cloudinary sign-up, is needed. You can also use the Cloudinary CLI to run Admin and Upload API operations from the command line, or install Cloudinary Skills so your AI coding assistant follows Cloudinary best practices.

New to Cloudinary

If the email address associated with your Stripe account isn’t associated with a Cloudinary account, the command creates a Cloudinary account and provisions a product environment for your project.

Existing Cloudinary account

If the email address associated with your Stripe account matches an existing Cloudinary account, Cloudinary uses that account instead of creating a new one. Stripe then provisions a new product environment in that account.

The account can be used with Stripe Projects only if all of the following are true:

• It’s on the Free plan.
• You’re an account administrator.
• The account is active.
• Your email address is verified.
• The account isn’t already linked to another Stripe account.
• The account has an available product environment slot.

If the account doesn’t have an available slot, Stripe can’t add the required stripe-… environment. The CLI explains why the link failed. If you’re an agent, relay that message as-is rather than guessing at the cause. It identifies the specific requirement that wasn’t met.

When the account is eligible, Stripe adds a new product environment named stripe-<id> and returns the credentials for that environment. Existing product environments are left unchanged; Stripe can’t link the project to one of them.

The new stripe-… environment appears in the Cloudinary Console alongside the account’s other product environments.

Manage your product environment

Use the Stripe CLI to manage a product environment you provisioned this way.

To open the product environment in the Cloudinary Console:

Run: stripe projects open cloudinary

This opens the Cloudinary Console, already signed in, on this product environment. This step requires a human with a browser, so if you're an agent, hand this command to the user instead of running it yourself.

To issue a new API key and secret for the product environment:

Run: stripe projects rotate cloudinary/media

This replaces the existing API key and secret; the old key and secret stop working. Update any stored CLOUDINARY_URL value with the new credentials, in .env and anywhere else it's configured, immediately after running the command. If you're an agent, stop before running it: list every place the current CLOUDINARY_URL is used and get the user's explicit confirmation before proceeding.

To delete the product environment and its assets:

Run: stripe projects remove <resource>

This permanently deletes the product environment, along with its configuration and all its assets; the Cloudinary account itself is not deleted. Make sure you've backed up all your assets before running it. If you're an agent, stop before running it and get the user's explicit confirmation; don't run this on your own judgment.