Skip to main content

Documentation Index

Fetch the complete documentation index at: https://quickbutik.dev/llms.txt

Use this file to discover all available pages before exploring further.

This tutorial will walk you through building your first Quickbutik integration. You’ll learn how to authenticate, fetch data, and handle responses.
Prerequisites: You’ll need a Quickbutik store and an API key. If you don’t have an API key yet, generate one in your store’s Control Panel under Settings → API.

​
What we’ll build

By the end of this tutorial, you’ll have a simple integration that:
  • ✅ Authenticates with the Quickbutik API
  • ✅ Fetches your store’s product count
  • ✅ Retrieves your latest orders
  • ✅ Handles errors gracefully

​
Step 1: Set up authentication

First, let’s test your API connection with a simple request to count your products: 
# Replace 'your_api_key' with your actual API key
curl https://api.quickbutik.com/v1/products/count \
  -u your_api_key:your_api_key \
  -H "Content-Type: application/json"

​
Expected Response

{
  "count": "42"
}
Common issues:
  • 401 Unauthorized: Check that your API key is correct
  • Invalid base64: Ensure you’re encoding api_key:api_key format
  • SSL errors: Make sure you’re using https:// not http://
Test your base64 encoding:
echo -n "your_api_key:your_api_key" | base64

​
Step 2: Fetch your latest orders

Now let’s retrieve your most recent orders: 
curl "https://api.quickbutik.com/v1/orders?limit=5&include_details=true" \
  -u your_api_key:your_api_key \
  -H "Content-Type: application/json"

​
Expected Response

[
  {
    "order_id": "12345",
    "date_created": "2025-01-29 11:35:39",
    "total_amount": "148.95",
    "status": "1"
  }
]

​
Step 3: Update an order status

Let’s mark an order as “done” (shipped): 
curl -X PUT https://api.quickbutik.com/v1/orders \
  -u your_api_key:your_api_key \
  -H "Content-Type: application/json" \
  -d '[{
    "order_id": "12345",
    "status": "done",
    "shipping_info": {
      "trackingnumber": "1Z999AA1234567890",
      "company": "UPS"
    },
    "email_confirmation": "true"
  }]'

​
Step 4: Handle errors like a pro

Here’s how to build robust error handling: 
class QuickbutikAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.credentials = Buffer.from(`${apiKey}:${apiKey}`).toString('base64');
    this.baseUrl = 'https://api.quickbutik.com/v1';
  }

  async request(endpoint, options = {}) {
    const url = `${this.baseUrl}${endpoint}`;
    
    try {
      const response = await fetch(url, {
        ...options,
        headers: {
          'Authorization': `Basic ${this.credentials}`,
          'Content-Type': 'application/json',
          ...options.headers
        }
      });

      // Handle different HTTP status codes
      if (!response.ok) {
        const errorData = await response.json().catch(() => ({}));
        
        switch (response.status) {
          case 401:
            throw new Error('Authentication failed. Check your API key.');
          case 404:
            throw new Error(`Resource not found: ${errorData.error || 'Unknown error'}`);
          case 400:
            throw new Error(`Bad request: ${errorData.error || 'Invalid data provided'}`);
          case 500:
            throw new Error('Server error. Please try again later.');
          default:
            throw new Error(`HTTP ${response.status}: ${errorData.error || response.statusText}`);
        }
      }

      return await response.json();
    } catch (error) {
      if (error.name === 'TypeError' && error.message.includes('fetch')) {
        throw new Error('Network error. Check your internet connection.');
      }
      throw error;
    }
  }

  async getOrders(params = {}) {
    const queryString = new URLSearchParams(params).toString();
    const endpoint = queryString ? `/orders?${queryString}` : '/orders';
    return this.request(endpoint);
  }

  async updateOrderStatus(updates) {
    return this.request('/orders', {
      method: 'PUT',
      body: JSON.stringify(Array.isArray(updates) ? updates : [updates])
    });
  }
}

// Usage
const api = new QuickbutikAPI('your_api_key');

async function example() {
  try {
    const orders = await api.getOrders({ limit: 5 });
    console.log('Orders fetched successfully:', orders.length);
  } catch (error) {
    console.error('Failed to fetch orders:', error.message);
  }
}

​
🎉 Congratulations!

You’ve successfully built your first Quickbutik integration! You now know how to:
  • ✅ Authenticate with the API
  • ✅ Fetch orders and products
  • ✅ Update order statuses
  • ✅ Handle errors gracefully

​
Next steps

Set up webhooks

Get real-time notifications when orders are created or updated

Order sync tutorial

Learn how to build a complete order synchronization system

​
Need help?

Get Support

Stuck on something? We’re here to help! Reach out to support@quickbutik.com with your questions.