​
Development Guide for the StateSet Platform

​
Table of Contents

  1. Overview
  2. Prerequisites
  3. Step-by-Step Setup
  4. Integrating the SDK in Your Application
  5. Best Practices
  6. Additional Resources
  7. Support

​
Overview

The StateSet Platform streamlines e-commerce operations—particularly returns—by providing powerful tools and APIs. This guide will walk you through setting up a development environment, integrating the StateSet Node SDK, and fetching data (such as returns) directly from the StateSet API.

​
Prerequisites

Before getting started, ensure you have the following:

  • Node.js: Version 18.10.0 or higher.
  • StateSet Cloud Account: Sign up at StateSet Cloud.

​
Step-by-Step Setup

​
Install the StateSet Node SDK

From your project root directory, run:

npm install stateset-node

This command installs the official StateSet Node SDK, enabling you to interact with the StateSet API from your Node.js application.

​
Create a StateSet Cloud Project

  1. Sign Up or Log In: Go to StateSet Cloud and either sign up for a new account or log in to your existing one.
  2. Create a Project: After logging in, follow the on-screen prompts to create a new project. Your project will serve as the workspace for all StateSet operations and integrations.

​
Generate an API Key

  1. Navigate to API Settings: In your StateSet Cloud project dashboard, locate the API section.
  2. Create a New API Key: Click on “Create API Key” and follow the instructions.
  3. Store Your Key Safely: Copy the generated API key and store it in a secure location. You’ll need it to authenticate API requests.

Note: Do not commit your API key to source control. Instead, store it as an environment variable (e.g., STATESET_API_KEY) in a .env file or your deployment environment’s secret manager.

​
Integrating the SDK in Your Application

The following example demonstrates how to retrieve a list of returns from the StateSet API using Next.js and the StateSet Node SDK. Adjust this code to fit your preferred framework or architecture.

import { NextRequest, NextResponse } from "next/server";
import Stateset from 'stateset-node';

export const config = {
  runtime: 'edge', // Using edge runtime for faster responses
};

export default async function handler(req: NextRequest) {
  try {
    // Retrieve API key from environment variables
    const apiKey = process.env.STATESET_API_KEY;
    if (!apiKey) {
      throw new Error('STATESET_API_KEY environment variable is not set.');
    }

    // Initialize the StateSet client
    const stateset = new Stateset({ apiKey });

    // Fetch returns data
    const response = await stateset.returns.list();
    const { returns } = response;

    return NextResponse.json({ returns });
  } catch (error) {
    console.error('Error fetching returns:', error);
    const errorMessage = (error instanceof Error) ? error.message : 'An unknown error occurred';
    return NextResponse.json({ error: errorMessage }, { status: 500 });
  }
}

Key Takeaways:

  • API Key Setup: Use process.env.STATESET_API_KEY to keep sensitive information out of your codebase.
  • Error Handling: Catch and log errors for easier debugging.
  • JSON Response: Return JSON objects for easy integration with frontend clients or other services.

​
Best Practices

  1. Use Environment Variables:
    Store credentials like the API key in environment variables to enhance security and flexibility.

  2. Robust Error Handling:
    Implement comprehensive error handling. Always validate that the API key and other required configuration parameters are present and handle API failures gracefully.

  3. Rate Limiting & Caching:
    If the StateSet API imposes rate limits, implement exponential backoff or caching strategies. Caching responses when possible can reduce both latency and API call volume.

  4. Data Validation & Sanitization:
    Validate and sanitize data returned by the API before using it within your application or database operations to maintain data integrity and security.

  5. Logging & Monitoring:
    Maintain logs and use monitoring tools to track usage, performance metrics, and error rates. These insights help with scaling and early detection of issues.

​
Additional Resources

​
Support

For questions, issues, or assistance with the StateSet Node SDK:

Our support team and developer community are ready to help you succeed with StateSet.

You’re now ready to build, integrate, and optimize your commerce operations with the StateSet Platform.

Introduction to StateSetService-as-a-Software