curl --request POST \
--url https://api.gigstack.io/v2/invoices/egress \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"automation_type": "none",
"currency": "MXN",
"use": "G03",
"payment_form": "03",
"client": {
"id": "client_1234567890"
},
"items": [
{
"quantity": 1,
"description": "Purchased materials",
"sku": "MAT-001",
"product_key": "80141503",
"unit_key": "E48",
"unit_name": "Unidad",
"unit_price": 500,
"taxability": "02",
"taxes": [
{
"type": "IVA",
"rate": 0.16,
"factor": "Tasa",
"withholding": false,
"inclusive": false
}
]
}
],
"send_email": true,
"emails": [
"proveedor@empresa.com"
],
"metadata": {
"purchase_order": "PO-2024-001",
"department": "procurement"
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
automation_type: 'none',
currency: 'MXN',
use: 'G03',
payment_form: '03',
client: {id: 'client_1234567890'},
items: [
{
quantity: 1,
description: 'Purchased materials',
sku: 'MAT-001',
product_key: '80141503',
unit_key: 'E48',
unit_name: 'Unidad',
unit_price: 500,
taxability: '02',
taxes: [
{type: 'IVA', rate: 0.16, factor: 'Tasa', withholding: false, inclusive: false}
]
}
],
send_email: true,
emails: ['proveedor@empresa.com'],
metadata: {purchase_order: 'PO-2024-001', department: 'procurement'}
})
};
fetch('https://api.gigstack.io/v2/invoices/egress', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.gigstack.io/v2/invoices/egress"
payload = {
"automation_type": "none",
"currency": "MXN",
"use": "G03",
"payment_form": "03",
"client": { "id": "client_1234567890" },
"items": [
{
"quantity": 1,
"description": "Purchased materials",
"sku": "MAT-001",
"product_key": "80141503",
"unit_key": "E48",
"unit_name": "Unidad",
"unit_price": 500,
"taxability": "02",
"taxes": [
{
"type": "IVA",
"rate": 0.16,
"factor": "Tasa",
"withholding": False,
"inclusive": False
}
]
}
],
"send_email": True,
"emails": ["proveedor@empresa.com"],
"metadata": {
"purchase_order": "PO-2024-001",
"department": "procurement"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"message": "Invoice created successfully",
"data": {
"uuid": "B0C3E4F2-1A2B-4C5D-9E8F-0123456789AB",
"client": {
"id": "client_1234567890",
"name": "Proveedor ABC SA",
"email": "proveedor@empresa.com",
"tax_id": "PABC800101ABC",
"from": "api",
"livemode": true,
"owner": "user_1234567890",
"team": "team_1234567890",
"created_at": 1767225600000
},
"status": "valid",
"currency": "MXN",
"exchange_rate": 1,
"total": 580,
"subtotal": 500,
"taxes": 80,
"discount": 0,
"series": "E",
"folio_number": 123,
"invoice_type": "E",
"items": [
{
"id": "item_1234567890",
"description": "Purchased materials",
"quantity": 1,
"unit_price": 500,
"product_key": "80141503",
"unit_key": "E48"
}
],
"created_at": 1677651234,
"livemode": true,
"owner": "user_1234567890"
}
}{
"message": "Invalid body",
"error": "<string>",
"errors": [
{
"path": "client_id",
"code": "unexpected_key",
"message": "Unexpected field"
}
]
}{
"message": "Invalid body",
"error": "<string>",
"errors": [
{
"path": "client_id",
"code": "unexpected_key",
"message": "Unexpected field"
}
]
}{
"message": "Invalid body",
"error": "<string>",
"errors": [
{
"path": "client_id",
"code": "unexpected_key",
"message": "Unexpected field"
}
]
}{
"message": "Invalid body",
"error": "<string>",
"errors": [
{
"path": "client_id",
"code": "unexpected_key",
"message": "Unexpected field"
}
]
}{
"message": "Invalid body",
"error": "<string>",
"errors": [
{
"path": "client_id",
"code": "unexpected_key",
"message": "Unexpected field"
}
]
}{
"message": {
"error": "El certificado de sello digital (CSD) no está configurado o no es válido.",
"code": "csd_validation_error",
"retryable": false
}
}{
"message": "Invalid body",
"error": "<string>",
"errors": [
{
"path": "client_id",
"code": "unexpected_key",
"message": "Unexpected field"
}
]
}{
"message": {
"error": "El servicio de timbrado no está disponible en este momento. Vuelve a intentarlo en unos minutos.",
"code": "pac_unavailable",
"retryable": true
}
}Create egress invoice
Integration note: A credit note adjusts the fiscal document. It does not refund money through a payment processor. Verified staging issuance returned HTTP 200 and data.uuid. Read shared fields and the Mexico or Colombia guide for country-specific meaning. The linked fiscal recipes and staging issuance results use a Mexican issuer.
Create a new egress invoice (expense/credit note) with CFDI 4.0 compliance.
gigstack Connect: Create invoices for other teams using the team parameter.
curl --request POST \
--url https://api.gigstack.io/v2/invoices/egress \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"automation_type": "none",
"currency": "MXN",
"use": "G03",
"payment_form": "03",
"client": {
"id": "client_1234567890"
},
"items": [
{
"quantity": 1,
"description": "Purchased materials",
"sku": "MAT-001",
"product_key": "80141503",
"unit_key": "E48",
"unit_name": "Unidad",
"unit_price": 500,
"taxability": "02",
"taxes": [
{
"type": "IVA",
"rate": 0.16,
"factor": "Tasa",
"withholding": false,
"inclusive": false
}
]
}
],
"send_email": true,
"emails": [
"proveedor@empresa.com"
],
"metadata": {
"purchase_order": "PO-2024-001",
"department": "procurement"
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
automation_type: 'none',
currency: 'MXN',
use: 'G03',
payment_form: '03',
client: {id: 'client_1234567890'},
items: [
{
quantity: 1,
description: 'Purchased materials',
sku: 'MAT-001',
product_key: '80141503',
unit_key: 'E48',
unit_name: 'Unidad',
unit_price: 500,
taxability: '02',
taxes: [
{type: 'IVA', rate: 0.16, factor: 'Tasa', withholding: false, inclusive: false}
]
}
],
send_email: true,
emails: ['proveedor@empresa.com'],
metadata: {purchase_order: 'PO-2024-001', department: 'procurement'}
})
};
fetch('https://api.gigstack.io/v2/invoices/egress', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.gigstack.io/v2/invoices/egress"
payload = {
"automation_type": "none",
"currency": "MXN",
"use": "G03",
"payment_form": "03",
"client": { "id": "client_1234567890" },
"items": [
{
"quantity": 1,
"description": "Purchased materials",
"sku": "MAT-001",
"product_key": "80141503",
"unit_key": "E48",
"unit_name": "Unidad",
"unit_price": 500,
"taxability": "02",
"taxes": [
{
"type": "IVA",
"rate": 0.16,
"factor": "Tasa",
"withholding": False,
"inclusive": False
}
]
}
],
"send_email": True,
"emails": ["proveedor@empresa.com"],
"metadata": {
"purchase_order": "PO-2024-001",
"department": "procurement"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"message": "Invoice created successfully",
"data": {
"uuid": "B0C3E4F2-1A2B-4C5D-9E8F-0123456789AB",
"client": {
"id": "client_1234567890",
"name": "Proveedor ABC SA",
"email": "proveedor@empresa.com",
"tax_id": "PABC800101ABC",
"from": "api",
"livemode": true,
"owner": "user_1234567890",
"team": "team_1234567890",
"created_at": 1767225600000
},
"status": "valid",
"currency": "MXN",
"exchange_rate": 1,
"total": 580,
"subtotal": 500,
"taxes": 80,
"discount": 0,
"series": "E",
"folio_number": 123,
"invoice_type": "E",
"items": [
{
"id": "item_1234567890",
"description": "Purchased materials",
"quantity": 1,
"unit_price": 500,
"product_key": "80141503",
"unit_key": "E48"
}
],
"created_at": 1677651234,
"livemode": true,
"owner": "user_1234567890"
}
}{
"message": "Invalid body",
"error": "<string>",
"errors": [
{
"path": "client_id",
"code": "unexpected_key",
"message": "Unexpected field"
}
]
}{
"message": "Invalid body",
"error": "<string>",
"errors": [
{
"path": "client_id",
"code": "unexpected_key",
"message": "Unexpected field"
}
]
}{
"message": "Invalid body",
"error": "<string>",
"errors": [
{
"path": "client_id",
"code": "unexpected_key",
"message": "Unexpected field"
}
]
}{
"message": "Invalid body",
"error": "<string>",
"errors": [
{
"path": "client_id",
"code": "unexpected_key",
"message": "Unexpected field"
}
]
}{
"message": "Invalid body",
"error": "<string>",
"errors": [
{
"path": "client_id",
"code": "unexpected_key",
"message": "Unexpected field"
}
]
}{
"message": {
"error": "El certificado de sello digital (CSD) no está configurado o no es válido.",
"code": "csd_validation_error",
"retryable": false
}
}{
"message": "Invalid body",
"error": "<string>",
"errors": [
{
"path": "client_id",
"code": "unexpected_key",
"message": "Unexpected field"
}
]
}{
"message": {
"error": "El servicio de timbrado no está disponible en este momento. Vuelve a intentarlo en unos minutos.",
"code": "pac_unavailable",
"retryable": true
}
}Authorizations
Authentication Method: HTTP Bearer token.
The runtime requires the literal Bearer prefix — a bare token in the
Authorization header is rejected with 401 unauthorized.
Header Format: Authorization: Bearer YOUR_API_KEY
Your API key is a JWT. Live keys operate on live data (livemode: true);
test keys operate on isolated test data (livemode: false).
Get your key at: app.gigstack.pro/settings?tab=api
Errors: credential failures are answered by the authentication layer with a raw
{ "message": … } body, not the standardized envelope — 401 for a missing, malformed or
expired token, 403 for a revoked key or a plan without API access. See the Unauthorized
and AuthForbidden responses.
Query Parameters
gigstack Connect: Target team ID for multi-team access.
Requires gigstack Connect enabled on your team and shared billing account.
Also requires the multipleIssuerAccounts feature on your plan. Requests targeting a
team other than the one your API key belongs to return 403 without it.
Only API keys can use it: an OAuth access token sent with another team's id is rejected with
403 Team mismatch with OAuth token.
Optional — omit it entirely unless you are acting on another team. It deliberately
carries no example value so generated snippets do not emit ?team=undefined; when the
parameter is absent, the team is derived from your API key.
Example: ?team=team_xyz789
Body
Unknown top-level keys are rejected (400 validation_failed / unexpected_key) — body
validation runs in strict allowlist mode, so a field the schema does not declare
produces that error. In particular there is no client_id field: reference an
existing client with client: { "id": "client_…" }, or look one up with
client: { "search": { "on_key": "tax_id", "on_value": "…" } }. Supplying both id
and search on the same object is a 400.
team, livemode and owner are reserved and injected by the auth middleware.
Show child attributes
Show child attributes
"MXN"
"G03"
Line items. Only quantity is required on each item; everything else is optional or resolved from the referenced service.
Show child attributes
Show child attributes
"03"
Unix timestamp for invoice date
1640995200
Return base64 encoded PDF and XML files in response
true
Exchange rate for currency conversion. If not provided, the latest rate from our rates collection will be used automatically.
1
123
Optional. Defaults to the team's credit-note serie, then 'E'.
"A"
Optional idempotency key to prevent duplicate invoices
"unique_key_123"
01, 02, 03, 04, null "01"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
"Additional notes for PDF"
"<addenda>...</addenda>"
Whether to send the document via email to the client. Defaults to true.
true
Suppress all notification emails for this document. Takes precedence over
send_email — when true, no mail is sent even if send_email is true.
false
["client@example.com"]
Payment automation type:
none: No automation, create invoice only
none "none"
CFDI MetodoPago. Optional — defaults to PUE when omitted, which is how every
egress invoice was stamped before this field existed.
With PPD, SAT requires payment_form to be 99 ("Por definir"); any other
value you send is overridden to 99 rather than rejected.
PPD, PUE "PUE"