xclade Commerce API

Overview

The xclade REST API is a resource-oriented standard interface for interacting with the core commerce engine. Built on Medusa v2 primitives, it provides predictable, Type-Safe endpoints for managing your storefront data and checkout flows.

API Design

• Resource Oriented: URLs represent resources (e.g., /store/products, /store/carts).
• Standard Methods: Uses standard HTTP verbs (GET, POST, DELETE).
• JSON Envelopes: All responses are wrapped in a standardized JSON structure.
• Typed Responses: Strict adherence to the OpenAPI specification ensures client generation reliability.

Base URL

All API requests are routed through your tenant-specific endpoint. The API is divided into two primary namespaces:

Example Base URL:

https://{your-tenant}.api.myxclade.com/store

Authentication

The API supports multiple authentication strategies depending on the context:

1. Publishable API Keys (Storefront)

For public storefront access, include your Publishable Key in the header. This scopes the request to your specific sales channel.

x-publishable-api-key: pk_01H...

2. Bearer Tokens (Customer/Admin)

For authenticated operations, standard JWT Bearer tokens are used.

Authorization: Bearer {jwt_token}

3. Session Cookies

For web-based clients, connect.sid cookies enable persistent sessions automatically.

API Architecture

The API is organized into logical resource groups, each handling specific business domains:

Core Resources

• Auth: Authentication, session management, and token refresh
• Customers: Customer accounts, profiles, and address management

Commerce Resources

• Products: Product catalog, variants, and inventory
• Collections: Curated product groupings
• Product Categories: Hierarchical product organization
• Carts: Shopping cart lifecycle and line item management
• Orders: Order placement, tracking, and history

Payment & Fulfillment

• Payment Collections: Payment session orchestration
• Payment Providers: Available payment method configuration
• Shipping Options: Delivery method selection and calculation

Supporting Resources

• Regions: Geographic market configuration
• Currencies: Multi-currency pricing support
• Returns: Return request processing
• Gift Cards: Gift card issuance and redemption
• Store Credit: Customer credit balance management

Getting Started

Navigate through the API sections using the sidebar menu. Each endpoint provides:

• Detailed parameter specifications
• Request and response schemas
• Code examples in multiple programming languages
• Authentication requirements
• Error response formats

Rate Limiting

API requests are subject to rate limiting to ensure service stability. Rate limit information is included in response headers. Contact support for enterprise rate limit configurations.

Support

For technical assistance, integration guidance, or to report issues, please visit xclade.com or contact your account representative.