Store

The Store module handles store configuration, subscription management, team access, and webhooks.

Get Store

Retrieve the current store.

const store = await sdk.store.getStore({});

console.log(store.key, store.settings);

List Stores

List all stores the current user has access to.

const result = await sdk.store.getStores({
query: 'store',
isNetwork: false,
status: 'ACTIVE',
limit: 20,
cursor: null,
sort_field: 'created_at',
sort_direction: 'desc'
});

result.items.forEach(store => {
console.log(store.key);
});

Create Store

Create a new store.

const result = await sdk.store.createStore({
key: 'my-store',
timezone: 'America/New_York',
billing_email: '[email protected]',
languages: [{ id: 'en' }],
emails: {
  billing: '[email protected]',
  support: '[email protected]'
}
});

Two default markets are auto-created with every store: us (USD, Exclusive) and eu (EUR, Inclusive). Fetch them with sdk.market.list() or create additional markets with sdk.market.create().

Update Store

Update store settings.

const result = await sdk.store.updateStore({
id: 'store_abc123',
key: 'my-updated-store',
timezone: 'America/New_York',
languages: [{ id: 'en' }],
emails: {
  billing: '[email protected]',
  support: '[email protected]'
}
});

Delete Store

Permanently delete a store and all associated data.

await sdk.store.deleteStore({
  id: 'store_abc123'
});

Subscriptions

Get Subscription Plans

List available subscription plans.

const plans = await sdk.store.getSubscriptionPlans({});

plans.forEach(plan => {
  console.log(plan.name, plan.price, plan.features);
});

Subscribe to Plan

Subscribe a store to a plan. Returns a Stripe checkout URL for payment.

const result = await sdk.store.subscribe({
plan_id: 'plan_pro',
success_url: 'https://yourapp.com/subscription/success',
cancel_url: 'https://yourapp.com/subscription/cancel'
});

// Redirect to Stripe checkout
if (result.url) {
window.location.href = result.url;
}

Create Billing Portal Session

Create a Stripe Profile Portal session for subscription management.

const result = await sdk.store.createPortalSession({
  returnUrl: 'https://yourapp.com/settings/billing'
});

// Redirect to Stripe portal
window.location.href = result.url;

Team Management

Add Member

Add a user to the store team immediately. If the account does not exist yet, it is created with the assigned store role. No confirmation email or accept step is sent.

await sdk.store.addMember({
email: '[email protected]',
role: 'admin'  // 'admin' | 'owner' | 'super'
});

Remove Member

Remove a team member from the store.

await sdk.store.removeMember({
  account_id: 'acc_abc123',
});

Webhooks

Test Webhook

Send a test webhook to verify your endpoint configuration.

await sdk.store.testWebhook({
webhook: {
  url: 'https://yourapp.com/webhooks',
  events: ['order.created', 'order.paid'],
  secret: 'whsec_...'
}
});

console.log('Webhook test sent successfully');

Media

Get Store Media

List all media files for a store.

const result = await sdk.store.getStoreMedia({
  id: 'store_abc123',
  limit: 50,
  cursor: null,
  query: 'product',
  mime_type: 'image/jpeg',
  sort_field: 'created_at',
  sort_direction: 'desc'
});

result.items.forEach(media => {
  console.log(media.id, media.url);
});

Refunds

Process Refund

Process a refund for a payment.

await sdk.store.processRefund({
id: 'store_abc123',
entity: 'ord_xyz789',  // Order ID
amount: 1999  // Partial refund in cents
});

Integrations

Manage third-party service integrations (Stripe, Shippo, Telegram, OpenAI, etc.).

List Integrations

const integrations = await sdk.store.listIntegrations({
  storeId: 'store_abc123',
});

integrations.forEach(integration => {
  console.log(integration.key, integration.provider.type);
});

Create Integration

// Stripe payment integration
await sdk.store.createIntegration({
  storeId: 'store_abc123',
  key: 'stripe-payments',
  provider: {
    type: 'stripe',
    secret_key: 'sk_live_...',
    publishable_key: 'pk_live_...',
    webhook_secret: 'whsec_...',
    currency: 'USD',
    activeForCardPayments: true,
  },
});

// Telegram bot integration
await sdk.store.createIntegration({
  storeId: 'store_abc123',
  key: 'support-telegram',
  provider: {
    type: 'telegram_bot',
    bot_token: '123456:ABC...',
  },
});

Update Integration

await sdk.store.updateIntegration({
  storeId: 'store_abc123',
  id: 'int_xyz789',
  provider: {
    type: 'stripe',
    publishable_key: 'pk_live_new...',
    currency: 'EUR',
  },
});

Delete Integration

await sdk.store.deleteIntegration({
  storeId: 'store_abc123',
  id: 'int_xyz789',
});

Get Integration Config

Get the active integration config for a specific category.

const paymentConfig = await sdk.store.getIntegrationConfig({
  storeId: 'store_abc123',
  type: 'payment', // 'payment' | 'shipping' | 'analytics'
});

Available Provider Types

Plus 20+ more API-key providers (Airtable, Linear, GitHub, Notion, HubSpot, etc.).

Channel Integrations

For messaging channels (telegram_bot), incoming messages are routed to AI agents that have the integration’s ID in their channel_ids array. See AI Agents for setting up agent routing.

OAuth

Connect and disconnect OAuth providers (e.g. Google) for a store.

OAuth Connect

await sdk.store.oauthConnect({
  store_id: 'store_abc123',
  provider: 'google',
  code: 'auth_code_from_oauth_callback',
  redirect_uri: 'https://yourapp.com/oauth/callback',
});

OAuth Disconnect

await sdk.store.oauthDisconnect({
  storeId: 'store_abc123',
  provider: 'google',
});

Webhook CRUD

Manage webhook endpoints programmatically.

List Webhooks

const webhooks = await sdk.store.listWebhooks({
  storeId: 'store_abc123',
});

Create Webhook

await sdk.store.createWebhook({
  storeId: 'store_abc123',
  key: 'order-notifications',
  url: 'https://yourapp.com/webhooks/orders',
  events: [
    { event: 'order.created' },
    { event: 'order.updated' },
  ],
  headers: { 'X-Custom-Header': 'value' },
  secret: 'whsec_my_secret',
  enabled: true,
});

Update Webhook

await sdk.store.updateWebhook({
  storeId: 'store_abc123',
  id: 'wh_xyz789',
  key: 'order-notifications',
  url: 'https://yourapp.com/webhooks/v2/orders',
  events: [
    { event: 'order.created' },
    { event: 'order.updated' },
    { event: 'order.cancelled' },
  ],
  headers: {},
  secret: 'whsec_new_secret',
  enabled: true,
});

Delete Webhook

await sdk.store.deleteWebhook({
  storeId: 'store_abc123',
  id: 'wh_xyz789',
});

Available Webhook Events