---
title: "Create receipt"
method: POST
path: "/receipts"
tags: ["Receipts"]
---

# Create receipt

`POST /receipts`

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

**Features:**
- Automatic amount calculations with taxes
- Flexible validity periods
- Client auto-creation support
- Metadata support for tracking
- Idempotency support to prevent duplicate receipts

**gigstack Connect:** Create receipts for other teams using the `team` parameter.

## Query parameters

- `team` string

## Request body

- ReceiptInput
  - `client` object, required
    - `id` string, nullable — Existing client ID
    - `search` object
      - `on_key` string — Field to search client on
      - `on_value` string — Value to search for
      - `auto_create` boolean — Create client if not found
      - `safety_check` boolean — When true, prevents using multiple matching results (returns error). When false, uses the first result found. Default: false
    - `address` ClientAddress, nullable
      - `country` string, nullable
      - `street` string, nullable
      - `zip` string, nullable
      - `city` string, nullable
      - `state` string, nullable
      - `exterior` string, nullable
      - `interior` string, nullable
      - `municipality` string, nullable
      - `neighborhood` string, nullable
    - `name` string, nullable
    - `company` string, nullable
    - `phone` string, nullable
    - `email` string, email, nullable
    - `legal_name` string, nullable
    - `tax_id` string, nullable
    - `metadata` object
  - `currency` string, required — Currency code (ISO 4217)
  - `exchange_rate` number, nullable — Exchange rate to use for currency conversion
  - `items` ItemSchema[], required — Receipt items
    - `id` string, nullable — Service/product ID reference
    - `search` object
      - `on_key` string — Field to search on (sku, name, etc.)
      - `on_value` string — Value to search for
      - `auto_create` boolean — Create service if not found
      - `safety_check` boolean — When true, prevents using multiple matching results (returns error). When false, uses the first result found. Default: false
    - `quantity` number, required — Item quantity
    - `description` string, nullable — Item description
    - `sku` string, nullable — Stock keeping unit
    - `product_key` string, nullable — SAT product key (c_ClaveProdServ)
    - `unit_key` string, nullable — SAT unit key (c_ClaveUnidad)
    - `unit_name` string, nullable — Unit name
    - `unit_price` number, nullable — Unit price
    - `discount` number, nullable — Discount amount or percentage
    - `taxes` TaxElement[] — Tax elements applied to this item
      - `base` union — Taxable base amount. Accepts number or numeric string. If null, calculated automatically from item price.
        - number
        - string
      - `factor` string, nullable — SAT tax factor (Tasa, Cuota, Exento)
      - `inclusive` boolean, nullable — Whether the tax is included in the unit price
      - `rate` number, required — Tax rate (e.g., 0.16 for 16% IVA)
      - `type` 'IVA' | 'ISR' | 'IEPS', required — Type of tax
      - `withholding` boolean, nullable — Whether this is a withholding tax
    - `third_party` object, nullable — Third party information for items provided by external parties
      - `legal_name` string — Third party legal name
      - `tax_id` string — Third party RFC (tax ID)
      - `tax_system` string — Third party tax system
      - `zip` string — Third party ZIP code
    - `metadata` object, nullable — Additional metadata for the item
  - `metadata` object, nullable — Additional metadata - accepts any custom properties for tracking business data, references, or integration identifiers. All properties are preserved and returned as-is.
  - `periodicity` 'day' | 'week' | 'two_weeks' | 'month' | 'two_months', nullable — Receipt validity period
  - `invoice_config` object, nullable — Invoice configuration for future stamping
    - `folio` number, nullable — Invoice folio number
    - `serie` string, nullable — Invoice series
  - `payment_form` string, nullable — SAT payment form code
  - `idempotency_key` string, nullable — Unique key to prevent duplicate receipts. If a receipt with this key already exists, the existing receipt will be returned.

## Response `200`

Receipt created successfully

- StandardSuccessResponse
  - `message` string, required
  - `data` object, required

## Other responses

- `400` — Bad request

---

[API](https://skmtc.dev/disruptive-learning/apis/gigstack-api-v2.md) · [All operations](https://skmtc.dev/disruptive-learning/apis/gigstack-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/disruptive-learning/gigstack-api-v2/revisions/5cf53ffd7580/schema)