Vercel Integration

Why Vercel?

Taking full advantage of OrderCloud's composability means integrating with other great software - like Vercel. Vercel is a hosting platform focused on frontend frameworks and static sites associated with the popular NextJS framework. OrderCloud and Vercel complement each other well.

• Ordercloud and Vercel both enable rapid custom frontend development (mainly in javascript) by abstracting out complex concerns (commerce and hosting, respectively).

• Vercel's built-in serverless functions offer a familiar javascript environment to build the secure middleware integrations most OrderCloud solutions require.

• Vercel's NextJS static site generation is well-suited to commerce use-cases, unlocking fast page loads via CDN (built-in to Vercel) and great SEO for product pages.

• Well aware of that, Vercel maintains an open source example commerce storefront in NextJS that connects to multiple commerce engines like OrderCloud.

Get a live storefront in 5 minutes

1. If you haven't already, sign up for OrderCloud and sign up for Vercel! Both are free and quick. You will also need a github, gitlab or bitbucket account.

2. Visit the vercel commerce github and fork it to your source control account.

3. Create a new vercel project and connect it to the forked repository. Then go to Integrations -> Browse Marketplace -> OrderCloud, or this link, and click "Add Integration".

4. Follow the prompts to authenticate to OrderCloud. Then connect your new vercel project to the option "Seed a new marketplace".

5. Once seeding is complete, you will be returned to Vercel. Deploy or Redeploy the project and you have a live storefront with cart, checkout, and example products.

How does the Integration work?

The OrderCloud integration is part of the Vercel integration marketplace. It can link your vercel projects each to one OrderCloud marketplace. This link consists of 2 API Client resources created in Ordercloud and 6 Environment Variable resources created in Vercel.

OrderCloud API Clients

{
    ID: <generated>, 
    AppName: Vercel-Middleware-Connector,
    Active: true,
    AllowSeller: true,
    ClientSecret: <generated> 
    AccessTokenDuration: 600,
    RefreshTokenDuration: 43200
}

{
    ID: <generated>,
    AppName: Vercel-Storefront-Connector,
    Active: true,
    AllowAnyBuyer: true,
    IsAnonBuyer: true,
    AccessTokenDuration: 600,
    RefreshTokenDuration: 43200
}

Why two API clients to connect to OrderCloud? The OrderCloud API offers extreme flexibility in commerce use cases. The trade-off is that custom solutions must bring their own definitions of the various user roles and permissions they want to support. OrderCloud provides tools for controlling which users can take what API actions and which users can authenticate through which API clients. However, making those configuration choices and then securely connecting your custom code are a complexity that falls on the solution implementor. With this Vercel integration, you get a pre-coded storefront and a pre-configured data template. We've made the user roles and security decisions for you by choosing a very common pattern.

The Vercel-Storefront-Connector client is for buyer users. It is used to authenticate requests to OrderCloud that render the storefront like the Product List, Product Details, Cart, Checkout, etc. It is given limited API permissions - for example, you can't use it to change product features or read orders across users. These would be inappropriate things for a buyer to do. Because its permissions are limited, it is safe to expose the details to a client browser. Vercel-Storefront-Connector is the connection used to make the vast majority of requests to OrderCloud. The Vercel-Middleware-Connector client, on the other hand, is given full API access and is used sparingly. It can read or modify any piece of data in the OrderCloud marketplace. Accordingly, it also requires a Client Secret which should never be public. This connection should only be used inside serverless functions which do pre-canned actions after appropriate security checks (this is why its referred to as "middleware"). As an example, the vercel commerce app must use this connection to set Payment.Accepted to true after the user's credit card details are considered captured. To summarize, two API clients are needed because they provide different security levels.

Vercel Environment Variables

ORDERCLOUD_MARKETPLACE_ID
ORDERCLOUD_MARKETPLACE_NAME
ORDERCLOUD_BUYER_CLIENT_ID
ORDERCLOUD_MIDDLEWARE_CLIENT_ID
ORDERCLOUD_MIDDLEWARE_CLIENT_SECRET
COMMERCE_PROVIDER ("@vercel/commerce-ordercloud")

If you select the "Seed a new marketplace" option of the integration, a new marketplace will be created and seeded with this data template. Since this template already contains API Clients with names Vercel-Middleware-Connector and Vercel-Storefront-Connector, they will not be overwritten and everything will "just work". However, if you choose to connect to an existing OrderCloud marketplace, you will have to make sure these newly created API Clients are connected to organizations and default users you desire.

Similarly, if your project code is forked from Vercel Commerce, the environment variables above will be expected. However, if you connect other code it is your responsibility to consume those variables appropriately. ORDERCLOUD_MIDDLEWARE_CLIENT_SECRET especially should not be exposed to the front end.

The integration "just works" when the Vercel Commerce code and matching seed template are used. However, it can be used to connect a custom storefront with a matching custom OrderCloud configuration.

Was this page helpful? Give it a bravo!

Still have questions?
Ask in our Community Channel

Content Powered By