> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gigstack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Services API Guide

> Integration guide for Services

<Note>Start with [shared fields](/concepts/shared-fields), then the [Mexico](/countries/mexico) or [Colombia](/countries/colombia) guide. The CFDI, RFC, SAT catalog, and payment-complement examples below describe Mexico; they are not universal country requirements.</Note>

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

```http theme={null}
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:**

```bash theme={null}
curl -X GET "https://api.gigstack.io/v2/services?limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Example Response:**

```json theme={null}
{
    "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

```http theme={null}
POST /services
```

Create a new service in your catalog.

**Request Body:**

```json theme={null}
{
    "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:**

```bash theme={null}
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

```http theme={null}
GET /services/{id}
```

Retrieve a specific service by ID.

**Example Request:**

```bash theme={null}
curl -X GET https://api.gigstack.io/v2/services/service_1234567890 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Update Service

```http theme={null}
PUT /services/{id}
```

Update an existing service's information.

**Example Request:**

```bash theme={null}
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

```http theme={null}
DELETE /services/{id}
```

Delete a specific service from your catalog.

**Example Request:**

```bash theme={null}
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

```json theme={null}
{
    "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

```json theme={null}
{
    "type": "IVA",
    "rate": 0.16,
    "factor": "Tasa",
    "withholding": false
}
```

#### 10% ISR Withholding

```json theme={null}
{
    "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"`:

```json theme={null}
{
    "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.

```json theme={null}
{
    "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:

```json theme={null}
{
    "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

```json theme={null}
{
    "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

```json theme={null}
{
    "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

```json theme={null}
{
    "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

1. **Always use correct SAT codes** - Ensure product\_key and unit\_key match SAT catalogs
2. **Configure taxes properly** - Include all applicable taxes (IVA, ISR, IEPS)
3. **Use meaningful SKUs** - Create a consistent SKU system for internal tracking
4. **Include detailed descriptions** - Help clients understand what they're paying for
5. **Set up common services** - Pre-create frequently used services
6. **Update prices regularly** - Keep pricing current with market conditions

## Related Resources

* [Invoices API](/guides/invoices) - Use services in invoices
* [Payments API](/guides/payments) - Include services in payment requests
* [Teams API](/guides/teams) - Configure default tax settings

## Error Handling

### Invalid Product Key

```json theme={null}
{
    "message": "Invalid product_key",
    "error": "Product key must be 8 digits from SAT catalog"
}
```

### Invalid Tax Configuration

```json theme={null}
{
    "message": "Invalid tax configuration",
    "error": "Tax rate must be between 0 and 1"
}
```

### Service Not Found

```json theme={null}
{
    "message": "Service not found",
    "error": "The specified service does not exist"
}
```

***

For additional assistance, contact [support@gigstack.io](mailto:support@gigstack.io)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.