Services API Guide

Manage your product and service catalog with SAT compliance codes. The Services API handles product/service definitions, tax configurations, and pricing for use in invoices and payments.

📋 Overview

Services represent the items you sell or provide. Each service includes SAT product keys, unit keys, pricing, and tax configurations required for Mexican tax compliance.

🔑 Key Features

SAT Product Keys - Proper classification for CFDI compliance

Tax Configuration - IVA, ISR, IEPS support with rates

SKU Management - Internal product identification

Auto-creation - Create services during invoice/payment flow

Flexible Pricing - Unit prices with currency support

📚 Endpoints

List Services

Retrieve a paginated list of services in your catalog.

Query Parameters:

limit (integer, 1-100) - Number of results per page (default: 10)

next (string) - Pagination cursor for next page

team (string) - gigstack Connect: Target team ID

Example Request:

Example Response:

{
    "message": "Services retrieved successfully",
    "data": [
        {
            "id": "service_1234567890",
            "description": "Consulting services",
            "sku": "CONS-001",
            "product_key": "80141503",
            "unit_key": "E48",
            "unit_name": "Servicio",
            "unit_price": 1000.0,
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16,
                    "factor": "Tasa",
                    "withholding": false
                }
            ],
            "team": "team_1234567890",
            "created_at": 1677651234
        }
    ],
    "has_more": false,
    "total_results": 1
}

Create Service

Create a new service in your catalog.

Request Body:

{
    "description": "Professional consulting services",
    "sku": "CONS-001",
    "product_key": "80141503",
    "unit_key": "E48",
    "unit_name": "Servicio",
    "unit_price": 1500.0,
    "taxes": [
        {
            "type": "IVA",
            "rate": 0.16,
            "factor": "Tasa",
            "base": "01",
            "inclusive": false,
            "withholding": false
        }
    ]
}

Example Request:

Get Service

Retrieve a specific service by ID.

Example Request:

Update Service

Update an existing service's information.

Example Request:

Delete Service

Delete a specific service from your catalog.

Example Request:

🏗️ Service Structure

Important Fields

Field	Type	Description	Example
`description`	string	Service description	"Consulting services"
`sku`	string	Stock Keeping Unit	"CONS-001"
`product_key`	string	SAT product key (8 digits)	"80141503"
`unit_key`	string	SAT unit key	"E48"
`unit_name`	string	Unit display name	"Servicio"
`unit_price`	number	Price per unit	1000.00
`taxes`	array	Tax configuration	See Tax Configuration

📊 Tax Configuration

Tax Object Structure

{
    "type": "IVA", // Tax type: IVA, ISR, IEPS
    "rate": 0.16, // Tax rate (0.16 = 16%)
    "factor": "Tasa", // SAT factor type
    "base": "01", // Tax base code
    "inclusive": false, // If tax is included in price
    "withholding": false // If this is a withholding tax
}

Common Tax Configurations

Standard 16% IVA

{
    "type": "IVA",
    "rate": 0.16,
    "factor": "Tasa",
    "withholding": false
}

10% ISR Withholding

{
    "type": "ISR",
    "rate": 0.1,
    "factor": "Tasa",
    "withholding": true
}

Zero IVA (Exempt)

{
    "type": "IVA",
    "rate": 0.0,
    "factor": "Exento",
    "withholding": false
}

🗂️ Common SAT Product Keys

Category	Product Key	Description
Consulting	80141503	Business consulting
Software	81111500	Software development
Web Services	81112100	Web hosting services
Training	86101604	Training services
Design	82121500	Graphic design
Marketing	80141600	Marketing services
Legal	84111500	Legal services
Accounting	84111600	Accounting services
Medical	85121600	Medical services
Construction	72121400	Construction services

📏 Common SAT Unit Keys

Unit Key	Description	Use Case
E48	Servicio	Services
H87	Pieza	Individual pieces
EA	Elemento	Elements/Items
ACT	Actividad	Activities
MON	Mes	Monthly services
ANN	Año	Annual services
HUR	Hora	Hourly services
DAY	Día	Daily services
KGM	Kilogramo	Weight-based
MTR	Metro	Length-based

🔍 Search and Auto-Creation

When creating invoices or payments, you can search for existing services or auto-create them:

{
    "items": [
        {
            "search": {
                "on_key": "sku",
                "on_value": "CONS-001",
                "auto_create": true
            },
            "description": "Consulting services",
            "sku": "CONS-001",
            "product_key": "80141503",
            "unit_key": "E48",
            "unit_price": 1000.0,
            "quantity": 2,
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16
                }
            ]
        }
    ]
}

🎯 Use Cases

1. Professional Services Company

{
    "description": "Legal consultation - 1 hour",
    "sku": "LEGAL-HR",
    "product_key": "84111500",
    "unit_key": "HUR",
    "unit_name": "Hora",
    "unit_price": 3000.0,
    "taxes": [
        {
            "type": "IVA",
            "rate": 0.16,
            "withholding": false
        },
        {
            "type": "ISR",
            "rate": 0.1,
            "withholding": true
        }
    ]
}

2. E-commerce Product

{
    "description": "Laptop Computer",
    "sku": "LAPTOP-001",
    "product_key": "43211500",
    "unit_key": "H87",
    "unit_name": "Pieza",
    "unit_price": 15000.0,
    "taxes": [
        {
            "type": "IVA",
            "rate": 0.16,
            "withholding": false
        }
    ]
}

3. Subscription Service

{
    "description": "Software subscription - Monthly",
    "sku": "SAAS-MONTHLY",
    "product_key": "81111500",
    "unit_key": "MON",
    "unit_name": "Mes",
    "unit_price": 500.0,
    "taxes": [
        {
            "type": "IVA",
            "rate": 0.16,
            "withholding": false
        }
    ]
}

💡 Best Practices

Always use correct SAT codes - Ensure product_key and unit_key match SAT catalogs

Configure taxes properly - Include all applicable taxes (IVA, ISR, IEPS)

Use meaningful SKUs - Create a consistent SKU system for internal tracking

Include detailed descriptions - Help clients understand what they're paying for

Set up common services - Pre-create frequently used services

Update prices regularly - Keep pricing current with market conditions

Invoices API - Use services in invoices

Payments API - Include services in payment requests

Teams API - Configure default tax settings

🚨 Error Handling

Invalid Product Key

{
    "message": "Invalid product_key",
    "error": "Product key must be 8 digits from SAT catalog"
}

Invalid Tax Configuration

{
    "message": "Invalid tax configuration",
    "error": "Tax rate must be between 0 and 1"
}

Service Not Found

{
    "message": "Service not found",
    "error": "The specified service does not exist"
}

Need help with service configuration? Check our support documentation or contact support@gigstack.io

📋 Overview#

🔑 Key Features#

📚 Endpoints#

List Services#

Create Service#

Get Service#

Update Service#

Delete Service#

🏗️ Service Structure#

Important Fields#

📊 Tax Configuration#

Tax Object Structure#

Common Tax Configurations#

Standard 16% IVA#

10% ISR Withholding#

Zero IVA (Exempt)#

🗂️ Common SAT Product Keys#

📏 Common SAT Unit Keys#

🔍 Search and Auto-Creation#

🎯 Use Cases#

1. Professional Services Company#

2. E-commerce Product#

3. Subscription Service#

💡 Best Practices#

🔗 Related Resources#

🚨 Error Handling#

Invalid Product Key#

Invalid Tax Configuration#

Service Not Found#

📋 Overview

🔑 Key Features

📚 Endpoints

List Services

Create Service

Get Service

Update Service

Delete Service

🏗️ Service Structure

Important Fields

📊 Tax Configuration

Tax Object Structure

Common Tax Configurations

Standard 16% IVA

10% ISR Withholding

Zero IVA (Exempt)

🗂️ Common SAT Product Keys

📏 Common SAT Unit Keys

🔍 Search and Auto-Creation

🎯 Use Cases

1. Professional Services Company

2. E-commerce Product

3. Subscription Service

💡 Best Practices

🔗 Related Resources

🚨 Error Handling

Invalid Product Key

Invalid Tax Configuration

Service Not Found