Create draft invoice (pre-factura)

curl --request POST \
  --url https://api.gigstack.io/v2/invoices/draft \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "invoice_type": "I",
  "currency": "MXN",
  "use": "G03",
  "payment_form": "03",
  "payment_method": "PUE",
  "client": {
    "id": "client_1234567890"
  },
  "items": [
    {
      "quantity": 1,
      "description": "Servicio de consultoría",
      "product_key": "80141503",
      "unit_key": "ACT",
      "unit_name": "Actividad",
      "unit_price": 5000,
      "taxes": [
        {
          "type": "IVA",
          "rate": 0.16,
          "factor": "Tasa",
          "withholding": false,
          "inclusive": false
        }
      ]
    }
  ],
  "metadata": {
    "project_id": "PROJ-2024-001"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    invoice_type: 'I',
    currency: 'MXN',
    use: 'G03',
    payment_form: '03',
    payment_method: 'PUE',
    client: {id: 'client_1234567890'},
    items: [
      {
        quantity: 1,
        description: 'Servicio de consultoría',
        product_key: '80141503',
        unit_key: 'ACT',
        unit_name: 'Actividad',
        unit_price: 5000,
        taxes: [
          {type: 'IVA', rate: 0.16, factor: 'Tasa', withholding: false, inclusive: false}
        ]
      }
    ],
    metadata: {project_id: 'PROJ-2024-001'}
  })
};

fetch('https://api.gigstack.io/v2/invoices/draft', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gigstack.io/v2/invoices/draft"

payload = {
    "invoice_type": "I",
    "currency": "MXN",
    "use": "G03",
    "payment_form": "03",
    "payment_method": "PUE",
    "client": { "id": "client_1234567890" },
    "items": [
        {
            "quantity": 1,
            "description": "Servicio de consultoría",
            "product_key": "80141503",
            "unit_key": "ACT",
            "unit_name": "Actividad",
            "unit_price": 5000,
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16,
                    "factor": "Tasa",
                    "withholding": False,
                    "inclusive": False
                }
            ]
        }
    ],
    "metadata": { "project_id": "PROJ-2024-001" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "message": "Draft created",
  "data": {
    "id": "Wm4R8tY2uI6oP0aS3dF7",
    "draft": true,
    "invoice_type": "I",
    "client": {
      "id": "client_1234567890",
      "name": "ESCUELA KEMPER URGATE",
      "legal_name": "ESCUELA KEMPER URGATE",
      "email": "contabilidad@ejemplo.com",
      "bcc": [],
      "phone": "+524421234567",
      "tax_id": "EKU9003173C9",
      "tax_system": "601",
      "use": "G03",
      "address": {
        "street": "Av. Constituyentes",
        "exterior": "1000",
        "neighborhood": "Centro",
        "city": "Querétaro",
        "state": "QRO",
        "zip": "76000",
        "country": "MEX"
      },
      "is_valid": true,
      "efos": {
        "is_valid": true
      },
      "metadata": {},
      "livemode": true,
      "from": "api",
      "owner": "user_1234567890",
      "team": "team_1234567890",
      "created_at": 1767225600000
    },
    "created_at": 1767225600000,
    "updated_at": 1767225600000,
    "currency": "MXN",
    "exchange_rate": 1,
    "total": 5800,
    "subtotal": 5000,
    "discount": 0,
    "series": "A",
    "folio_number": null,
    "use": "G03",
    "payment_form": "03",
    "payment_method": "PUE",
    "date": null,
    "livemode": true,
    "owner": "user_1234567890",
    "from": "api",
    "status": "draft",
    "items": [
      {
        "quantity": 1,
        "description": "Servicio de consultoría",
        "product_key": "80141503",
        "unit_key": "ACT",
        "unit_name": "Actividad",
        "unit_price": 5000,
        "taxes": [
          {
            "type": "IVA",
            "rate": 0.16,
            "factor": "Tasa",
            "withholding": false,
            "inclusive": false
          }
        ]
      }
    ],
    "metadata": {
      "project_id": "PROJ-2024-001"
    },
    "automation_type": "none",
    "emails": [],
    "related_documents": [],
    "complements": []
  }
}

Invoices

Create draft invoice (pre-factura)

Small working example

Integration note: Save data.id as the draft ID and inspect data.livemode before testing fiscal operations. Draft creation does not stamp a CFDI. 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 draft invoice (pre-factura) that can be edited and stamped later.

Only the invoice_type field is required. All other fields are optional, allowing you to build the invoice incrementally:

Create a draft with minimal data (invoice_type)
Update the draft as data becomes available (client, items, payment details)
Preview the draft to generate a PDF with “Sin Validez Fiscal” watermark
Stamp the draft when ready to finalize it into a valid CFDI

gigstack Connect: Create drafts for other teams using the team parameter.

POST

invoices

draft

Create draft invoice (pre-factura)

curl --request POST \
  --url https://api.gigstack.io/v2/invoices/draft \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "invoice_type": "I",
  "currency": "MXN",
  "use": "G03",
  "payment_form": "03",
  "payment_method": "PUE",
  "client": {
    "id": "client_1234567890"
  },
  "items": [
    {
      "quantity": 1,
      "description": "Servicio de consultoría",
      "product_key": "80141503",
      "unit_key": "ACT",
      "unit_name": "Actividad",
      "unit_price": 5000,
      "taxes": [
        {
          "type": "IVA",
          "rate": 0.16,
          "factor": "Tasa",
          "withholding": false,
          "inclusive": false
        }
      ]
    }
  ],
  "metadata": {
    "project_id": "PROJ-2024-001"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    invoice_type: 'I',
    currency: 'MXN',
    use: 'G03',
    payment_form: '03',
    payment_method: 'PUE',
    client: {id: 'client_1234567890'},
    items: [
      {
        quantity: 1,
        description: 'Servicio de consultoría',
        product_key: '80141503',
        unit_key: 'ACT',
        unit_name: 'Actividad',
        unit_price: 5000,
        taxes: [
          {type: 'IVA', rate: 0.16, factor: 'Tasa', withholding: false, inclusive: false}
        ]
      }
    ],
    metadata: {project_id: 'PROJ-2024-001'}
  })
};

fetch('https://api.gigstack.io/v2/invoices/draft', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gigstack.io/v2/invoices/draft"

payload = {
    "invoice_type": "I",
    "currency": "MXN",
    "use": "G03",
    "payment_form": "03",
    "payment_method": "PUE",
    "client": { "id": "client_1234567890" },
    "items": [
        {
            "quantity": 1,
            "description": "Servicio de consultoría",
            "product_key": "80141503",
            "unit_key": "ACT",
            "unit_name": "Actividad",
            "unit_price": 5000,
            "taxes": [
                {
                    "type": "IVA",
                    "rate": 0.16,
                    "factor": "Tasa",
                    "withholding": False,
                    "inclusive": False
                }
            ]
        }
    ],
    "metadata": { "project_id": "PROJ-2024-001" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "message": "Draft created",
  "data": {
    "id": "Wm4R8tY2uI6oP0aS3dF7",
    "draft": true,
    "invoice_type": "I",
    "client": {
      "id": "client_1234567890",
      "name": "ESCUELA KEMPER URGATE",
      "legal_name": "ESCUELA KEMPER URGATE",
      "email": "contabilidad@ejemplo.com",
      "bcc": [],
      "phone": "+524421234567",
      "tax_id": "EKU9003173C9",
      "tax_system": "601",
      "use": "G03",
      "address": {
        "street": "Av. Constituyentes",
        "exterior": "1000",
        "neighborhood": "Centro",
        "city": "Querétaro",
        "state": "QRO",
        "zip": "76000",
        "country": "MEX"
      },
      "is_valid": true,
      "efos": {
        "is_valid": true
      },
      "metadata": {},
      "livemode": true,
      "from": "api",
      "owner": "user_1234567890",
      "team": "team_1234567890",
      "created_at": 1767225600000
    },
    "created_at": 1767225600000,
    "updated_at": 1767225600000,
    "currency": "MXN",
    "exchange_rate": 1,
    "total": 5800,
    "subtotal": 5000,
    "discount": 0,
    "series": "A",
    "folio_number": null,
    "use": "G03",
    "payment_form": "03",
    "payment_method": "PUE",
    "date": null,
    "livemode": true,
    "owner": "user_1234567890",
    "from": "api",
    "status": "draft",
    "items": [
      {
        "quantity": 1,
        "description": "Servicio de consultoría",
        "product_key": "80141503",
        "unit_key": "ACT",
        "unit_name": "Actividad",
        "unit_price": 5000,
        "taxes": [
          {
            "type": "IVA",
            "rate": 0.16,
            "factor": "Tasa",
            "withholding": false,
            "inclusive": false
          }
        ]
      }
    ],
    "metadata": {
      "project_id": "PROJ-2024-001"
    },
    "automation_type": "none",
    "emails": [],
    "related_documents": [],
    "complements": []
  }
}

Authorizations

Authorization

string

header

required

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

team

string

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

application/json

Unknown top-level keys are rejected (400 validation_failed / unexpected_key) — body validation runs in strict allowlist mode. team, livemode and owner are reserved and injected by the auth middleware.

invoice_type

enum<string>

required

Type of invoice to draft:

I: Income (Ingreso)
E: Egress (Egreso / Credit Note)

Available options:

I,

E

Example:

"I"

client

object | null

Client information (optional at creation, required for stamping)

Show child attributes

currency

string

Currency code (optional at creation, required for stamping)

Example:

"MXN"

exchange_rate

number

Exchange rate (auto-fetched if not provided at stamp time)

Example:

1

use

string

CFDI use code (optional at creation, required for stamping)

Example:

"G03"

payment_form

enum<string>

Payment form code (optional at creation, required for stamping)

Available options:

01,

02,

03,

04,

05,

06,

08,

12,

13,

14,

15,

17,

23,

24,

25,

26,

27,

28,

29,

30,

31,

99

Example:

"03"

payment_method

enum<string>

Payment method (optional at creation, required for stamping)

Available options:

PPD,

PUE

Example:

"PUE"

items

object[]

Invoice line items (optional at creation, required for stamping)

Show child attributes

series

string

Invoice series

Example:

"A"

folio_number

number

Custom folio number (auto-assigned if not provided at stamp time)

exports

enum<string> | null

Export classification

Available options:

01,

02,

03,

04,

null

complements

object[] | null

Show child attributes

invoice_pdf_notes

string

Custom notes to include in the PDF

addenda

string | null

XML addenda to include

global

object | null

Show child attributes

automation_type

enum<string>

Automation to trigger after stamping

Available options:

payment,

none

send_email

boolean

Whether to send the document via email to the client. Defaults to true.

ignore_emails

boolean | null

Suppress all notification emails for this document. Takes precedence over send_email — when true, no mail is sent even if send_email is true.

Example:

false

emails

string<email>[]

metadata

object

Custom key-value metadata

Response

Draft created successfully

message

string

Example:

"Draft created"

data

object

Show child attributes

Clients

Services

Descarga Masiva SAT

Invoices

Payments

Receipts

Retentions

Teams

Users

Webhooks

Catalogs

Auth

SAT Lists

Documents

Platform Payouts

Create draft invoice (pre-factura)

Authorizations

Query Parameters

Body

Response