Mailchimp Developer LogoMailchimp Developer Wordmark

Fundamentals

The basics

Mailchimp Open Commerce is an API-first, modular commerce stack. The API implements all features in GraphQL and is fully extensible via plugins.

Open Commerce is open-source-licensed, freely available software. You can explore the platform’s repos on GitHub, or follow the Quick Start guide to install the development platform on your computer. If you’re interested in contributing to Open Commerce, be sure to read and follow the code of conduct and check out the community resources.

Using Open Commerce

Whether you’re a business owner running a shop or a developer setting up a custom implementation, it’s easy to get a shop up and running with the Open Commerce development platform and build from there.

Every shop is built around a catalog of products. You can set up your products in the admin dashboard and then organize them with tags to help shoppers navigate your catalog. Once shoppers have found what they want and make a purchase, you’ll fulfill their orders by accepting payments and delivering their items.

Developers can customize any part of the administrator or shopper experience by writing plugins. Because Open Commerce is fully modular, you’ll often want to share code between plugins so features are available across the entire platform. If you’ve created a new plugin or modified an existing one and you want to share it with other developers, you can contribute to the Open Commerce community. When committing to existing Open Commerce repos, you should follow the testing requirements

Open Commerce vs Reaction Commerce

Open Commerce was formerly known as Reaction Commerce. You may see references to Reaction throughout the guides and docs, especially in code—all Open Commerce repos are under the reactioncommerce GitHub organization.

As we continue the renaming process, we’ll announce any future breaking changes in the release notes.

Development platform

The Open Commerce development platform is the simplest way to set up the API and its supporting services on your local machine. The development platform is containerized and uses public Docker images by default, though you can also choose to run the platform in development mode, which uses local images that can be updated on the fly as you make edits to a running plugin.

The development platform has several make scripts that automatically pull the latest version of Open Commerce and start all of the required services using Docker Compose. The development platform runs on localhost; see the Quick Start guide for a list of ports where you can access its various services. For details on specific make commands for controlling and customizing the development platform, see the development platform project documentation on GitHub.

Plugins

All of Open Commerce’s features, including the API core, are provided by first-party plugins—the main project is a shell that that imports all of the required NPM packages. This structure gives you complete control over what plugins and features are active in your installation. For more information on customizing these plugins or creating your own, check out the Build an API Plugin guide.

A wide range of first-party plugins covers all the basic platform features, including handling backend services, shop configuration, and the shopper experience. You can view a list of the plugins active in your instance in the admin dashboard under Settings > System Information. The plugins included with the development platform are:

PluginDescription
api-plugin-accountsManages internal accounts for shop operators and shoppers.
api-plugin-address-validationValidates shopper addresses during checkout.
api-plugin-address-validation-testA template for creating a new address validation plugin.
api-plugin-authenticationConnects the Identity service to the Open Commerce API.
api-plugin-authorization-simpleChecks account permissions to allow or deny actions.
api-plugin-cartsHandles shopping cart objects.
api-plugin-catalogsHandles product catalogs.
api-plugin-discountsHandles discounting products.
api-plugin-discounts-codesEnables discount codes that shoppers can enter at checkout.
api-plugin-emailSends transactional emails.
api-plugin-email-smtpManages the SMTP connection for outgoing transactional emails.
api-plugin-email-templatesProvides transactional email templates that shop operators can customize.
api-plugin-filesManages file uploads for a shop.
api-plugin-i18nHandles internationalization options for a shop.
api-plugin-inventoryTracks inventory counts for product variants.
api-plugin-inventory-simpleDetermines product availability status based on inventory counts.
api-plugin-job-queueManages job queuing and execution.
api-plugin-navigationAllows for the creation of hierarchical navigation in a shop.
api-plugin-notificationsSends messages about order statuses.
api-plugin-ordersHandles orders, including fulfillment groups.
api-plugin-paymentsManages all payment methods for a shop.
api-plugin-payments-exampleA template for creating a new payment handler.
api-plugin-payments-stripeProcesses payments with Stripe.
api-plugin-pricing-simpleEnables setting prices on product variants.
api-plugin-productsCreates products and manages their information.
api-plugin-settingsManages shop settings like those available in the admin dashboard.
api-plugin-shipmentsHandles shipment types, including allowing or denying shipment methods for products or orders that meet certain criteria.
api-plugin-shipments-flat-rateHandles shipment types that always cost the same amount.
api-plugin-shopsAllows creation and management of shops within an Open Commerce instance.
api-plugin-simple-schemaImplements SimpleSchema to validate data for MongoDB documents.
api-plugin-sitemap-generatorCreates sitemap files for search engines at a specified time interval.
api-plugin-surchargesAllows applying surcharges to a cart.
api-plugin-system-informationProvides information about the running instance of Open Commerce, including registered plugins.
api-plugin-tagsHandles tag creation and organization.
api-plugin-taxesManages tax rates based on location, product type, and more.
api-plugin-taxes-flat-rateAllows for setting a single tax rate.
api-plugin-translationsSupplies translations of terms used in the API in over 20 languages.

Environment variables

Much of the platform-wide configuration of Open Commerce is set via environment variables—either to pass information from one service to another or simply to customize the platform to meet your needs.

You can set variables in the .env file within each plugin, which is used by Docker Compose when starting the system and loading plugins. Each Open Commerce repo contains a .env.example file that lists the environment variables and default values for that project. You can run the bin/setup script within the project to automatically copy the contents of .env.example to .env (although it will not overwrite existing values). Your .env files will contain personalized and potentially sensitive information, so you should never commit them to a public GitHub repo.

Note: When running the development platform, its make scripts automatically set up the required .env files for you.

In some cases, projects may look for additional environment variables that are not listed in .env.example because they are optional and have default values set in the code. You can find these optional variables by searching for cleanEnv within a Node project.

Community

Open Commerce has a global team of contributors to its projects on GitHub. New contributors are always welcome, and they should read and abide by the code of conduct.

If you have questions about implementing Open Commerce, customizing code for your own purposes, or contributing to a project, check out the developer forum and Gitter chat. For bug reports and feature requests, you can create a new issue directly in the appropriate repo.

For more information on getting your code ready to commit, check out the ESLint configuration project and the Testing Requirements doc.

Improve our docs onGitHub