gigstack Connect API Guide

Access and manage resources across multiple teams within the same billing account. gigstack Connect enables authorized teams to work with resources from other teams seamlessly.

Overview

gigstack Connect is a powerful feature that allows teams with special permissions to access and manage resources (clients, invoices, payments, etc.) across multiple teams that share the same billing account. This is ideal for franchises, multi-entity businesses, service providers managing multiple client accounts, and marketplace platforms that need to split payments between platform and merchants.

Key Features

Multi-Team Access - Access resources across teams

Payment Splitting - Split marketplace payments between platform and merchants

Unified Management - Manage multiple teams from one API key

Billing Account Scope - Limited to teams in same billing account

Global Availability - Works on all 35+ API endpoints

Seamless Integration - Simple query parameter addition

Security Controls - Permission-based access

How It Works

Simply add the team query parameter to ANY endpoint to access another team's resources:

Requirements

gigstack Connect Enabled - Your API key's team must have gigstack Connect enabled

Shared Billing - Target team must share the same billing account

Team Exists - Target team must be valid and active

Proper Permissions - Your role must allow the requested action

Usage Examples

Accessing Clients Across Teams

Managing Invoices Across Teams

Processing Payments for Other Teams

Managing Services Across Teams

Team Settings Management

Marketplace Payment Splitting

gigstack Connect enables marketplace platforms to automatically split payments between the platform (master team) and merchants (connect teams). This feature is only available for master teams with marketplace-enabled billing accounts.

How Payment Splitting Works

When you register a payment with transfer_data, the system:

Validates that your team has marketplace permissions

Calculates the split based on the master percentage or custom_price

Creates two separate payments (master and connect)

Assigns clients according to your configuration

Returns both payment IDs and split details

Important: The team and livemode fields are automatically extracted from your authentication token - you don't need to send them.

Basic Marketplace Payment Split

Response:

{
    "message": "Split payment registered successfully",
    "data": {
        "split_reference": "split_abc123xyz",
        "master_payment_id": "payment_master_123",
        "connect_payment_id": "payment_connect_456",
        "master_amount": 174.0,
        "connect_amount": 986.0,
        "total_amount": 1160.0,
        "master_payment": {
            "id": "payment_master_123",
            "client": "client_1234567890",
            "amount": 174.0,
            "team": "team_master",
            "split_role": "master"
        },
        "connect_payment": {
            "id": "payment_connect_456",
            "client": "client_1234567890",
            "amount": 986.0,
            "team": "team_connect",
            "split_role": "connect"
        },
        "connect_team": null
    }
}

Creating a New Merchant Team

If the connect team doesn't exist (by tax ID), a new team will be created automatically:

Response with new team:

{
    "message": "Split payment registered successfully",
    "data": {
        "split_reference": "split_xyz789abc",
        "master_payment_id": "payment_master_789",
        "connect_payment_id": "payment_connect_012",
        "master_amount": 232.0,
        "connect_amount": 2088.0,
        "total_amount": 2320.0,
        "master_payment": {
            "id": "payment_master_789",
            "client": "client_1234567890",
            "amount": 232.0,
            "team": "team_master",
            "split_role": "master"
        },
        "connect_payment": {
            "id": "payment_connect_012",
            "client": "client_master_as_merchant",
            "amount": 2088.0,
            "team": "team_newmerch",
            "split_role": "connect"
        },
        "connect_team": {
            "id": "team_newmerch",
            "tax_id": "NEWMERCH800101ABC",
            "legal_name": "New Merchant SA de CV",
            "is_newly_created": true,
            "onboarding_url": "https://api.gigstack.com/onboarding/team_newmerch?token=xyz789"
        }
    }
}

Send the onboarding_url to the merchant to complete their account setup.

Custom Item Configuration for Connect Payments

Customize how items appear in the connect team's payment and invoices:

The connect payment will use the custom product key, unit key, description, and tax configuration instead of copying from the original items.

Fixed Commission Pricing

Instead of percentage-based splits, charge a fixed commission fee using custom_price:

Response with Fixed Commission:

{
    "message": "Split payment registered successfully",
    "data": {
        "split_reference": "split_xyz789",
        "master_payment_id": "payment_master_456",
        "connect_payment_id": "payment_connect_789",
        "master_amount": 2535.00,
        "connect_amount": 75.00,
        "total_amount": 2610.00,
        "used_custom_price": true
    }
}

Benefits of Fixed Pricing:

Predictable fees: Charge the same commission regardless of transaction size

Minimum guarantees: Ensure a minimum platform fee on small transactions

Tiered pricing: Implement different fixed fees for different service levels

Simple calculations: Merchants know exactly what they'll pay

Important Notes:

custom_price overrides the percentage calculation

Connect gets the exact custom_price amount

Master receives the remainder (total - custom_price)

The master percentage is ignored when using custom_price

Client Assignment Strategies

Strategy 1: Both payments to original client

{
    "transfer_data": {
        "master": 15,
        "connect": "ABC123456789",
        "master_to": "client",
        "connect_to": "client"
    }
}

Master payment: assigned to original client

Connect payment: assigned to original client

Use case: End customer pays both platform and merchant

Strategy 2: Master to client, Connect to master

{
    "transfer_data": {
        "master": 10,
        "connect": "ABC123456789",
        "master_to": "client",
        "connect_to": "master"
    }
}

Master payment: assigned to original client

Connect payment: master team becomes the client

Use case: Platform pays merchant on behalf of customer

Strategy 3: Master to connect, Connect to client

{
    "transfer_data": {
        "master": 5,
        "connect": "ABC123456789",
        "master_to": "connect",
        "connect_to": "client"
    }
}

Master payment: connect team becomes the client

Connect payment: assigned to original client

Use case: Merchant pays platform fee, customer pays merchant

Strategy 4: Both cross-assigned

{
    "transfer_data": {
        "master": 12,
        "connect": "ABC123456789",
        "master_to": "connect",
        "connect_to": "master"
    }
}

Master payment: connect team becomes the client

Connect payment: master team becomes the client

Use case: Complex inter-company transactions

Use Cases

1. Franchise Management

Manage multiple franchise locations from a central account:

2. Multi-Entity Corporation

Handle invoicing for different business entities:

3. Accounting Service Provider

Manage multiple client companies:

4. Consolidated Operations

Perform bulk operations across teams:

5. Marketplace Platform

Process payments with automatic splitting between platform and merchants:

Security and Permissions

Access Control

Only teams with gigstack Connect enabled can use this feature

Target teams must be in the same billing account

User permissions apply to cross-team operations

Audit logs track all cross-team actions

Permission Requirements

Action	Required Role
Read resources	Viewer or higher
Create resources	Member or higher
Update resources	Member or higher
Delete resources	Admin or higher
Manage team settings	Admin or higher

Error Responses

Not a Master Team

{
    "message": "Unauthorized",
    "error": "Unauthorized, not a master team"
}

Solution: Your team needs gigstack Connect enabled. Contact support.

Team Not Found

{
    "message": "Team not found",
    "error": "The specified team does not exist"
}

Solution: Verify the team ID is correct and active.

No Matched Teams

{
    "message": "Unauthorized",
    "error": "Unauthorized, no matched teams"
}

Solution: Target team must share the same billing account.

Insufficient Permissions

{
    "message": "Access denied",
    "error": "Your role does not allow this action on the target team"
}

Solution: Your user role must allow the requested action.

Best Practices

Cache Team IDs - Store frequently accessed team IDs

Batch Operations - Group operations by team for efficiency

Error Handling - Implement robust error handling for cross-team ops

Audit Trail - Log all cross-team operations

Permission Checks - Verify permissions before bulk operations

Rate Limiting - Be mindful of rate limits when accessing multiple teams

Consistent Naming - Use clear naming conventions for cross-team resources

Performance Considerations

Rate Limits

Standard rate limits apply per API key

Cross-team requests count toward your quota

Consider caching frequently accessed data

Optimization Tips

Complete Endpoint Support

gigstack Connect works with ALL endpoints:

Core Resources

Supported: /clients - Client management

Supported: /services - Service catalog

Supported: /invoices/income - Invoice creation and management

Supported: /payments - Payment processing

Supported: /teams - Team configuration

Supported: /users - User management

Additional Operations

Supported: /clients/validate/{id} - Validate client fiscal info

Supported: /clients/customerportal - Customer portal access

Supported: /invoices/{id}/files - Invoice file retrieval

Supported: /payments/{id}/paid - Mark payments as paid

Supported: /payments/{id}/refund - Process refunds

Supported: /teams/{id}/settings - Team settings management

Supported: /teams/{id}/series - Invoice series configuration

Supported: All other endpoints in the API

Getting Started

Step 1: Verify gigstack Connect Status

Step 2: List Available Teams

Step 3: Test Cross-Team Access

Step 4: Implement in Your Application

For additional assistance, contact support@gigstack.io

gigstack Connect API Guide

gigstack Connect API Guide#

Overview#

Key Features#

How It Works#

Requirements#

Usage Examples#

Accessing Clients Across Teams#

Managing Invoices Across Teams#

Processing Payments for Other Teams#

Managing Services Across Teams#

Team Settings Management#

Marketplace Payment Splitting#

How Payment Splitting Works#

Basic Marketplace Payment Split#

Creating a New Merchant Team#

Custom Item Configuration for Connect Payments#

Fixed Commission Pricing#

Client Assignment Strategies#

Use Cases#

1. Franchise Management#

2. Multi-Entity Corporation#

3. Accounting Service Provider#

4. Consolidated Operations#

5. Marketplace Platform#

Security and Permissions#

Access Control#

Permission Requirements#

Error Responses#

Not a Master Team#

Team Not Found#

No Matched Teams#

Insufficient Permissions#

Best Practices#

Performance Considerations#

Rate Limits#

Optimization Tips#

Complete Endpoint Support#

Core Resources#

Additional Operations#

Getting Started#

Step 1: Verify gigstack Connect Status#

Step 2: List Available Teams#

Step 3: Test Cross-Team Access#

Step 4: Implement in Your Application#

gigstack Connect API Guide

Overview

Key Features

How It Works

Requirements

Usage Examples

Accessing Clients Across Teams

Managing Invoices Across Teams

Processing Payments for Other Teams

Managing Services Across Teams

Team Settings Management

Marketplace Payment Splitting

How Payment Splitting Works

Basic Marketplace Payment Split

Creating a New Merchant Team

Custom Item Configuration for Connect Payments

Fixed Commission Pricing

Client Assignment Strategies

Use Cases

1. Franchise Management

2. Multi-Entity Corporation

3. Accounting Service Provider

4. Consolidated Operations

5. Marketplace Platform

Security and Permissions

Access Control

Permission Requirements

Error Responses

Not a Master Team

Team Not Found

No Matched Teams

Insufficient Permissions

Best Practices

Performance Considerations

Rate Limits

Optimization Tips

Complete Endpoint Support

Core Resources

Additional Operations

Getting Started

Step 1: Verify gigstack Connect Status

Step 2: List Available Teams

Step 3: Test Cross-Team Access

Step 4: Implement in Your Application