API Documentation

Overview of Store.icu API Platform

The Store.icu API platform provides partners and developers with programmatic access to store data, business logic, and platform functionality. This comprehensive API allows you to build integrations, automate processes, and create custom solutions for your clients.

API Access

Authentication

All API requests require authentication using OAuth 2.0:

Register your application in the Partner Dashboard
Obtain client credentials (client ID and secret)
Implement the OAuth 2.0 authorization flow
Use the resulting access token in the Authorization header

Authorization: Bearer {access_token}

Access Scopes

Request only the permissions your integration needs:

Scope	Access Level	Description
`read_products`	Read-only	View product data
`write_products`	Read-write	Create and modify products
`read_orders`	Read-only	View order information
`write_orders`	Read-write	Create and update orders
`read_customers`	Read-only	Access customer data
`write_customers`	Read-write	Create and update customers
`read_inventory`	Read-only	View inventory levels
`write_inventory`	Read-write	Adjust inventory
`read_content`	Read-only	Access content pages
`write_content`	Read-write	Modify store content
`read_themes`	Read-only	View theme data
`write_themes`	Read-write	Modify store theme
`read_reports`	Read-only	Access analytics data
`admin`	Full access	Complete store management

Detailed information on scope implementation is available in the Scope Documentation.

Rate Limits

API usage is subject to the following rate limits:

Partner Tier	Requests per Minute	Burst Capacity	Daily Limit
Standard	60	120	20,000
Gold	120	240	50,000
Platinum	240	480	100,000

Rate limit information is included in response headers:

X-Rate-Limit-Limit: 60
X-Rate-Limit-Remaining: 58
X-Rate-Limit-Reset: 1620000000

API Versions

Store.icu uses API versioning to ensure compatibility:

Version	Status	End-of-Life Date
v3	Current	Active
v2	Deprecated	January 1, 2026
v1	Legacy	June 30, 2025

Specify the API version in the URL:

https://api.store.icu/v3/products

Version migration guides are available in the API Changelog.

Core API Resources

Products

Manage product catalog:

GET /api/v3/products
POST /api/v3/products
GET /api/v3/products/{id}
PUT /api/v3/products/{id}
DELETE /api/v3/products/{id}

Product resource features:

Comprehensive product attributes
Variant management
Custom field support
Bulk operations
Image handling
Inventory synchronization

Products API Documentation

Orders

Handle customer orders:

GET /api/v3/orders
POST /api/v3/orders
GET /api/v3/orders/{id}
PUT /api/v3/orders/{id}

Order management capabilities:

Complete order lifecycle
Status updates
Fulfillment tracking
Payment processing
Refund handling
Order notes
Custom metadata

Orders API Documentation

Customers

Manage customer data:

GET /api/v3/customers
POST /api/v3/customers
GET /api/v3/customers/{id}
PUT /api/v3/customers/{id}
DELETE /api/v3/customers/{id}

Customer resource features:

Profile management
Address book
Order history
Groups and segmentation
Consent tracking
Account status

Customers API Documentation

Inventory

Track and manage stock:

GET /api/v3/inventory
GET /api/v3/inventory/{product_id}
POST /api/v3/inventory/adjustments

Inventory capabilities:

Real-time stock levels
Allocation management
Multi-location support
Movement history
Low stock alerts
Batch updates

Inventory API Documentation

Cart & Checkout

Manage shopping carts:

POST /api/v3/carts
GET /api/v3/carts/{id}
PUT /api/v3/carts/{id}
POST /api/v3/carts/{id}/checkout

Cart features:

Item management
Price calculation
Promotion application
Checkout initiation
Abandoned cart recovery
Guest cart handling

Cart API Documentation

Content

Manage store content:

GET /api/v3/pages
POST /api/v3/pages
GET /api/v3/pages/{id}
PUT /api/v3/pages/{id}
DELETE /api/v3/pages/{id}

Content management features:

Page creation and editing
Blog post management
Navigation menus
Media library
Metadata handling
Content scheduling

Content API Documentation

Advanced API Features

GraphQL API

For complex data requirements, use our GraphQL endpoint:

POST https://api.store.icu/graphql

Benefits of GraphQL:

Request exactly the data you need
Combine multiple resources in a single request
Reduce network overhead
Strongly typed schema
Interactive documentation

GraphQL API Documentation

Bulk Operations

Efficiently manage large datasets:

POST /api/v3/bulk/products/import
POST /api/v3/bulk/customers/export

Bulk operation capabilities:

Asynchronous processing
CSV and JSON format support
Progress tracking
Error handling
Scheduled operations
Delta updates

Bulk Operations Documentation

Webhooks

Subscribe to real-time events:

POST /api/v3/webhooks
GET /api/v3/webhooks
DELETE /api/v3/webhooks/{id}

Available event topics:

product/created
product/updated
order/created
order/updated
order/fulfilled
customer/created
customer/updated
inventory/updated

Webhook features:

Custom HTTP headers
Signature verification
Retry configuration
Event filtering
Rate limiting
Logging and debugging

Webhooks Documentation

Storefront API

Public-facing API for custom shopping experiences:

GET /api/storefront/v3/products
POST /api/storefront/v3/cart

Storefront capabilities:

Product discovery
Cart management
Checkout flow
Customer authentication
Order status
Wishlists

Storefront API Documentation

API Implementation Examples

Common Integration Scenarios

Step-by-step guides for popular use cases:

Code Examples

Sample implementations in popular languages:

Node.js

const axios = require('axios');

async function getProducts() {
  try {
    const response = await axios.get('https://api.store.icu/v3/products', {
      headers: {
        'Authorization': `Bearer ${process.env.API_TOKEN}`,
        'Content-Type': 'application/json'
      }
    });
    return response.data;
  } catch (error) {
    console.error('API Error:', error.response.data);
    throw error;
  }
}

PHP

<?php
function getProducts() {
  $curl = curl_init();
  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.store.icu/v3/products",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer " . $_ENV['API_TOKEN'],
      "Content-Type: application/json"
    ]
  ]);
  $response = curl_exec($curl);
  curl_close($curl);
  return json_decode($response, true);
}
?>

Python

import requests

def get_products():
    headers = {
        'Authorization': f'Bearer {os.environ.get("API_TOKEN")}',
        'Content-Type': 'application/json'
    }
    response = requests.get('https://api.store.icu/v3/products', headers=headers)
    response.raise_for_status()
    return response.json()

More code examples are available in our GitHub repository.

API Development Tools

SDKs and Libraries

Official client libraries:

Language	Repository	Installation
JavaScript	GitHub	`npm install storeicu-sdk`
PHP	GitHub	`composer require storeicu/sdk`
Python	GitHub	`pip install storeicu`
Ruby	GitHub	`gem install storeicu`
Java	GitHub	Maven/Gradle
C#	GitHub	NuGet

Testing Tools

Resources for API development:

API Playground: Interactive API explorer
Postman Collection: Ready-to-use request collection
Mock API Server: For development without live data
Webhook Tester: Test webhook deliveries
Status Dashboard: API service status monitoring

API Best Practices

Performance Optimization

Techniques to improve API efficiency:

Use GraphQL for complex data requirements
Implement resource expansion to reduce requests
Employ sparse fieldsets to minimize payload size
Utilize pagination for large collections
Implement caching where appropriate
Schedule bulk operations during off-peak hours

Security Guidelines

Protect your API implementation:

Store credentials securely
Rotate access tokens regularly
Request only necessary OAuth scopes
Validate webhook signatures
Implement transport layer security
Audit API access regularly
Follow the principle of least privilege

Error Handling

Best practices for robust applications:

Implement exponential backoff for rate limit errors
Add proper exception handling
Log API responses for troubleshooting
Design for API unavailability
Add monitoring and alerting
Understand error response formats

Example error response:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested product could not be found",
    "details": {
      "resource": "product",
      "id": "123456"
    },
    "request_id": "f8dbf208-3a5d-4097-8b88-98e898c6d9d1"
  }
}

Partner-Specific API Features

White-Labeling

Customize the API experience:

Custom API domain (api.yourcompany.com)
Branded documentation
Custom rate limits
Partner-specific endpoints
Dedicated support contacts

Available to Gold and Platinum partners.

API Analytics

Monitoring tools for partners:

Usage dashboards
Client-specific metrics
Performance analytics
Error rate monitoring
Feature adoption tracking
Quota management

Access these in the Partner API Dashboard.

API Support

Troubleshooting Resources

When you encounter issues:

API Status Page: Check for service disruptions
Error Code Reference: Detailed explanation of error codes
Troubleshooting Guide: Common issues and solutions
Partner Forum: Community assistance
API Changelog: Recent updates and breaking changes

Support Channels

Get help with your integration:

Email: api-support@store.icu
Partner Portal: Submit technical tickets
Developer Community: Join discussions
Office Hours: Weekly technical Q&A sessions
Integration Review: Schedule a code review

Advanced API Topics

Multi-Store Management

For partners managing multiple client stores:

Organization-level API access
Multi-store data aggregation
Cross-store operations
Permission management
Tenant isolation

Multi-Store API Documentation

Localization

Internationalization features:

Multi-currency support
Language-specific content
Regional tax handling
International address formatting
Timezone-aware operations
Translation management

Localization API Documentation

Extending the Platform

Build on top of Store.icu:

Custom field definitions
Metadata storage
Workflow customization
Event-driven programming
Third-party service connectors
Custom checkout flows

Platform Extension Documentation

API Certification Program

Become a certified API integration partner:

Complete the API fundamentals course
Build a certification integration project
Pass the technical assessment
Submit integration for review
Receive API Specialist certification

API Certification Details

Resources for Clients

Materials to share with merchants:

Upcoming API Features

Stay informed about our API roadmap:

Enhanced B2B capabilities (Q3 2025)
Advanced personalization API (Q4 2025)
Expanded analytics endpoints (Q1 2026)
Machine learning product recommendations (Q2 2026)
Real-time inventory synchronization enhancements (Q3 2025)

For detailed roadmap information, visit the API Roadmap.

API Documentation

Overview of Store.icu API Platform​

API Access​

Authentication​

Access Scopes​

Rate Limits​

API Versions​

Core API Resources​

Products​

Orders​

Customers​

Inventory​

Cart & Checkout​

Content​

Advanced API Features​

GraphQL API​

Bulk Operations​

Webhooks​

Storefront API​

API Implementation Examples​

Common Integration Scenarios​

Code Examples​

Node.js​

PHP​

Python​

API Development Tools​

SDKs and Libraries​

Testing Tools​

API Best Practices​

Performance Optimization​

Security Guidelines​

Error Handling​

Partner-Specific API Features​

White-Labeling​

API Analytics​

API Support​

Troubleshooting Resources​

Support Channels​

Advanced API Topics​

Multi-Store Management​

Localization​

Extending the Platform​

API Certification Program​

Resources for Clients​

Upcoming API Features​