Warranty Workflow Guide

Last Updated: January 16, 2025

Introduction

Manages warranty claims through a multi-system integration involving Zendesk, ShipStation, and Stateset.

Zendesk is used to create and track customer support tickets.
Stateset orchestrates the workflow, including data normalization, AI-driven analysis, and record-keeping.
ShipStation automates order creation, shipping label generation, and delivery tracking.

This document aims to help you understand how data flows between these platforms, how to handle exceptions, and how to customize or troubleshoot the system.

High-Level Workflow

Customer Submits Warranty Claim
A customer contacts via a Zendesk support form or email, providing details and any attachments (e.g., product images).
Data Transferred to Stateset
Zendesk, via a webhook, sends the warranty ticket data to Stateset for processing.
Stateset Processes Data
- Normalization: Stateset consolidates the ticket data, customer information, and product details.
- Address Verification: An external service (Google Address Validation) verifies or corrects the shipping address.
- AI Analysis: The system uses OpenAI’s Vision API for brand/model identification, accessories detection, and issue code determination.
Order Creation in ShipStation
Stateset automatically creates a new replacement order in ShipStation with an RMA number. ShipStation returns a unique shipstation_order_id.
Warranty Record Management in Stateset
A new or updated “warranty” record is created in Stateset, storing all relevant info:
- RMA number
- Original order ID
- Product/issue details
- ShipStation order ID
- Customer details
- AI analysis outputs (defective item, issue code, brand)
Zendesk Ticket Updates
Stateset updates the Zendesk ticket with:
- A private note (internal)
- Custom fields (defective item, quantity, issue code)
- A customer-facing message
Fulfillment and Shipment
ShipStation processes the replacement order and generates shipment details. Communication continues via Zendesk if needed.

Detailed Process Steps

1. Warranty Claim Creation in Zendesk

The customer’s first step is to open a new ticket, either by:

Filling out a warranty form that leads to a Zendesk ticket.
Sending an email to support email, which is captured by Zendesk.

Key Fields in Zendesk Ticket:

Subject: General summary of the issue or complaint.
Description: Full text of the customer’s issue, often containing production codes or details about leaks, defects, etc.
Attachments: Photos or videos demonstrating the defect or product type.

2. Data Sent to Stateset via Webhook

Once the ticket is created in Zendesk:

A Webhook is triggered in Zendesk with the ticket data.
The Webhook targets a Stateset endpoint that begins the warranty workflow.

Zendesk Signature Validation ensures that the incoming request is authentic (see Appendix).

3. Data Processing in Stateset

Stateset receives the payload and extracts or normalizes relevant data into a standardized format:

Zendesk Ticket Data
- ticket_id
- order_id (if the customer has it)
- subject
- description
- image_description (analysis from attached images)
Customer Data
- customer_email, billing_email
- Name, address (street, city, state, zip, country)
- phone
Product Data
- product
- quantity
- volume
- color
- defective_product
- defective_quantity
- warranty_issue

4. Address Verification

Before creating an order, Stateset checks the customer’s address via an external service (Google Address Validation).

If verification is successful, the normalized address fields (verified_address_street, verified_address_city, etc.) are used.
If no verified address is found, the workflow reverts to the original address fields, but a note may be logged indicating a potential address mismatch.

5. ShipStation Order Creation

Using the verified address and product info, Stateset calls the ShipStation API to create a “Replacement Order” under a unique RMA number (W-<ticket_id>).

Unique RMA Check: The system queries ShipStation to see if an order with the same RMA already exists. If so, the new order creation is skipped to avoid duplicates.

If successful, ShipStation responds with a shipstation_order_id. This indicates the order is queued for fulfillment. If unsuccessful, Stateset logs an error and halts further processing.

6. Stateset Warranty Record Creation

Next, a Warranty Record is created (or updated) in Stateset’s database. This record includes:

Identifiers: id (Zendesk ticket number), order_id (original if known), rma (replacement order RMA)
ShipStation: shipstation_order_id
Timestamps: created_date
Status: E.g., NEW, or any subsequent statuses (like IN_PROGRESS, COMPLETED).
Customer: customerEmail, first_name, last_name, address fields
AI Output: defective_item, issue_code

7. AI-Driven Product and Issue Identification

To streamline data entry and reduce manual guesswork, the system may use OpenAI’s API to interpret:

Brand Determination
Model and Volume
Accessory Detection
Issue Codes

How it Works

The AI model looks at text descriptions and/or images.
Custom function calls in the Stateset backend parse out the brand, product SKU, or accessories needed.
If the AI is uncertain, it may default to unknown, prompting manual intervention.

8. Zendesk Ticket Updates

Finally, Stateset updates Zendesk to ensure full visibility for agents and customers:

Private Note (Internal)
- Lists newly created shipstation_order_id, determined SKU, product description, brand, quantity, defective item, and issue code.
Custom Fields
- Defective Item
- Quantity
- Issue Code
Customer-Facing Message
- Automatically generated courtesy message explaining the outcome.
- May provide next steps or tracking information.

Troubleshooting & Common Issues

Duplicate Order Error
- Symptoms: An order with the same RMA (“W-###”) already exists in ShipStation, causing the system to skip new creation.
- Fix: Check if the original ticket was re-sent, or if the same RMA was triggered more than once. Confirm with the customer if multiple orders are needed.
Address Verification Failure
- Symptoms: Address not found or partially matched.
- Fix: Confirm with the customer for correctness. Stateset may revert to the original address if the verification fails. Consider a manual review step if address validation is crucial.
AI Misidentification
- Symptoms: Brand or product incorrectly identified.
- Fix: Update the warranty record in Stateset and correct fields in Zendesk. Provide feedback to the AI logic (e.g., adjusting prompts or default logic).
ShipStation API Key Issues
- Symptoms: “Unauthorized” or “Invalid credentials” errors.
- Fix: Verify your ShipStation API credentials and test them in a known environment.
Webhook Not Triggering
- Symptoms: Data never arrives in Stateset after a new Zendesk ticket.
- Fix: Check Zendesk Admin -> Webhooks for correct endpoint and authentication. Ensure the signature validation code is up to date.
Order Creation Succeeds but No Zendesk Update
- Symptoms: A replacement order is created, but the Zendesk ticket lacks any new notes.
- Fix: Check the logs in Stateset for errors when calling Zendesk’s API. Validate Zendesk API tokens and ticket permissions.

Best Practices and Tips

Maintain Clean Data
Encourage customers to provide clear, detailed descriptions and pictures. The better the data, the more accurate AI-driven brand and accessory identification will be.
AI Confidence Levels
If your AI returns a “low” confidence level, consider adding a manual review step before shipping a replacement.
Address Verification
Use the verified address fields whenever available. This reduces shipping costs, undeliverable packages, and delays.
Use Custom Fields Wisely
Storing the defective item, quantity, and issue code in Zendesk custom fields simplifies reporting and search.
Monitor Logs
Regularly check Stateset logs to spot recurring issues, especially around shipping errors or AI misclassifications.
Stay Current with API Credentials
Regularly rotate or confirm credentials for Zendesk, ShipStation, and Google Address Validation to avoid unexpected downtimes.
Edge Cases
- No matching SKU: If the product can’t be matched, consider a manual process to clarify SKU and color.
- International Addresses: Ensure the country field is accurate. If your ShipStation store is restricted to the U.S. or certain countries, handle out-of-scope addresses carefully.

Appendix: Technical Implementation

Below are selected excerpts and explanations from the code that power this workflow. This section is intended for developers or administrators who need to dive deeper into how the system functions.

Zendesk Signature Validation

Before processing the incoming data, Stateset verifies that the webhook request actually came from Zendesk:

export async function isValidSignature(signature, body, timestamp) {
    let hmac = crypto.createHmac(SIGNING_SECRET_ALGORITHM, PROD_SIGNING_SECRET);
    let sig = hmac.update(timestamp + body).digest("base64");

    return (
        Buffer.compare(
            Buffer.from(signature),
            Buffer.from(sig.toString("base64"))
        ) === 0
    );
};

Purpose: Prevents spoofed or malicious requests.
Implementation: Compares the HMAC from Zendesk with one generated locally using shared secrets.

Logging Errors in Stateset

Whenever an error occurs (e.g., ShipStation creation failure), Stateset logs it:

export async function logError(rma, description) {
    console.log('logging_stateset_error');
    var log_id = uuidv4();
    const log = { "id": log_id, "rma": rma, "description": description, "rma_type": "warranty" };
    return "logged_stateset_error";
};

Usage: Simplifies debugging by capturing the RMA, error description, and timestamp.

Creating a Ship-To Address Record

Stateset can create a dedicated “Ship-To” address record in its own database:

mutation CreateShipToAddress($ship_to: ship_to_insert_input!) {
  insert_ship_to(objects: [$ship_to]) {
    returning {
      id
      first_name
      last_name
      street1
      city
      state
      country      
    }
  }
}

Best Practice: Keep shipping addresses versioned or historically traceable. If a package is returned or lost, having an immutable record helps in audits.

Checking for Duplicate Orders in ShipStation

Stateset queries ShipStation before attempting to create a new order:

const response = await fetch(`https://ssapi.shipstation.com/orders?orderNumber=${order_id}`, requestOptions);
if (response.ok) {
    // ...
    if (result && result.orders[0]) {
        return res.status(200).json({ status: "duplicate_request_order_and_invoice_already_processed" });
    }
}

Prevents sending multiple replacement orders for the same ticket, avoiding duplication and wasted shipping.

Creating ShipStation Orders

When no duplicates are found, Stateset issues a POST request to ShipStation:

export async function createShipStationOrder(rma, customer_email, ...) {
    // ...
    var shipstation_replacement_order = JSON.stringify({
        "orderNumber": rma,
        "orderKey": uuidv4(),
        // ...
        "items": [{
            "sku": sku,
            "name": name,
            "quantity": quantity
        }],
        // ...
        "billTo": { /* Customer billing info */ },
        "shipTo": { /* Verified shipping info */ },
        "internalNotes": "Ticket #" + ticket_id,
        "advancedOptions": {
            "warehouseId": 442610,
            "storeId": 242000
        }
    });
    // ...
}

Key Fields: orderNumber (the RMA), customerEmail, items (SKU, quantity).
storeId: Make sure this references the correct store in ShipStation for production.

Stateset Warranty Record: Create and Update

Create

mutation CreateWarrantyRecord($warranty: warranties_insert_input!) {
  insert_warranties(objects: [$warranty]) { returning { id ... } }
}

Update

mutation UpdateWarrantyRecord($id: String!, $defective_item: String!, $issue_code: String!) {
    update_warranties(where: {id: {_eq: $id}}, _set: {defective_item: $defective_item, issue_code: $issue_code}) {
      returning { id }
    }
}

Stored Fields: brand, model, defective item, issue code, RMA, email, creation dates, etc.

AI Function Calls Overview

Stateset uses specialized function calls to the OpenAI API. Examples include:

determineBrandAndModel
determineAccessories
determineHydraPakDefectiveItem

These calls parse user descriptions, images, or relevant ticket data to infer brand, model, or SKU. If it fails or returns an “unknown” result, a manual review might be required.

Updating Zendesk

Private Note:

export async function addPrivateNoteToHydraPakZendeskTicket(ticket_id, message) {
    // ...
    const zendeskPayload = JSON.stringify({
        "ticket": {
            "comment": { "body": message, "public": false }
        }
    });
    // ...
}

Custom Fields:

export async function updateHydraPakZendeskTicketCustomFields(ticket_id, defective_item, quantity, issue_code) {
    const ticketPayload = {
        "ticket": {
            "custom_fields": [
                { "id": 360031805313, "value": defective_item },
                { "id": 81571188, "value": quantity },
                { "id": 360006941114, "value": issue_code }
            ],
            "status": "open"
        }
    };
    // ...
}

These updates ensure that support agents can see all relevant details in one place.

Address Verification (Google Address Validation API)

Key Points:

Uses Google’s Address Validation to standardize addresses, checking for street, city, state, postal code, and country.
If a partially matched address is returned, the system logs it and sets a lower “confidence” rating.
On failure or missing fields, the workflow continues with the original address unless it’s critically incomplete.

export const verifyAddress = async (address) => {
    // ...
    const response = await fetch(`${baseUrl}?key=${apiKey}`, {
        method: 'POST',
        body: JSON.stringify({ ... })
    });
    // ...
}

Image Analysis for Brand, Model, and Accessories

For tickets with attachments:

Extract Attachment URLs from the Zendesk ticket description (or from an image_description field).
Analyze the images with the OpenAI endpoint.
Combine the textual analysis with any brand references in the subject or description.
Function Calls determine brand, accessories needed (e.g., “bite valve”), and whether to replace them.

async function analyzeBrandAndModelImages(imageUrls) {
  // ...
  // Sends each image URL to OpenAI
  // ...
}

This approach reduces manual identification efforts and speeds up the resolution time for customer claims.

Final Notes

Document Updates
This guide will be revised as the warranty workflow evolves. Keep track of any new fields, updated code references, or changes to APIs.
Contacts for Support
- Stateset: For issues with automation or AI function calls.
- Zendesk: For webhook setup or ticket configuration issues.
- ShipStation: For shipping label, order creation, or fulfillment issues.
- Support Admin: For internal changes to workflows, custom fields, or approvals.
Version Control
Always maintain version control of your Stateset environment and any custom scripts for quick rollbacks if an update introduces errors.

Thank You

We hope this expanded guide provides the clarity you need to successfully deploy, manage, and troubleshoot the Warranty Workflow. For any additional questions or contributions, please reach out to your system administrator or the Stateset support team.

Overview

Quickstart

StateSet One

StateSet Response

StateSet Commerce

Warranty Vision Workflow User Guide

Warranty Workflow Guide

Table of Contents

Introduction

High-Level Workflow

Detailed Process Steps

1. Warranty Claim Creation in Zendesk

2. Data Sent to Stateset via Webhook

3. Data Processing in Stateset

4. Address Verification

5. ShipStation Order Creation

6. Stateset Warranty Record Creation

7. AI-Driven Product and Issue Identification

8. Zendesk Ticket Updates

Troubleshooting & Common Issues

Best Practices and Tips

Appendix: Technical Implementation

Zendesk Signature Validation

Logging Errors in Stateset

Creating a Ship-To Address Record

Checking for Duplicate Orders in ShipStation

Creating ShipStation Orders

Stateset Warranty Record: Create and Update

AI Function Calls Overview

Updating Zendesk

Address Verification (Google Address Validation API)

Image Analysis for Brand, Model, and Accessories

Final Notes

Thank You

Overview

Quickstart

StateSet One

StateSet Response

StateSet Commerce

​Warranty Workflow Guide

​Table of Contents

​Introduction

​High-Level Workflow

​Detailed Process Steps

​1. Warranty Claim Creation in Zendesk

​2. Data Sent to Stateset via Webhook

​3. Data Processing in Stateset

​4. Address Verification

​5. ShipStation Order Creation

​6. Stateset Warranty Record Creation

​7. AI-Driven Product and Issue Identification

​8. Zendesk Ticket Updates

​Troubleshooting & Common Issues

​Best Practices and Tips

​Appendix: Technical Implementation

​Zendesk Signature Validation

​Logging Errors in Stateset

​Creating a Ship-To Address Record

​Checking for Duplicate Orders in ShipStation

​Creating ShipStation Orders

​Stateset Warranty Record: Create and Update

​AI Function Calls Overview

​Updating Zendesk

​Address Verification (Google Address Validation API)

​Image Analysis for Brand, Model, and Accessories

​Final Notes

​Thank You

Warranty Workflow Guide

Table of Contents

Introduction

High-Level Workflow

Detailed Process Steps

1. Warranty Claim Creation in Zendesk

2. Data Sent to Stateset via Webhook

3. Data Processing in Stateset

4. Address Verification

5. ShipStation Order Creation

6. Stateset Warranty Record Creation

7. AI-Driven Product and Issue Identification

8. Zendesk Ticket Updates

Troubleshooting & Common Issues

Best Practices and Tips

Appendix: Technical Implementation

Zendesk Signature Validation

Logging Errors in Stateset

Creating a Ship-To Address Record

Checking for Duplicate Orders in ShipStation

Creating ShipStation Orders

Stateset Warranty Record: Create and Update

AI Function Calls Overview

Updating Zendesk

Address Verification (Google Address Validation API)

Image Analysis for Brand, Model, and Accessories

Final Notes

Thank You