Skip to content
Bifröst OrbitDocs

Get started as a developer

What you can build on Commerce Orbit, where each API lives, how it decides who you are, and your first request.

Tutorial3 min read

Commerce Orbit holds a shop's products, stock, prices, carts and orders. The shop's team runs them in the app; your website reads them and takes orders through the APIs below. Payments go from the shopper's browser straight to the shop's own Stripe account, never through your server or ours.

What you can build

Show products and collections with live prices and stock
Use
The storefront API (REST) or GraphQL
Run a cart with discount codes, shipping choices and VAT
Use
The cart endpoints in the storefront API
Take payment on your own website
Use
Checkout in the storefront API, with Stripe's Payment Element. See Checkout with Stripe.
Show an order and its tracking after checkout
Use
The order endpoint in the storefront API
Preview draft products on a staging website
Use
An API key that reads drafts, from your server
Let an AI assistant look up products and orders
Use
The MCP server
Try requests with the shop's own data

If the website is built in CMS Orbit, editors can put products on pages without code: see Show your products on your website. The hosted shop at https://app.bifrostorbit.com/commerce/shop/{shop address} needs no code either, and your website can link to its products and cart.

Addresses

Storefront API
Address
https://app.bifrostorbit.com/commerce/api/public/{shop address}
GraphQL
Address
https://app.bifrostorbit.com/commerce/api/cdn/graphql
MCP server
Address
https://app.bifrostorbit.com/commerce/mcp
Hosted shop
Address
https://app.bifrostorbit.com/commerce/shop/{shop address}

The shop address is set under Settings, such as northwilds.

Who you are

  • Reading the shop, products and collections needs no key. It returns only what the hosted shop shows anyway.
  • Carts, checkout and orders need no key either. From a browser, only the shop's Website and Allowed websites in Settings may call them; a call from your server, without an Origin header, always may. An order is only shown to someone who has its number and the email it was placed with.
  • API keys are optional. A key that starts with com_pk_ counts your requests; one that starts with com_sk_ also reads draft products and works only from a server. Admins create them under API keys.
  • The MCP server signs in with OAuth as a person on the team, with that person's role.

Your first request

List the shop's winter products, in Norwegian and Norwegian kroner:

Shell
curl 'https://app.bifrostorbit.com/commerce/api/public/northwilds/products?tag=winter&locale=nb&currency=NOK'
JSON
{  "data": [    {      "id": "6650f1c2a9e4b3d2c1f0e9b1",      "slug": "fjell-gtx-boot",      "title": "Fjell GTX-støvel",      "price": { "min": 289000, "max": 289000, "currency": "NOK", "compareAt": null },      "available": true,      "variants": [{ "id": "v3f9a1c2b7e", "title": "42 / Brown", "sku": "FJELL-GTX-42-BRN", "price": 289000, "available": true, "quantity": 7 }],      "url": "https://app.bifrostorbit.com/commerce/shop/northwilds/products/fjell-gtx-boot",      "locale": "nb"    }  ]}

The answer is shortened. Amounts are whole minor units: 289000 with NOK is 2,890 kr.

The same in GraphQL, from a browser:

JavaScript
const response = await fetch("https://app.bifrostorbit.com/commerce/api/cdn/graphql?organisation=northwilds", {  method: "POST",  headers: { "Content-Type": "application/json" },  body: JSON.stringify({ query: '{ products(tag: "winter", locale: "nb", currency: "NOK") { slug title price { min currency } available } }' }),});const { data } = await response.json();

From here

  1. Open API playground under Developers in the sidebar and run Products with the shop's data.
  2. Read the storefront API for every field, the cart and the order.
  3. Ask an Admin to add your website under Allowed websites before you call carts from the browser.
  4. Read Checkout with Stripe to take payment.
  5. When something answers with an error, look it up in Troubleshooting.

Commerce Orbit records what happens to products, stock and orders as events in Orbit Exchange. It doesn't send webhooks to your own systems yet, and there is no Commerce Orbit SDK: the APIs are plain HTTP and JSON.

Was this page helpful?

Read next

The storefront APIRead the shop, products and collections, build a cart, check out with Stripe or on invoice and show the order, from your own website. Endpoints, fields, CORS, caching and rate limits.Checkout with StripeTake payment on your own website with Stripe's Payment Element, using the client secret and publishable key from checkout, send the shopper to their order page, and know what happens when they never finish.GraphQLRead the shop, products and collections in one request, with the schema, examples, errors and limits. Carts and checkout stay in the storefront API.API keysCreate keys for the storefront API and GraphQL to preview draft products on your website and to see which website calls and how often. Reading works without one.The API playgroundTry the storefront API and GraphQL with the shop's own products and collections, see the JSON your website gets, and copy the request as curl or JavaScript.EventsThe events Commerce Orbit sends to Orbit Exchange when products, stock, collections, orders and the MAM connection change, what each carries, and how they are delivered. The same events can go to your own systems as webhooks.The MCP serverConnect any MCP client to Commerce Orbit with OAuth sign-in, and the tools it gets for products, collections, orders and the shop's status.Troubleshooting the APIsThe errors the storefront API, GraphQL and the MCP server answer with, what each one means and what to do about it.