@godaddy/gd-commerce-server
An opinionated Express router for GoDaddy Commerce catalog, cart, and hosted checkout APIs.
import express from 'express';
import { createCommerceRouter, createRuntimeCommerceConfiguration } from '@godaddy/gd-commerce-server';
const app = express();
app.use(express.json());
app.use('/api/commerce', createCommerceRouter({
configuration: createRuntimeCommerceConfiguration(),
checkoutReturnUrls: {
returnUrls: ['https://shop.example.com/shop'],
successUrls: ['https://shop.example.com/checkout/success'],
},
}));
The default configuration reads these server-only environment variables on each request:
GODADDY_OAUTH_CLIENT_IDandGODADDY_OAUTH_CLIENT_SECRETGODADDY_STORE_IDandGODADDY_CHANNEL_IDGODADDY_CURRENCY_CODE- Optional
GODADDY_CHECKOUT_CONFIGURATION: JSON with booleanenablePromotionCodes,enableTaxCollection, andenableShippingfields. All three default to false when this variable is absent or malformed so configuration discovery cannot prevent checkout creation. Optionalshippingaccepts the checkout API'soriginAddressorfulfillmentLocationId; omit it to use store configuration.
See Checkout configuration for the temporary build-time synchronization flow and its eventual-consistency limitation.
The API origin defaults to https://api.godaddy.com. The package does not load files, provision merchants, or assign application attribution. Hosts own these concerns and any readiness checks or retries before invoking Commerce.
Host configuration
For an alternate API origin, pass an explicit server-controlled option. It must be an HTTPS origin without credentials, a path, query, or fragment. The host is responsible for trusting the destination, which receives OAuth credentials. Request bodies never select the API origin or attribution.
const configuration = createRuntimeCommerceConfiguration({
apiBaseUrl: process.env.COMMERCE_API_ORIGIN, // undefined uses production
sourceApp: process.env.COMMERCE_SOURCE_APP,
owner: process.env.COMMERCE_ORDER_OWNER,
});
apiBaseUrl controls catalog, order, and OAuth requests; checkout uses the corresponding checkout.commerce. subdomain. There is no built-in list of alternate environments. sourceApp and owner are optional host-owned attribution values: checkout uses both, while draft orders use owner. Supply values required by your Commerce integration; the package omits them by default.
Hosts with their own configuration service can implement CommerceConfiguration directly. read() returns clientId, clientSecret, storeId, channelId, currencyCode, apiBaseUrl, and optional attribution. readCheckout() returns the checkout flags and optional shipping settings. Return validated, ready-to-use settings from one consistent binding. Both functions run on the server; credentials must never reach browser code.
Routers and helpers
createCommerceCatalogRouter(configuration) installs catalog, public configuration, and cart routes. createGoDaddyPaymentsRouter(configuration, checkoutReturnUrls) installs checkout and read-only order-status routes without requiring catalog UI. createCommerceRouter({ configuration }) installs both by default or accepts explicit feature flags.
The HTTP checkout route accepts an existing draftOrderId or a direct skuId; Commerce resolves catalog prices. It rejects lineItemData. For non-catalog charges such as fixed-price deposits, calculate the amount on the server and call createCheckoutSession(params, configuration) directly. Never forward browser-supplied prices to this trusted helper. Server callers can also use getOrderStatus(orderId, configuration) without an HTTP loopback.
Product channel visibility
GET /products and GET /products/:id use the channel from the server configuration and request only ACTIVE products. Search, category filters, and explicit product IDs retain that channel filter. Product-detail requests for products unavailable on that channel return 404. Browser query parameters cannot select a different channel. Products configured for all channels remain available when the configured channel is active and registered to the store.
If a configured GODADDY_CHANNEL_ID is inactive or is not registered to the configured store, the Catalog API returns an empty product list and product-detail requests return 404. These are successful empty results from the Catalog API, not configuration errors. When an expected catalog is empty, verify that the channel is active and registered to GODADDY_STORE_ID, then check product status and channel assignments. A missing GODADDY_CHANNEL_ID is different: the default configuration reader rejects it with 503 not_configured.
The Catalog API resolves active store channels through the paginated /v1/commerce/channels endpoint when evaluating a channel filter. Those lookups are not currently cached by the Catalog API, so channel-filtered catalog requests can add upstream calls and latency.
These checks control product browsing. GET /skus/:id, cart creation (POST /cart), and item addition (POST /cart/:id/items) forward SKU IDs without this package checking whether their products are available on the configured channel. A 404 from product details does not establish that a SKU lookup or cart write will be rejected. Hosts that require channel-based restrictions on these operations must enforce them before forwarding the SKU IDs; browsing filters are not an authorization boundary.
Checkout return destinations
Configure checkoutReturnUrls on the router using trusted deployment settings. Both lists contain complete absolute HTTPS URLs; scheme, origin, port, path, and configured query parameters must match. Success URLs may add a single orderId query parameter. Additional query parameters, fragments, credentials, relative URLs, and unlisted destinations are rejected. Configure separate cancel and success destinations as shown above; do not derive the allowlist from request headers or request bodies.
Without this policy, HTTP checkout returns 503 before creating a session. Invalid request destinations return 400. This applies to both router presets that expose checkout. Trusted in-process callers of createCheckoutSession() own their return URLs and must construct or validate them server-side.
A return from hosted checkout is not proof of payment. The order-status route uses the authorized Orders REST API, which supports completed orders, and returns its payment status (for example PAID or PENDING; the exported ORDER_STATUS_UNKNOWN, 'unknown', if absent). Show it only as display enrichment and never present an unconfirmed payment as paid. The server OAuth client must be granted commerce.order:read. The helper verifies the returned order ID, store, and channel and returns a limited summary without customer contact data. The route returns 400 for a missing, blank, padded, ., or .. order ID (padded IDs are rejected, not trimmed) or one the Orders API rejects as malformed (422 VALIDATION_FAILED), and 404 when the Orders API reports the order missing (404 NOT_FOUND) or the order belongs to another store or channel. A 404 without that code, such as from a misconfigured API base URL, is an upstream failure. Token and other Commerce failures, including a response for a different order ID, return 502 and unreadable configuration returns 503 (see Errors). Hosts must authenticate callers and authorize access to each requested order before exposing this route.
Connection state
Hosts can implement the optional synchronous CommerceConfiguration.readConnectionState()
method. Its return type is exported as CommerceConnectionState (unbound | connecting | ready).
Returning undefined keeps the existing behavior. Throw when the state is unknown or cannot be
read. The default environment configuration does not implement this method, so missing
credentials never count as unbound.
GET /config returns { state: 'unbound' } or { state: 'connecting' } without reading store
credentials. ready includes the usual opaque cartScope and currencyCode after read()
succeeds. Without this method, the successful response shape is unchanged. All responses are
uncached; a malformed state or unavailable configuration returns 503. Data and checkout routes,
and the in-process checkout and order helpers, reject any state other than ready before
upstream calls.
The host owns the connection lifecycle. Report ready only after the store connection is
complete. Lost configuration is an error, never evidence of unbound. After a store connects,
report unbound again only after it is deliberately disconnected. The storefront package owns
the generic sample products and local sample cart; this server never creates sample Commerce
records or simulates checkout.
A site before its store connects
A template that shows the storefront's sample products before a store connects needs the catalog routes and an
explicit connection state. Here COMMERCE_CONNECTION_STATE is a host-owned setting, set to unbound when the site
is created and to ready by the host's connection flow. Read it from whatever records the connection; never derive
it from missing GODADDY_* variables.
import express from 'express';
import { createCommerceCatalogRouter, createRuntimeCommerceConfiguration } from '@godaddy/gd-commerce-server';
const runtime = createRuntimeCommerceConfiguration();
const configuration = {
...runtime,
readConnectionState() {
const state = process.env.COMMERCE_CONNECTION_STATE;
if (state === 'unbound' || state === 'connecting' || state === 'ready') return state;
throw new Error('COMMERCE_CONNECTION_STATE must be unbound, connecting, or ready.');
},
};
const app = express();
app.use(express.json());
// Before static files and any single-page app or SSR fallback, which would answer /api/commerce with HTML.
app.use('/api/commerce', createCommerceCatalogRouter(configuration));
app.use(express.static('dist'));
createCommerceCatalogRouter exposes no checkout routes, so a site without checkout needs no checkoutReturnUrls.
GET /api/commerce/config should return {"state":"unbound"} as JSON. If it returns the app's HTML page, the
router is not mounted, or a fallback route runs before it.
Errors
Every route reports failures the same way. The body is { "error": "<customer-facing message>", "code": "<code>", "requestId": "<id>" } (order-status also includes success: false). The same id is passed to the logger. Bodies never contain upstream messages, configuration details, or credentials.
| Status | code | Meaning |
|---|---|---|
| 400 | invalid_request | Missing or invalid input. |
| 404 | not_found | Missing order or product, or a write to an existing cart (/cart/:id/...) that is missing, expired, or completed. Cart reads keep returning 200 { "cart": null }. Checkout with a stale or completed draftOrderId is not yet distinguished and returns 502. |
| 409 | scope_mismatch | X-Commerce-Scope no longer matches the configured store binding. |
| 502 | upstream_unauthorized | Commerce rejected this server's OAuth client or requested scope (HTTP 401/403, or an OAuth 400 with invalid_client, invalid_grant, unauthorized_client, or invalid_scope). It concerns server credentials, not the caller, so it is never reported as 401/403. |
| 502 | upstream_error | Commerce failed, returned an unexpected response, or could not be reached. |
| 503 | not_configured | Configuration is missing or unreadable, the host reports a connection state other than ready, or checkout return URLs are not configured. |
| 500 | internal_error | An unexpected error in this package. |
Upstream errors without a specific mapping stay 502; business errors such as invalid discount codes are not yet distinguished. 5xx detail, including upstream status and GraphQL error codes, goes to the logger:
createCommerceRouter({
configuration,
logger: { error: (message, context) => log.error(context, message) },
// Use the host's request id when its edge sets one; unsafe or missing ids fall back to a UUID.
getRequestId: (req) => req.get('x-request-id'),
});
createCommerceCatalogRouter and createGoDaddyPaymentsRouter accept the same { logger, getRequestId } as their last argument. The logger defaults to console.error. In-process helpers throw the exported CommerceError subclasses (InvalidRequestError, NotFoundError, CommerceNotConfiguredError, UpstreamError), including when a host configuration throws while being read. Check error.code (for example 'not_found') rather than instanceof, which fails when a host has more than one copy of this package.