Receipts API Guide

Create, manage, and stamp receipts that can be converted into CFDI invoices. The Receipts API handles pre-invoice document creation with flexible validity periods and SAT compliance for later stamping.

Overview

The Receipts API provides comprehensive receipt management for pre-invoice documents. Create receipts with automatic calculations, flexible validity periods, and stamp them as CFDI invoices when needed.

Key Features

Receipt Creation - Create pre-invoice receipts with automatic calculations

Flexible Validity - Set custom validity periods (day, week, month, etc.)

CFDI Stamping - Convert receipts to compliant CFDI invoices

Client Integration - Full client management and auto-creation support

Enhanced Metadata Support - Track custom data, references, and business identifiers with full flexibility

Periodicity Control - Manage receipt lifecycle and validity

Idempotency - Prevent duplicate receipt creation

Endpoints

List Receipts

Retrieve a paginated list of receipts.

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": "Receipts retrieved successfully",
    "data": [
        {
            "id": "receipt_1234567890",
            "client": {
                "id": "client_1234567890",
                "name": "Juan Pérez García",
                "tax_id": "PEGJ800101ABC"
            },
            "status": "pending",
            "total": 1160.0,
            "subtotal": 1000.0,
            "taxes": 160.0,
            "currency": "MXN",
            "periodicity": "month",
            "payment_form": "03",
            "created": 1677651234,
            "validUntil": 1680243234,
            "url": "https://invoicing.gigstack.pro/autofactura?id=receipt_1234567890"
        }
    ],
    "has_more": false,
    "total_results": 1
}

Create Receipt

Create a new receipt with items and client information. Receipts are pre-invoice documents that can be later stamped as CFDI invoices.

Key Features:

Automatic amount calculations with taxes

Flexible validity periods

Client auto-creation support

Metadata support for tracking

Custom payment form codes

Idempotency support to prevent duplicate receipts

Request Body:

{
    "client": {
        "id": "client_1234567890"
    },
    "currency": "MXN",
    "exchange_rate": 1.0,
    "items": [
        {
            "id": "service_1234567890",
            "quantity": 2,
            "unit_price": 1000.0
        }
    ],
    "periodicity": "month",
    "payment_form": "03",
    "idempotency_key": "receipt-key-12345",
    "metadata": {
        "order_id": "ORD-12345",
        "department": "Sales",
        "project_code": "PROJ-2024-Q1",
        "external_reference": "EXT-ABC-789",
        "priority": "high",
        "custom_tags": ["recurring", "priority-client"]
    }
}

Optional Fields:

idempotency_key (string) - Unique key to prevent duplicate receipt creation. If a receipt with this key already exists, the existing receipt will be returned instead of creating a duplicate.

exchange_rate (number) - Exchange rate for currency conversion. If not provided, the latest rate from our rates collection will be used automatically.

Periodicity Options:

day - Valid until end of current day

week - Valid until end of current week

two_weeks - Valid for 2 weeks from creation

month - Valid until end of current month (default)

two_months - Valid until end of next month

Payment Form Codes:

01 - Cash

02 - Check

03 - Electronic transfer

04 - Credit card

05 - Electronic money

06 - Digital money

99 - To be defined

Idempotency:

The idempotency_key parameter allows you to safely retry receipt creation requests without creating duplicate receipts. This is especially useful for handling network errors or ensuring exactly-once semantics in distributed systems.

If you provide an idempotency_key and a receipt with that key already exists, the API will return the existing receipt instead of creating a new one

Idempotency keys should be unique per receipt creation attempt

Common patterns: use UUIDs, combine order ID with timestamp, or use external system references

Example with Client Auto-Creation:

Get Receipt

Retrieve a specific receipt by ID.

Example Request:

Stamp Receipt

Convert a receipt into a CFDI invoice by stamping it with SAT.

Stamp Options:

client - Stamp to the associated client

general_public_national - Stamp to Mexican general public

general_public_foreign - Stamp to foreign general public

Request Body:

{
    "stamp_to": "client",
    "fiscal_information": {
        "legal_name": "Juan Pérez García",
        "tax_id": "PEGJ800101ABC",
        "tax_system": "601",
        "zip": "01000"
    },
    "date": 1677651234000
}

Example Request:

Cancel Receipt

Cancel a receipt. This action cannot be undone.

Example Request:

Receipt Structure

Receipt Status

Status	Description
`pending`	Receipt created, awaiting stamping
`stamped`	Receipt converted to CFDI invoice
`expired`	Receipt validity period expired
`canceled`	Receipt canceled

Validity Periods

Receipts have configurable validity periods based on the periodicity parameter:

day: Valid until end of creation day

week: Valid until end of creation week

two_weeks: Valid for 14 days from creation

month: Valid until end of creation month (default)

two_months: Valid until end of the following month

Complex Receipt Examples

Receipt with Multiple Items

{
    "client": {
        "id": "client_1234567890"
    },
    "currency": "MXN",
    "items": [
        {
            "id": "service_001",
            "quantity": 2,
            "unit_price": 1000.0
        },
        {
            "description": "Installation service",
            "quantity": 1,
            "unit_price": 500.0,
            "product_key": "72121400",
            "unit_key": "E48",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16
                }
            ]
        }
    ],
    "periodicity": "two_weeks",
    "payment_form": "04"
}

Receipt with USD Currency and Exchange Rate

{
    "client": {
        "id": "client_1234567890"
    },
    "currency": "USD",
    "exchange_rate": 18.5,
    "items": [
        {
            "description": "International consulting",
            "quantity": 10,
            "unit_price": 100.0,
            "product_key": "80141503",
            "unit_key": "HUR",
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.0,
                    "factor": "Exento"
                }
            ]
        }
    ],
    "periodicity": "month",
    "payment_form": "03"
}

Receipt with Custom Invoice Configuration

{
    "client": {
        "id": "client_1234567890"
    },
    "currency": "MXN",
    "items": [
        {
            "id": "service_1234567890",
            "quantity": 1
        }
    ],
    "periodicity": "month",
    "payment_form": "03",
    "invoice_config": {
        "serie": "B",
        "folio": 456
    },
    "metadata": {
        "project_id": "PROJ-2024-001",
        "department": "Engineering"
    }
}

Enhanced Metadata Support

The receipts API now supports flexible metadata storage that preserves all custom properties you provide. This enhancement allows you to:

Store Any Custom Properties - Add any key-value pairs relevant to your business

Preserve Data Structure - All metadata properties are returned exactly as submitted

Track Business References - Store external IDs, project codes, and system identifiers

Support Complex Data - Use nested objects, arrays, and mixed data types

Metadata Usage Examples

Basic Tracking:

{
    "metadata": {
        "order_id": "ORD-12345",
        "department": "Sales"
    }
}

Advanced Tracking:

{
    "metadata": {
        "project": {
            "code": "PROJ-2024-Q1",
            "manager": "Alice Smith",
            "budget_category": "consulting"
        },
        "external_systems": {
            "crm_id": "CRM-789",
            "erp_reference": "ERP-ABC-123"
        },
        "tags": ["priority", "recurring", "b2b"],
        "workflow_stage": "approved",
        "custom_fields": {
            "delivery_date": "2024-03-15",
            "special_instructions": "Rush order"
        }
    }
}

Integration Identifiers:

{
    "metadata": {
        "stripe_session_id": "cs_test_123",
        "shopify_order_id": "shop_456",
        "quickbooks_reference": "QB-789",
        "internal_workflow_id": "WF-2024-001"
    }
}

Common Scenarios

1. Create Monthly Receipt (Standard)

2. Create Weekly Receipt

3. Stamp Receipt to Client

4. Stamp to General Public

Receipt Workflows

Standard Receipt Workflow

Receipt with Auto-Client Creation

Receipt Validity Management

Best Practices

Set appropriate periodicity - Choose validity periods based on your workflow

Leverage enhanced metadata - Store any custom data, external references, and business identifiers; all properties are preserved exactly as submitted

Include complete item information - Ensure accurate calculations

Validate clients first - Check fiscal data before creating receipts

Monitor receipt expiration - Stamp receipts before they expire

Handle exchange rates - Set proper rates for foreign currency receipts

Test stamping process - Validate CFDI generation in staging

Structure metadata thoughtfully - Use consistent naming conventions and organize data logically for easy retrieval and filtering

Use idempotency keys - Always provide an idempotency_key when creating receipts to prevent duplicates, especially when retrying failed requests or processing webhook events

Clients API - Manage receipt recipients

Services API - Configure receipt items

Payments API - Process payments for receipts

Invoices API - View stamped receipts as invoices

Error Handling

Invalid Client

{
    "message": "Client not found",
    "error": "The specified client does not exist"
}

Invalid Item Configuration

{
    "message": "Invalid item",
    "error": "Service service_xyz not found"
}

Receipt Already Stamped

{
    "message": "Receipt already stamped",
    "error": "Cannot modify a stamped receipt"
}

Receipt Expired

{
    "message": "Receipt expired",
    "error": "Cannot stamp an expired receipt"
}

Stamping Error

{
    "message": "Stamping failed",
    "error": "Missing required fiscal information for CFDI generation"
}

Failed Client Fiscal Information

{
    "message": "Receipt creation failed",
    "error": "Client fiscal information validation failed. RFC is invalid or client is in EFOS blacklist."
}

When a client's fiscal information fails validation (invalid RFC or EFOS blacklist), the receipt creation will be rejected. Update the client information before retrying.

For additional assistance, contact support@gigstack.io

Receipts API Guide

Receipts API Guide#

Overview#

Key Features#

Endpoints#

List Receipts#

Create Receipt#

Get Receipt#

Stamp Receipt#

Cancel Receipt#

Receipt Structure#

Receipt Status#

Validity Periods#

Complex Receipt Examples#

Receipt with Multiple Items#

Receipt with USD Currency and Exchange Rate#

Receipt with Custom Invoice Configuration#

Enhanced Metadata Support#

Metadata Usage Examples#

Common Scenarios#

1. Create Monthly Receipt (Standard)#

2. Create Weekly Receipt#

3. Stamp Receipt to Client#

4. Stamp to General Public#

Receipt Workflows#

Standard Receipt Workflow#

Receipt with Auto-Client Creation#

Receipt Validity Management#

Best Practices#

Related Resources#

Error Handling#

Invalid Client#

Invalid Item Configuration#

Receipt Already Stamped#

Receipt Expired#

Stamping Error#

Failed Client Fiscal Information#

Receipts API Guide

Overview

Key Features

Endpoints

List Receipts

Create Receipt

Get Receipt

Stamp Receipt

Cancel Receipt

Receipt Structure

Receipt Status

Validity Periods

Complex Receipt Examples

Receipt with Multiple Items

Receipt with USD Currency and Exchange Rate

Receipt with Custom Invoice Configuration

Enhanced Metadata Support

Metadata Usage Examples

Common Scenarios

1. Create Monthly Receipt (Standard)

2. Create Weekly Receipt

3. Stamp Receipt to Client

4. Stamp to General Public

Receipt Workflows

Standard Receipt Workflow

Receipt with Auto-Client Creation

Receipt Validity Management

Best Practices

Related Resources

Error Handling

Invalid Client

Invalid Item Configuration

Receipt Already Stamped

Receipt Expired

Stamping Error

Failed Client Fiscal Information