Shared fields and country rules

You can create the same basic customer record for a Mexican or Colombian issuing business:

{
  "name": "Workshop customer",
  "email": "customer@example.com",
  "metadata": {"external_id": "customer-1042"}
}

Send this body to POST /clients. Follow Create a customer once for the complete request and duplicate lookup. Add fiscal details from the country guide before using the customer on an invoice.

Mexico · CFDI

RFC, fiscal regime, Uso CFDI, SAT product codes, and payment complements.

Colombia · DIAN

Identification type, NIT, fiscal responsibilities, and municipality codes.

Choose the issuing country first

The issuing team’s invoicing configuration selects the country and provider. client.address.country describes the customer; it does not switch the issuer to another country’s invoicing system. A Mexican issuer selling to a Colombian customer still uses the Mexican invoicing flow, with the appropriate foreign-recipient details. Start with issuer setup to confirm the country, credentials, numbering and environment. The public team response does not expose provider selection. For multiple issuing businesses, select the intended team through the documented gigstack Connect flow. Confirm its invoicing setup before issuing. Currency and test mode are separate choices; neither selects the issuing country.

Shared customer fields

These fields belong to the customer API in both country flows. “Optional” below means optional when creating a contact, not necessarily sufficient for issuing an invoice.

Fields	Meaning	Contact creation
`name`	Customer display name	Required
`email`, `phone`, `company`, `bcc`	Contact and company details	Optional
`metadata`	Your own references, such as an external customer ID	Optional
`search`	Find an existing record before creating one	Optional
`address`	Customer location	Optional; fiscal requirements vary
`legal_name`	Registered name	Optional; fiscal requirements vary
`tax_id`	Recipient identifier: RFC in Mexico, identification number in Colombia	Optional; meaning depends on country

tax_system and use describe Mexican fiscal data. Colombia adds document_type, organization_type, tribute_code, fiscal_responsibilities, dv, and municipality_code. See the country pages for their meaning and behavior.

Shared invoice fields

Both flows use the same invoice routes. The table describes the common structure; the income invoice reference defines exact types and required fields for immediate issuance. Draft creation has different requirements and can accept incomplete information.

Fields	Meaning	What varies by country
`client`	Saved customer ID or embedded customer details	Fiscal identity and address requirements
`currency`, `exchange_rate`	Invoice currency and conversion rate	Local currency and conversion behavior
`items[].description`, `quantity`, `unit_price`	What was sold, how many, and unit price	Fiscal classification and tax treatment
`items[].taxes`	Tax inputs for the line	Supported taxes and provider mapping
`metadata`, `idempotency_key`	Your references and duplicate handling	Check each endpoint’s duplicate behavior
`send_email`, `ignore_emails`, `emails`	Delivery settings where supported	Delivery is separate from issuance
`invoice_pdf_notes`	Document notes	Provider formatting and length limits

Shared names can have different meanings

POST /invoices/income currently requires use, payment_form, and payment_method even for a Colombian issuing team. The request validator accepts the published SAT-style payment codes and PUE / PPD; the Colombian adapter maps those values to its provider. Read the Colombia compatibility fields before adapting a Mexican example. Do not assume a field accepted by the shared schema is used by every country’s provider. The API reference lists accepted input; the country guides explain its fiscal meaning.

Start here

Fields by country

Shared examples

Mexico · CFDI examples

Build and troubleshoot

Invoicing

Customers and payments

Mexico · SAT

Accounts

Mexico · SAT catalogs

Shared fields and country rules

Mexico · CFDI

Colombia · DIAN

Choose the issuing country first

Shared customer fields

Shared invoice fields

Shared names can have different meanings

Mexico · CFDI

Colombia · DIAN

​Choose the issuing country first

​Shared customer fields

​Shared invoice fields

​Shared names can have different meanings

Choose the issuing country first

Shared customer fields

Shared invoice fields

Shared names can have different meanings