> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gigstack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Shared fields and country rules

> Start with the common customer and invoice fields, then add the issuing country's fiscal details.

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

```json theme={null}
{
  "name": "Workshop customer",
  "email": "customer@example.com",
  "metadata": {"external_id": "customer-1042"}
}
```

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

<CardGroup cols={2}>
  <Card title="Mexico · CFDI" icon="file-invoice" href="/countries/mexico">
    RFC, fiscal regime, Uso CFDI, SAT product codes, and payment complements.
  </Card>

  <Card title="Colombia · DIAN" icon="file-invoice" href="/countries/colombia">
    Identification type, NIT, fiscal responsibilities, and municipality codes.
  </Card>
</CardGroup>

## 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](/concepts/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](/guides/gigstack-connect). 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](/reference/createInvoicesIncome) defines exact types
and required fields for immediate issuance. [Draft creation](/reference/createInvoicesDraft)
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](/countries/colombia#invoice-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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.