Overview

Key terminology:

• Developer/Partner: You, the third party developing the Add-on
• Operator: Self-storage facility operators using your Add-on on the Storeganise platform in conjunction with your software
• Customer: The operator's customers

How Add-ons work:

• Your Add-on receives webhook events from Storeganise when specific actions occur (e.g., move-ins, payments, bookings)
• Your server processes these events and integrates with your system
• You can fetch additional data from the Storeganise API as needed
• Add-ons include webtasks that define how the Add-on integrates with Storeganise (such as creating custom fields when installed)
• Operators see your Add-on description, setup instructions, and custom fields for entering configuration like API key

What operators interact with

• Add-on description: Explains what your Add-on does and its benefits
• Setup instructions: Step-by-step guide for configuring the integration
• Custom fields: Form fields you define; these can be used for collecting credentials needed to access your service, or for options to configure how the Add-on works for that particular operator.

What you build (invisible to operators):

• Webhook endpoints that receive and process events
• Webtasks that run during Add-on installation and management
• API integration logic
• Error handling

Before you start

What you'll need:

• Technical expertise in web development and API integration
• Understanding of webhook-based architectures
• Ability to host and maintain server-side code
• Time commitment for development, testing, and documentation

What Storeganise provides:

• Dedicated testing environment
• Starter code packages
• Technical documentation and API access
• Assigned integration partner for guidance
• Production deployment support

The Add-on development process

Phase 1: Initial contact and setup

• Brief description of your integration, including your industry / category:
• Target use cases or customer needs
• How Storeganise's customers will benefit from this integration

What happens next:

• Storeganise assigns you an integration partner who becomes your primary technical contact
• You receive access to a dedicated development instance: [youraddonnname].storeganise.dev    
• When you first log in, you'll accept the Terms of Service and Privacy Agreement (no separate legal process required)

Reference Add-on installation

• Well-written Add-on descriptions
• Clear, step-by-step setup instructions for operators
• Professional presentation of custom fields for configuration

Phase 2: Development resources

Available starters:

• Payment/Billing Add-on(addon-custom-billing-starter)
  • For payment gateways, billing integrations
  • Includes: OAuth flows, payment method management, billing event handlers
• Access Control Add-on(addon-access-control-starter)
  • For lock systems, access management integrations
  • Includes: Move-in/move-out handlers, permission management, webtask examples

Starter package contents:

• Basic server setup and webhook handler structure
• Event mapping examples
• Sample webtasks for configuration
• Environment variable templates (.env.example    )
• File structure documentation

Documentation access:

• API documentation: Available at [youraddonnname].storeganise.dev/api/docs    
• API best practices
• API FAQs
• Webhook events reference
• Add-on framework guide: This document

Phase 3: Development and testing

Your responsibilities:

• Build the Add-on using the starter package as your foundation
• Test all functionality in your development instance
• Write a clear Add-on description and setup instructions for operators
• Create customer-facing documentation (helpdoc) for operators. This will be published on the Storeganise Helpdoc site.
• Prepare a demo showing your working Add-on

Stay in touch

Phase 4: Production readiness certification

Certification checklist

• Working demo showing complete flow (operator installation → operator configuration → usage)
• Add-on description with clear value proposition, features, and limitations (what operators will see)
• Simple Add-on instructions, or a link to the helpdoc.
• Operator-facing helpdoc covering installation, configuration, and troubleshooting
• Partner page information (company overview, logo, contact details, branding assets). Your partner page will be published on our website.

• All webhook events handled correctly
• Comprehensive error handling (network failures, API errors)
• Multi-site support tested (if applicable)
• Webhook responses within 30-second timeout requirement
• Nominated email address for support escalation
• Nominated email address for leads sourced through the Storeganise website

Phase 5: Production deployment

After approval

• Storeganise coordinates production deployment with the internal development team
• Production environment is configured and prepared
• Your Add-on is deployed to production
• You're notified when deployment is complete.
• Check-in scheduled after one week of production use

Phase 6: Marketplace launch

• Your Add-on appears in the Storeganise Add-on marketplace
• Partner page is added to the Storeganise website
• Changelog entry announces your new Add-on
• Customer communications highlight the integration

• Bug reports and updates follow established processes
• Your integration partner remains your primary contact
• Customer queries are forwarded to your nominated support address

Technical implementation

Webhook event structure

// Get the event data from the request body
const {
  type, // The event type, e.g. `user.created`, `job.unit_moveIn.completed`
  data = {}, // An object of event data; contains IDs depending on the event type, e.g. userId, jobId
  apiUrl, // The base URL of Storeganise API
  addonId, // The ID of the addon which called this webhook; the addon contains the business-specific customFields/settings
} = req.body;

• type: The event that triggered the webhook (see Webhook events reference for complete list)
• data: Object containing relevant IDs for the event (userId, jobId, invoiceId, etc.)
• apiUrl: Base URL for making API calls back to Storeganise to fetch additional data
• addonId: Your Add-on's unique ID, used to retrieve configuration settings

Add-on states

• Storeganise will not call the Add-on events/webhooks
• The external system cannot access the Storeganise account

• Storeganise will not call the Add-on events/webhooks
• The external system can access the Storeganise account
• This is the default state when an Add-on has just been installed

• Storeganise will call the Add-on events/webhooks
• The external system can access the Storeganise account

Fetching data from the Storeganise API

function StoreganiseApi({ apiUrl, addonId }) {
  return function fetchSg(path, {
    method = 'GET',
    body,
  } = {}) {
    return fetch(`${apiUrl}${path}`, {
      method,
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Addon ${addonId}|${config.sgApiKey}`,
      },
      body: body && JSON.stringify(body),
    })
      .then(async response => {
        const data = await response.json().catch(() => ({}));
        if (!response.ok) {
          console.error(`Error calling ${method} ${apiUrl}${path}: ${response.status} ${response.statusText}`); 
          const err = Object.assign(new Error(), data.error);
          err.status = response.status;
          throw err;
        }
        return data;
      });
  }
}

Fetching Add-on details:

const fetchSg = StoreganiseApi(req.body);
const addon = await fetchSg(`/v1/admin/addons/${addonId}`);

Tracking Add-on installations across operators

Handling request data

const { unitRentalId } = data;
const rental = await fetchSg(`/v1/admin/unit-rentals/${unitRentalId}?include=unit,owner,customFields`);
// Now call your remote API using addon.customFields for the credentials, and rental data to sync

Conventions for access control Add-ons

• If unit.customFields.{prefix}_id     is set, it'll override unit.name     for the unit name to sync on the remote API
• If unit.customFields.{prefix}_id     is set to NONE, it skips synchronisation for this unit
• Use unit.customFields.{prefix}_overlocked     (Boolean custom field) for the overlocking status of the unit
• Use unit.customFields.{prefix}_accessCode     or unit.customFields.{prefix}_pinCode     or other relevant names for the access codes (String custom field) and generate this value randomly with enough digits (at least 6)
• Use unit.customFields.{prefix}_resync     (Boolean custom field) to action a resync for this unit

Your role at each stage

During development:

• Build and test the Add-on functionality
• Write all documentation (operator instructions, operator helpdoc)
• Communicate regularly with your integration partner
• Request help when you encounter technical challenges

Before production:

• Complete the certification checklist thoroughly
• Prepare a comprehensive demo
• Ensure all operator-facing documentation is clear and accurate
• Test edge cases and error scenarios

After launch:

• Monitor for issues reported by operators
• Respond to support escalations
• Plan and implement updates as needed
• Maintain ongoing relationship with Storeganise

Managing Add-on updates:

• Add-on descriptions
• Setup instructions
• Custom fields
• Webtasks
• Webhook configurations
• Server code

Best practices for success

• Review the reference Add-on (Xero) in your dev instance for quality standards
• Use the provided starter package rather than building from scratch
• Ask questions early rather than making assumptions

• Write instructions assuming operators have no prior knowledge of your system
• Include screenshots for complex configuration steps
• Provide troubleshooting guidance for common issues operators might face
• Test your documentation with someone unfamiliar with your Add-on

• Cover the complete operator experience, not just the happy path
• Test error scenarios (network failures, invalid data, API errors)
• Verify multi-site support if applicable (operators managing multiple facilities)
• Ensure webhook responses complete within 30 seconds

Common pitfalls to avoid

Technical issues

• Webhook responses that exceed 30-second timeout
• Insufficient error handling for API failures
• Rate limiting not properly implemented
• Not handling all relevant webhook events

Documentation issues

• Incomplete setup instructions causing operator confusion
• Assuming technical knowledge operators may not have
• Missing troubleshooting guidance for operator issues
• No screenshots for complex configuration steps

Process issues

• Rushing to production before comprehensive testing
• Incomplete certification checklist submissions
• Poor demo that doesn't show complete functionality
• Infrequent communication with integration partner

Quality standards

Your Add-on should

• Work reliably for all supported use cases
• Handle errors gracefully with clear feedback to operators
• Follow Storeganise UI and UX patterns
• Include professional, comprehensive documentation for operators
• Respond to webhooks within timeout limits
• Make efficient use of the Storeganise API (e.g. minimize the number of requests where possible)

Documentation should

• Use clear, jargon-free language
• Include step-by-step instructions with screenshots
• Explain configuration parameters
• Provide troubleshooting guidance
• Follow Storeganise helpdoc formatting standards

Technical requirements

Required capabilities

• Webhook endpoint that accepts POST requests with Storeganise event data
• OAuth flow implementation (for authentication with your service)
• Error handling and retry logic
• Multi-site support (if Add-on applies to multiple facilities)

Performance requirements

• Webhook responses must complete within 30 seconds
• Handle API rate limits appropriately
• Implement proper error recovery mechanisms

API integration

• Use the Storeganise API to fetch complete object data
• Authentication uses the format: Addon ${addonId}|${config.sgApiKey}    
• Handle API errors gracefully (4xx and 5xx responses)

Getting started