Shopify Rust Client

A Rust client library for interacting with the Shopify Admin API. Currently focused on order management with plans to support all Shopify Admin APIs (REST and GraphQL).

Features

Current Support

🔍 Order Retrieval: Fetch orders by ID or order name
✏️ Order Updates: Update order properties (e.g., tags)
🪝 Webhook Support: Parse customer and shop compliance webhooks
📦 Type-Safe: Strongly typed models for Shopify API responses
🚀 Async/Await: Built on reqwest for asynchronous HTTP requests
🔐 Secure: Token-based authentication support

Roadmap

🚧 Full Admin REST API: Support for Products, Customers, Inventory, Fulfillments, and more
🚧 GraphQL Admin API: Complete GraphQL API support with query builder
🚧 Additional Webhooks: Support for more webhook topics beyond compliance
🚧 Rate Limiting: Built-in request throttling and retry logic

Installation

Add this to your Cargo.toml:

[dependencies]
shopify-client = "0.1.0"

Or install directly:

cargo add shopify-client

Public API

The library exposes three main modules for public use:

ShopifyClient - Main client for making API calls
types - All type definitions organized by resource (e.g., types::order)
webhooks - Webhook parsing utilities and types

use shopify_client::ShopifyClient;           // Main client
use shopify_client::types::order::*;         // Order types
use shopify_client::webhooks::*;             // Webhook utilities

Usage

Initialize the Client

use shopify_client::ShopifyClient;

let client = ShopifyClient::new(
    "https://your-shop.myshopify.com".to_string(),
    "your-access-token".to_string(),
    None, // Optional API version, defaults to "2024-07"
);

Get Order by ID

use shopify_client::ShopifyClient;

#[tokio::main]
async fn main() {
    let client = ShopifyClient::new(
        "https://your-shop.myshopify.com".to_string(),
        "your-access-token".to_string(),
        None,
    );

    let order_id = "1234567890".to_string();

    match client.order.get_with_id(&order_id).await {
        Ok(response) => {
            println!("Order: {:?}", response.order);
        }
        Err(e) => {
            eprintln!("Error: {:?}", e);
        }
    }
}

Get Order by Name

use shopify_client::ShopifyClient;

#[tokio::main]
async fn main() {
    let client = ShopifyClient::new(
        "https://your-shop.myshopify.com".to_string(),
        "your-access-token".to_string(),
        None,
    );

    let order_name = "1001".to_string(); // Without the # prefix

    match client.order.get_with_name(&order_name).await {
        Ok(response) => {
            println!("Orders found: {}", response.orders.len());
            for order in response.orders {
                println!("Order {}: {}", order.name, order.id);
            }
        }
        Err(e) => {
            eprintln!("Error: {:?}", e);
        }
    }
}

Update Order (Patch)

use shopify_client::ShopifyClient;
use shopify_client::types::order::{PatchOrderRequest, PatchOrder};

#[tokio::main]
async fn main() {
    let client = ShopifyClient::new(
        "https://your-shop.myshopify.com".to_string(),
        "your-access-token".to_string(),
        None,
    );

    let order_id = "1234567890".to_string();

    let patch_request = PatchOrderRequest {
        order: PatchOrder {
            tags: vec!["processed".to_string(), "priority".to_string()],
        },
    };

    match client.order.patch(&order_id, &patch_request).await {
        Ok(response) => {
            println!("Order updated: {:?}", response.order);
        }
        Err(e) => {
            eprintln!("Error: {:?}", e);
        }
    }
}

Parse Webhooks

use shopify_client::webhooks::{parse_webhook_with_header, WebhookPayload};

fn handle_webhook(topic_header: &str, payload: &str) {
    match parse_webhook_with_header(topic_header, payload) {
        Ok(WebhookPayload::CustomersDataRequest(data)) => {
            println!("Customer data request for shop: {}", data.shop_domain);
            println!("Customer: {:?}", data.customer);
            println!("Orders requested: {:?}", data.orders_requested);
        }
        Ok(WebhookPayload::CustomersRedact(data)) => {
            println!("Customer redact request for shop: {}", data.shop_domain);
            println!("Customer to redact: {:?}", data.customer);
            println!("Orders to redact: {:?}", data.orders_to_redact);
        }
        Ok(WebhookPayload::ShopRedact(data)) => {
            println!("Shop redact request for shop: {}", data.shop_domain);
            println!("Shop ID: {}", data.shop_id);
        }
        Err(e) => {
            eprintln!("Failed to parse webhook: {:?}", e);
        }
    }
}

Project Structure

The library is organized into a modular structure for easy extensibility:

src/
├── lib.rs                  # Main client entry point and exports
├── types/                  # Public type definitions
│   ├── mod.rs             # Type module exports
│   └── order.rs           # Order-related types
├── webhooks/              # Public webhook parsing module
│   ├── mod.rs             # Webhook parsing functions
│   └── types.rs           # Webhook payload types
├── common/                # Internal shared utilities (private)
│   ├── mod.rs
│   ├── types.rs           # Common types (APIError, ErrorResp)
│   └── utils.rs           # Utility functions
└── services/              # Internal API services (private)
    └── order/             # Order service implementation
        ├── mod.rs         # Order struct with public methods
        └── remote.rs      # Internal API implementation

Design Philosophy

Client-Based: Initialize a ShopifyClient once and access services through it
Clean Public API: Three public modules - ShopifyClient, types, and webhooks
Encapsulation: All internal implementation (common, services) is private
Service-Oriented: Each API resource (orders, products, etc.) is its own service module
Clear Separation: Services for outgoing API calls, webhooks for incoming data parsing
Type Safety: All API responses are strongly typed with comprehensive models

Data Models

The library provides strongly-typed models organized by resource:

Order Types (`types::order`)

Order: Complete order information including customer, line items, fulfillments, pricing, and timestamps
Customer: Customer details (ID, email, phone, name, addresses)
LineItem: Product line items with quantities, prices, properties, and fulfillment status
OrderFulfillment: Fulfillment tracking with tracking numbers, URLs, and shipment status
Address: Billing and shipping address information
PriceSet: Multi-currency pricing with shop and presentment money
Property: Custom line item properties
PatchOrderRequest / PatchOrder: Request types for updating orders

Webhook Types (`webhooks::types`)

CustomersDataRequestPayload: Customer data request webhook payload
CustomersRedactPayload: Customer redaction webhook payload
ShopRedactPayload: Shop redaction webhook payload
WebhookPayload: Enum containing all webhook payload types
WebhookParseError: Error type for webhook parsing failures
WebhookCustomer: Customer information in webhook payloads

Error Handling

The library uses a custom APIError enum for comprehensive error handling:

pub enum APIError {
    ServerError { errors: String },
    FailedToParse,
    NetworkError,
}

Errors are returned through Result<T, APIError> for easy error propagation and handling.

Authentication

This client requires a Shopify Admin API access token. You can obtain one by:

Creating a custom app in your Shopify admin panel
Generating an Admin API access token
Granting the necessary permissions (e.g., read_orders, write_orders)

API Version

Currently uses Shopify Admin API version 2024-07.

Requirements

Rust 1.56 or later (2021 edition)
Dependencies:
- reqwest (with JSON support)
- serde (with derive feature)
- serde_json

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under your preferred license.

Disclaimer

This is an unofficial Shopify client library. For official SDKs and documentation, visit Shopify's Developer Documentation.

shopify-client 0.3.0