Craft Commerce Headless SDK Documentation Index

This SDK is designed to simplify integration with Craft Commerce, offering specialized modules for users, carts, payments, subscriptions, and more. Whether you're building a headless e-commerce application or enhancing an existing Craft Commerce setup, this guide will help you navigate and implement the SDK effectively.

Note: Craft Commerce version 4 or higher is required for compatibility with this SDK.

Table of Contents

1. Demo and Local Testing
2. Craft CMS Configuration Guide
3. Package Installation
4. Client Module
5. Users Module
6. Cart Module
7. Payment Sources Module
8. Payment Module
9. Subscriptions Module
10. Suggestions for Craft CMS Improvements

Demo and Local Testing

You can see a working demo of the SDK at this link:
https://craft-commerce-headless-sdk.netlify.app/

If you want to test the SDK locally, follow these steps:

1. Clone the repository.
2. Navigate to the demo folder.
3. Run the following commands:

   npm install
   npm run dev

   This will start the demo locally. Before using the SDK, ensure that Craft CMS and Craft Commerce are correctly configured for headless usage. Follow the Craft CMS Configuration Guide for essential setup steps, including CORS configuration and cookie settings.

Craft CMS Configuration Guide

This section provides details on configuring Craft CMS for headless usage, including CORS setup and other necessary settings.

• Configuration

Package Installation

To use the Craft Commerce Headless SDK in your project, you can install it using your preferred package manager. Here are the commands for different managers:

npm

npm install craft-commerce-headless-sdk

pnpm

pnpm add craft-commerce-headless-sdk

yarn

yarn add craft-commerce-headless-sdk

After installation, you can import the SDK in your code:

import { craftCommerceHeadlessSdk } from 'craft-commerce-headless-sdk';

Client Module

The base module for API communication, handling HTTP requests with post and get methods.

• Installation
• Methods
  • post
  • get
• Examples

Users Module

This module handles user account creation, profile management, and address handling. It simplifies operations like login, password resets, and managing user-related data, all essential for e-commerce platforms.

• Installation
• Methods
  • loginUser
  • saveUser
  • uploadUserPhoto
  • sendPasswordResetEmail
  • setPassword
  • saveAddress
  • deleteAddress
  • getSessionInfo
• Examples

Cart Module

Manage shopping cart actions, including retrieval, updates, and checkout operations. This module supports typical e-commerce workflows in Craft Commerce.

• Installation
• Methods
  • completeCart
  • getCart
  • loadCart
  • forgetCart
  • updateCart
• Examples

Payment Sources Module

Create, manage, and assign payment methods to user accounts. This module supports common payment operations like adding or removing payment sources, tailored for Craft Commerce.

• Installation
• Methods
  • addPaymentSource
  • setPrimaryPaymentSource
  • deletePaymentSource
• Examples

Payment Module

Handle payments, including support for 3D Secure and other gateway integrations. This module streamlines the process of initiating and completing payments in Craft Commerce.

• Installation
• Methods
  • pay
  • completePayment
• Examples

Subscriptions Module

Manage subscriptions, including plan creation, cancellations, switching, and reactivation. This module simplifies recurring payment setups in Craft Commerce.

• Installation
• Methods
  • subscribe
  • cancel
  • switchPlan
  • reactivate
• Examples

Suggestions for Craft CMS Improvements

While this SDK provides extensive functionality, there are a few additional features that would greatly enhance the integration experience if included directly in Craft CMS or Craft Commerce:

• Include Available Payment Gateways in the Cart: Similar to how shipping methods are returned, having payment gateways listed directly in the cart data would streamline the checkout process and improve integration ease.

• Return User-Associated Addresses: Adding a feature to retrieve addresses associated with a user, similar to the actions/users/session-info method for session data, would simplify managing user information in headless implementations.