Skip to content
Arky Docs

E-shop API

Manage your e-commerce catalog, process orders, and handle checkout flows.

Integration Patterns

Section titled “Integration Patterns”

Before diving into the raw API, check out the E-commerce Integration Guide for complete flows:

  • Product Listing & Detail: Browse catalog with variants and pricing
  • Cart Management: Client-side cart state with items
  • Quote & Checkout: Get totals, apply promo codes, and complete purchases
  • Payment Handling: Stripe checkout and confirmation

Complete E-commerce Flow

Section titled “Complete E-commerce Flow”
import { createArkySDK } from 'arky-sdk';


// Client-side init with guest token
const sdk = createArkySDK({
  baseUrl: 'https://api.arky.io',
  businessId: 'your-business-id',
  market: 'us',
  autoGuest: true, // Auto-fetch guest token
  // ... token handlers
});


// 1. Fetch products
const { items: products } = await sdk.eshop.getProducts({
  limit: 20,
  market: 'us',
});


// 2. Get product detail
const product = await sdk.eshop.getProduct({ id: 'prod_123' });


// 3. Maintain cart state (client-side)
const cart = [
  { productId: 'prod_123', variantId: 'var_456', quantity: 2 },
];


// 4. Get quote (pricing, shipping, tax)
const quote = await sdk.eshop.getQuote({
  items: cart,
  address: { /* shipping address */ },
  promoCode: 'SAVE10',
});


// 5. Checkout
const checkout = await sdk.eshop.checkout({
  items: cart,
  quote: quote.id,
  paymentMethod: 'STRIPE',
  returnUrl: 'https://yourapp.com/order/success',
  cancelUrl: 'https://yourapp.com/cart',
});


// 6. Redirect to payment
if (checkout.paymentUrl) {
  window.location.href = checkout.paymentUrl;
}

See E-commerce Integration Guide for complete patterns.

Base URL

Section titled “Base URL”

All E-shop endpoints are prefixed with /v1/businesses/{businessId}.

Authentication

Section titled “Authentication”

Requires Authorization: Bearer <access_token> header. Guest tokens can be used for browsing products and checkout.

Products

Section titled “Products”

Create Product

Section titled “Create Product”

Endpoint: POST /v1/businesses/{businessId}/products

const product = await sdk.eshop.createProduct({
  name: 'Premium T-Shirt',
  slug: 'premium-t-shirt',
  description: 'High-quality cotton t-shirt',
  category: 'Apparel',
  gallery: [
    { id: 'media_123', url: 'https://...', mimeType: 'image/jpeg' },
  ],
  variants: [
    {
      id: 'variant_small_red',
      name: 'Small / Red',
      sku: 'TSHIRT-S-RED',
      attributes: [
        { name: 'Size', value: 'S' },
        { name: 'Color', value: 'Red' },
      ],
      pricing: {
        markets: [
          {
            marketId: 'US',
            currency: 'USD',
            price: 2999, // $29.99 in cents
            compareAtPrice: 3999,
          },
        ],
      },
      inventory: {
        tracked: true,
        quantity: 100,
      },
    },
    {
      id: 'variant_medium_red',
      name: 'Medium / Red',
      sku: 'TSHIRT-M-RED',
      attributes: [
        { name: 'Size', value: 'M' },
        { name: 'Color', value: 'Red' },
      ],
      pricing: {
        markets: [
          {
            marketId: 'US',
            currency: 'USD',
            price: 2999,
          },
        ],
      },
      inventory: {
        tracked: true,
        quantity: 150,
      },
    },
  ],
  statuses: [
    {
      id: 'status_1',
      status: 'ACTIVE',
      changedBy: 'USER',
      timestamp: Date.now() / 1000,
    },
  ],
  blocks: [], // Optional: custom product fields
});

Response:

{
  "id": "prod_abc123",
  "businessId": "biz_123",
  "name": "Premium T-Shirt",
  "slug": "premium-t-shirt",
  "description": "High-quality cotton t-shirt",
  "category": "Apparel",
  "gallery": [...],
  "variants": [...],
  "statuses": [...],
  "blocks": [],
  "createdAt": 1698765432,
  "updatedAt": 1698765432
}

Get Products

Section titled “Get Products”

List all products with pagination and filtering.

Endpoint: GET /v1/businesses/{businessId}/products

const { items, cursor } = await sdk.eshop.getProducts({
  limit: 20,
  cursor: null,
  category: 'Apparel', // Optional filter
});


// Search products
const results = await sdk.eshop.getProducts({
  query: 't-shirt',
  limit: 10,
});

Get Product

Section titled “Get Product”

Fetch a specific product by ID.

Endpoint: GET /v1/businesses/{businessId}/products/{id}

const product = await sdk.eshop.getProduct({
  id: 'prod_abc123',
});


console.log('Variants:', product.variants.length);
console.log('Price:', product.variants[0].pricing.markets[0].price);

Update Product

Section titled “Update Product”

Endpoint: PUT /v1/businesses/{businessId}/products/{id}

const updated = await sdk.eshop.updateProduct({
  id: 'prod_abc123',
  name: 'Updated T-Shirt Name',
  variants: [...], // Updated variants
});

Delete Product

Section titled “Delete Product”

Endpoint: DELETE /v1/businesses/{businessId}/products/{id}

await sdk.eshop.deleteProduct({
  id: 'prod_abc123',
});

Orders

Section titled “Orders”

Create Order

Section titled “Create Order”

Create an order manually (without checkout flow).

Endpoint: POST /v1/businesses/{businessId}/orders

const order = await sdk.eshop.createOrder({
  customerId: 'user_xyz',
  market: 'US',
  currency: 'USD',
  lines: [
    {
      type: 'PRODUCT_VARIANT',
      productId: 'prod_abc123',
      variantId: 'variant_small_red',
      quantity: 2,
      unitPrice: 2999,
      totalPrice: 5998,
    },
  ],
  subtotal: 5998,
  tax: 420,
  shipping: 500,
  total: 6918,
  statuses: [
    {
      id: 'status_1',
      status: 'PENDING',
      changedBy: 'USER',
      timestamp: Date.now() / 1000,
    },
  ],
  paymentStatus: [
    {
      id: 'payment_status_1',
      status: 'PENDING',
      changedBy: 'USER',
      timestamp: Date.now() / 1000,
    },
  ],
});

Get Orders

Section titled “Get Orders”

List orders with filtering.

Endpoint: GET /v1/businesses/{businessId}/orders

const { items, cursor } = await sdk.eshop.getOrders({
  limit: 20,
  cursor: null,
  status: 'PENDING', // Optional filter
  customerId: 'user_xyz', // Optional filter
});

Get Order

Section titled “Get Order”

Endpoint: GET /v1/businesses/{businessId}/orders/{id}

const order = await sdk.eshop.getOrder({
  id: 'order_abc123',
});


console.log('Total:', order.total);
console.log('Status:', order.statuses[order.statuses.length - 1].status);
console.log('Payment:', order.paymentStatus[order.paymentStatus.length - 1].status);

Update Order

Section titled “Update Order”

Endpoint: PUT /v1/businesses/{businessId}/orders/update

const updated = await sdk.eshop.updateOrder({
  id: 'order_abc123',
  lines: [...], // Updated line items
  subtotal: 6000,
  total: 7000,
});

Update Order Status

Section titled “Update Order Status”

Endpoint: PUT /v1/businesses/{businessId}/orders/{id}/status

await sdk.eshop.updateOrderStatus({
  id: 'order_abc123',
  status: 'SHIPPED',
  changedBy: 'USER',
  userId: 'user_xyz',
  timestamp: Date.now() / 1000,
});

Common Order Statuses:

  • PENDING
  • PROCESSING
  • SHIPPED
  • DELIVERED
  • CANCELLED
  • REFUNDED

Update Payment Status

Section titled “Update Payment Status”

Endpoint: PUT /v1/businesses/{businessId}/orders/{id}/payment-status

await sdk.eshop.updateOrderPaymentStatus({
  id: 'order_abc123',
  status: 'PAID',
  changedBy: 'SYSTEM',
  timestamp: Date.now() / 1000,
});

Payment Statuses:

  • PENDING
  • PAID
  • FAILED
  • REFUNDED
  • PARTIALLY_REFUNDED

Checkout Flow

Section titled “Checkout Flow”

Get Quote

Section titled “Get Quote”

Calculate pricing with tax, shipping, and promo codes.

Endpoint: POST /v1/payments/quote

const quote = await sdk.eshop.getQuote({
  currency: 'USD',
  paymentMethod: 'CREDIT_CARD',
  items: [
    {
      productId: 'prod_abc123',
      variantId: 'variant_small_red',
      quantity: 2,
    },
  ],
  shippingMethodId: 'shipping_standard',
  promoCode: 'SUMMER2024', // Optional
});


console.log('Subtotal:', quote.subtotal);
console.log('Tax:', quote.tax);
console.log('Shipping:', quote.shipping);
console.log('Discount:', quote.discount);
console.log('Total:', quote.total);

Response:

{
  "lines": [
    {
      "type": "PRODUCT_VARIANT",
      "productId": "prod_abc123",
      "variantId": "variant_small_red",
      "quantity": 2,
      "unitPrice": 2999,
      "totalPrice": 5998
    }
  ],
  "subtotal": 5998,
  "tax": 420,
  "taxBps": 700,
  "shipping": 500,
  "discount": 600,
  "total": 6318,
  "currency": "USD"
}

Checkout

Section titled “Checkout”

Process payment and create order.

Endpoint: POST /v1/businesses/{businessId}/orders/checkout

const result = await sdk.eshop.checkout({
  paymentMethod: 'CREDIT_CARD',
  shippingMethodId: 'shipping_standard',
  items: [
    {
      productId: 'prod_abc123',
      variantId: 'variant_small_red',
      quantity: 2,
    },
  ],
  blocks: [
    // Optional: shipping address, custom fields
    {
      id: 'shipping_address',
      type: 'TEXT',
      value: '123 Main St, New York, NY 10001',
    },
  ],
  promoCode: 'SUMMER2024',
});


if (result.checkoutUrl) {
  // Redirect to Stripe checkout
  window.location.href = result.checkoutUrl;
} else {
  // Order completed
  console.log('Order ID:', result.orderId);
}

Response (Stripe):

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_...",
  "orderId": "order_abc123"
}

Response (Free Order):

{
  "orderId": "order_abc123",
  "status": "COMPLETED"
}

Product Variants

Section titled “Product Variants”

Variants represent different configurations of a product (size, color, etc.).

Structure:

{
  id: 'variant_123',
  name: 'Medium / Blue',
  sku: 'TSHIRT-M-BLUE',
  attributes: [
    { name: 'Size', value: 'M' },
    { name: 'Color', value: 'Blue' },
  ],
  pricing: {
    markets: [
      {
        marketId: 'US',
        currency: 'USD',
        price: 2999, // cents
        compareAtPrice: 3999, // Original price (for sale display)
      },
      {
        marketId: 'EU',
        currency: 'EUR',
        price: 2799,
      },
    ],
  },
  inventory: {
    tracked: true,
    quantity: 50,
    lowStockThreshold: 10,
  },
  gallery: [], // Optional: variant-specific images
}

Inventory Management

Section titled “Inventory Management”

Inventory is tracked per variant:

  • tracked: true - Track stock levels
  • tracked: false - Unlimited stock
  • quantity - Current stock level
  • lowStockThreshold - Alert when stock is low

When an order is placed, inventory is automatically decremented.

Pricing & Markets

Section titled “Pricing & Markets”

Products can have different prices per market:

pricing: {
  markets: [
    {
      marketId: 'US',
      currency: 'USD',
      price: 2999,
    },
    {
      marketId: 'EU',
      currency: 'EUR',
      price: 2799,
    },
  ],
}

The SDK automatically selects the correct market price based on apiConfig.market.

Section titled “Related”