Documentation

Projects

Projects are the central data container for your commerce solution.

  • After completing this page, you should be able to:

    • Describe what a Project in Composable Commerce is.
    • Create your own Project.

    • A Project encompasses a complete set of isolated data and the commerce resources necessary to build your Composable Commerce solution. You can think of each Project as a secure container for Customers, Products, Carts, Orders, Discounts, and API Clients.

    Why do you need a data container? Composable Commerce is a multi-tenant, commerce Software as a Service (SaaS) product. A Project provides absolute data security within the multi-tenant environment. API Clients are created within each Project with a set of permission scopes, which ensures an absolute boundary between each Projects data. Learn more about Teams and Permissions here.

    Projects are very flexible and you may create more than one Project for various reasons based on your individual business needs. You may have individual Projects for each environment type: for example, trial, staging, and production. Or, a single Project can also be utilized to power one or many commerce websites, mobile applications or any other commerce solution. Composable Commerce does not force you to choose any specific topology.

    Keep in mind that a Project can belong to one Organization only, but an Organization can have many Projects.

    A company may use multiple projects to develop their commerce solution.

    In this image above, we can notice:

    • One Organization has been created to represent one example company.
    • This company has mutliple brands in its portfolio, and a Project has been set up for each brand. One Project powers the ecommerce site and mobile app of brand 1, while the other Project powers the Point of Sale system for brand 2.
    • Within the Organization, several distinct Teams have been created to define the permissions for working with each Project.

    This is a simplified example to show how Organizations, Teams, and Projects can be configured to solve your particular business needs. How would you configure these to suit your own business requirements?

    How can you create a Project?

    You can only create Projects in the Merchant Center. To create a Project:

    When you create a Project, you must define a Project key. This is a unique identifier that is used to identify the Project in every API call that you make. This, along with the scopes defined for your API Client will control programmatic access to the data contained in your Project.

    For your first trial Project, create the Project key however you wish. When you dive deeper into Composable Commerce, we recommend using a naming convention for convenience and consistency. Creating a naming convention for your Project keys in Composable Commerce is essential for maintaining consistency, improving readability, and making it easier to manage your Projects. Here's a recommended naming convention:

    Format: {CompanyShortName}_{Purpose}_{Country}_{Environment}

    Where:

    • {CompanyShortName}: an abbreviated form of your company or organization name. This helps to distinguish your Projects if you're managing multiple brands or organizations.
    • {Purpose}: the purpose of the Project. This could be the name of the particular website, application, or physical store that the Project is associated with.
    • {Country}: a three-letter country code (ISO 3166) representing the country the Project is associated with. In cases where country codes are not a good fit, this value can be replaced with another relevant descriptor (for example, region codes) that better suit the business case.
    • {Environment}: the environment of the Project. This can be dev for development, test for testing, staging for staging, or prod for production.

    All elements should be in lowercase and separated by underscores _. Avoid using spaces, special characters, or uppercase letters to ensure compatibility across various systems and programming languages.

    Examples:

    • mycompany_webshop_aus_prod
    • mycompany_mobileapp_aus_dev
    • mycompany_webshop_nzl_staging
    • mycompany_webshop_nzl_test

    This convention helps you to identify the purpose and environment of a Project just by looking at the Project key. It's important to note that once a Project key is set, it cannot be changed, so it's crucial to decide on a meaningful and scalable naming convention from the start.

    Please remember that the above is a recommendation and may not suit every use case. Always consider your specific business requirements, the size and complexity of your Projects, and your team's preferences when designing a naming convention.

    Once your Project is created, you should configure your Project settings.

    When you have created your Project, it will be in trial status for 60 days. You can see how much time is remaining in your trial in the Merchant Center in the Manage Projects screen. You can also see if your Project is considered to be in production or not.

    The In Production flag can be found on the Manage Projects page.

    If a Project is not activated at the end of the 60-day trial, it is marked with a Trial ended flag. The Project data would be available in the Merchant Center, but you cannot obtain API tokens for the Project or make API calls.

    The In production flag lets our Support team know that a Project is live and accepting traffic from customers. By default, this flag is deactivated for all Projects that are created.

    To activate a trial Project or to mark a Project as in production, contact Support.

    Test your knowledge