ConfigParams
The configuration parameters interface used when initializing the Shopify API library with shopifyApi().
Type Definition
interface ConfigParams<
Resources extends ShopifyRestResources = ShopifyRestResources,
Future extends FutureFlagOptions = FutureFlagOptions,
> {
apiKey?: string;
apiSecretKey: string;
scopes?: string[] | AuthScopes;
hostName: string;
hostScheme?: 'http' | 'https';
apiVersion: ApiVersion;
isEmbeddedApp: boolean;
isCustomStoreApp?: boolean;
adminApiAccessToken?: string;
userAgentPrefix?: string;
privateAppStorefrontAccessToken?: string;
domainTransformations?: DomainTransformation[];
billing?: BillingConfig;
restResources?: Resources;
logger?: LoggerConfig;
future?: Future;
isTesting?: boolean;
}
ConfigInterface
The validated configuration interface returned after initialization.
Type Definition
type ConfigInterface<Params extends ConfigParams = ConfigParams> = Omit<
Params,
'restResources' | 'scopes'
> & {
apiKey: string;
hostScheme: 'http' | 'https';
scopes?: AuthScopes;
isCustomStoreApp: boolean;
billing?: BillingConfig;
logger: {
log: LogFunction;
level: LogSeverity;
httpRequests: boolean;
timestamps: boolean;
};
future: FutureFlagOptions;
isTesting?: boolean;
};
API Versions
The ApiVersion enum defines available Shopify API versions.
Available Versions
ApiVersion.October24
string
default:"'2024-10'"
October 2024 API version
ApiVersion.January25
string
default:"'2025-01'"
January 2025 API version
ApiVersion.April25
string
default:"'2025-04'"
April 2025 API version
ApiVersion.July25
string
default:"'2025-07'"
July 2025 API version
ApiVersion.October25
string
default:"'2025-10'"
October 2025 API version
ApiVersion.January26
string
default:"'2026-01'"
January 2026 API version
ApiVersion.April26
string
default:"'2026-04'"
April 2026 API version
ApiVersion.Unstable
string
default:"'unstable'"
Unstable API version (latest unreleased features)
Example
import { shopifyApi, ApiVersion } from '@shopify/shopify-api';
const shopify = shopifyApi({
apiVersion: ApiVersion.April25, // '2025-04'
// ... other config
});
Domain Transformations
Configuration for transforming shop domains in split-domain architectures.
DomainTransformation Interface
interface DomainTransformation {
match: RegExp | string;
transform: ((matches: RegExpMatchArray) => string | null) | string;
includeHost?: boolean;
}
Pattern to match against shop domains (source domain).Can be a RegExp or string (converted to RegExp internally).
transform
((matches: RegExpMatchArray) => string | null) | string
required
Transformation function or template string.
- Template string: Uses
$1, $2, etc. for capture group substitution
- Function: Receives regex match groups and returns transformed domain
Whether this transformation should also apply to host validation.
Examples
const shopify = shopifyApi({
// ... other config
domainTransformations: [
{
match: /^([a-zA-Z0-9][a-zA-Z0-9-_]*)\.my\.shop\.dev$/,
transform: '$1.dev-api.shop.dev'
}
],
});
// shop1.my.shop.dev → shop1.dev-api.shop.dev
Logger Configuration
Customization options for logging.
LoggerConfig Interface
interface LoggerConfig {
log?: LogFunction;
level?: LogSeverity;
httpRequests?: boolean;
timestamps?: boolean;
}
A custom log function with signature:type LogFunction = (severity: LogSeverity, msg: string) => void;
The minimum severity level to log.
Whether to log HTTP requests.
Whether to log timestamps.
LogSeverity Enum
enum LogSeverity {
Error = 0,
Warning = 1,
Info = 2,
Debug = 3,
}
Example
import { shopifyApi, LogSeverity } from '@shopify/shopify-api';
const shopify = shopifyApi({
// ... other config
logger: {
log: (severity, message) => {
const levels = ['ERROR', 'WARNING', 'INFO', 'DEBUG'];
console.log(`[${levels[severity]}] ${message}`);
},
level: LogSeverity.Info,
httpRequests: true,
timestamps: true,
},
});
Billing Configuration
See the Billing API reference for detailed billing configuration options.
HTTP Methods
The Method enum defines available HTTP methods.
enum Method {
Get = 'GET',
Post = 'POST',
Put = 'PUT',
Patch = 'PATCH',
Delete = 'DELETE',
Head = 'HEAD',
Options = 'OPTIONS',
Connect = 'CONNECT',
}
enum ShopifyHeader {
AccessToken = 'X-Shopify-Access-Token',
ApiVersion = 'X-Shopify-API-Version',
Domain = 'X-Shopify-Shop-Domain',
Hmac = 'X-Shopify-Hmac-Sha256',
Topic = 'X-Shopify-Topic',
SubTopic = 'X-Shopify-Sub-Topic',
WebhookId = 'X-Shopify-Webhook-Id',
Name = 'X-Shopify-Name',
TriggeredAt = 'X-Shopify-Triggered-At',
EventId = 'X-Shopify-Event-Id',
StorefrontPrivateToken = 'Shopify-Storefront-Private-Token',
StorefrontSDKVariant = 'X-SDK-Variant',
StorefrontSDKVersion = 'X-SDK-Version',
}
Notes
All configuration is validated when you call shopifyApi(). Missing or invalid required fields will throw a ShopifyError.
For custom store apps, set isCustomStoreApp: true and provide adminApiAccessToken. The apiKey and scopes parameters become optional.
Domain transformations are applied in order. The first matching transformation is used.