Services API Guide

Start with shared fields, then the Mexico or Colombia guide. The CFDI, RFC, SAT catalog, and payment-complement examples below describe Mexico; they are not universal country requirements.

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

GET /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:

curl -X GET "https://api.gigstack.io/v2/services?limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

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

POST /services

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": null,
            "inclusive": false,
            "withholding": false
        }
    ]
}

Example Request:

curl -X POST https://api.gigstack.io/v2/services \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Web development services",
    "sku": "WEB-001",
    "product_key": "81111500",
    "unit_key": "E48",
    "unit_name": "Servicio",
    "unit_price": 2500.00,
    "taxes": [
      {
        "type": "IVA",
        "rate": 0.16,
        "factor": "Tasa",
        "withholding": false
      }
    ]
  }'

Get Service

GET /services/{id}

Retrieve a specific service by ID. Example Request:

curl -X GET https://api.gigstack.io/v2/services/service_1234567890 \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Service

PUT /services/{id}

Update an existing service’s information. Example Request:

curl -X PUT https://api.gigstack.io/v2/services/service_1234567890 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "unit_price": 1800.00,
    "description": "Updated consulting services"
  }'

Delete Service

DELETE /services/{id}

Delete a specific service from your catalog. Example Request:

curl -X DELETE https://api.gigstack.io/v2/services/service_1234567890 \
  -H "Authorization: Bearer YOUR_TOKEN"

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",
    "rate": 0.16,
    "factor": "Tasa",
    "base": null,
    "inclusive": false,
    "withholding": false
}

rate: 0.16 means 16%; inclusive indicates whether the price includes the tax, and withholding identifies a retained tax. The optional base is numeric or null.

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-rate IVA

Zero-rate and exempt treatment are different. For a zero rate, retain factor: "Tasa":

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

Exempt IVA

Use factor: "Exento" only for an exempt operation. Choose the treatment that applies to the actual sale; a numeric zero alone does not establish exemption.

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

Common SAT Product Keys

Category	Product Key	Description
Consulting	80101500	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"
}

For additional assistance, contact support@gigstack.io

Start here

Fields by country

Shared examples

Mexico · CFDI examples

Build and troubleshoot

Invoicing

Customers and payments

Mexico · SAT

Accounts

Mexico · SAT catalogs

Services API Guide

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-rate IVA

Exempt IVA

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

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-rate IVA

​Exempt IVA

​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-rate IVA

Exempt IVA

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