跳转到主要内容
版本：最新

API 概览

Shoplazza 提供全面的 API 来帮助你构建强大的应用和集成。

API 类型​

REST API​

REST API 通过简单的 HTTP 请求提供对所有 Shoplazza 资源的访问。

基础 URL: https://{shop-domain}/admin/api/{version}/

支持的版本:

  • 2024-01 (最新，推荐)
  • 2023-07
  • 2023-01

示例请求:

curl -X GET "https://your-shop.shoplazza.com/admin/api/2024-01/products.json" \
  -H "X-Shoplazza-Access-Token: your_access_token"

GraphQL API​

GraphQL API 提供了一种更灵活的方式，通过单个请求查询数据。

Endpoint: https://{shop-domain}/admin/api/{version}/graphql.json

Example Query:

query {
  products(first: 10) {
    edges {
      node {
        id
        title
        variants(first: 5) {
          edges {
            node {
              id
              price
              sku
            }
          }
        }
      }
    }
  }
}

Available Resources​

Product Management​

  • Products: Create, read, update, and delete products
  • Variants: Manage product variants
  • Collections: Organize products into collections
  • Inventory: Track and manage inventory levels

Order Management​

  • Orders: Access and manage customer orders
  • Fulfillments: Create and track order fulfillments
  • Transactions: View payment transactions
  • Refunds: Process order refunds

Customer Management​

  • Customers: Manage customer data
  • Customer Groups: Organize customers into segments
  • Customer Addresses: Manage shipping addresses

Store Configuration​

  • Shop: Access store settings and configuration
  • Settings: Manage store preferences
  • Webhooks: Set up real-time notifications
  • Metafields: Add custom data to resources

Authentication​

OAuth 2.0 (Public Apps)​

Public apps use OAuth 2.0 for authentication:

  1. Redirect merchant to authorization URL
  2. Merchant grants permissions
  3. Exchange authorization code for access token
  4. Use access token for API requests

API Tokens (Private Apps)​

Private apps use static API tokens:

headers: {
  'X-Shoplazza-Access-Token': 'your_access_token'
}

Rate Limits​

To ensure platform stability, API requests are rate limited:

  • REST API: 2 requests per second (bucket-based)
  • GraphQL API: Cost-based (1000 points per second)

Rate Limit Headers:

X-Shoplazza-Shop-Api-Call-Limit: 32/40

Webhooks​

Webhooks allow you to receive real-time notifications:

// Example webhook payload for orders/create
{
  "id": 123456789,
  "email": "customer@example.com",
  "total_price": "199.99",
  "line_items": [...],
  "created_at": "2024-01-15T10:30:00Z"
}

Available Webhooks:

  • orders/create, orders/updated, orders/cancelled
  • products/create, products/update, products/delete
  • customers/create, customers/update, customers/delete
  • fulfillments/create, fulfillments/update

Error Handling​

API errors return standard HTTP status codes:

  • 400: Bad Request - Invalid parameters
  • 401: Unauthorized - Invalid or missing credentials
  • 403: Forbidden - Insufficient permissions
  • 404: Not Found - Resource doesn't exist
  • 429: Too Many Requests - Rate limit exceeded
  • 500: Internal Server Error - Server-side issue

Error Response:

{
  "errors": {
    "title": ["can't be blank"]
  }
}

API Versioning​

Shoplazza APIs are versioned to ensure stability:

  • New versions are released quarterly
  • Each version is supported for 12 months
  • Deprecated endpoints receive 6 months notice

Best Practices​

  1. Use API Versioning: Always specify the API version
  2. Handle Rate Limits: Implement exponential backoff
  3. Validate Webhooks: Verify webhook signatures
  4. Cache When Possible: Reduce unnecessary API calls
  5. Use Bulk Operations: Process multiple items efficiently
  6. Error Handling: Implement robust error handling

SDK and Libraries​

Official SDKs available:

  • Node.js
  • Python
  • Ruby
  • PHP

Next Steps​