Create a customer once

Case: your application has customer customer-1042. You want one corresponding client in gigstack, even when a job runs again. Complete the quickstart first. These commands use GIGSTACK_BASE_URL and GIGSTACK_API_KEY from that page, plus jq to read JSON responses.

Create or find the customer

set -euo pipefail
curl --fail-with-body "$GIGSTACK_BASE_URL/clients" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Workshop customer",
    "email": "customer@example.com",
    "metadata": {"external_id": "customer-1042"},
    "search": {
      "on_key": "metadata.external_id",
      "on_value": "customer-1042",
      "update": false
    }
  }' > client.json

CLIENT_ID=$(jq -er '.data.id' client.json)
export CLIENT_ID

Expected: 201 for a new client; 200 when a matching client already exists. Both responses contain data.id. With update: false, finding the customer does not change the stored record. If several records match, resolve the conflict instead of selecting an arbitrary customer. Use a stable identifier from your own system. This lookup helps with repeat jobs; it is not a promise that simultaneous create requests are atomic.

Add fiscal details when you need to invoice

A contact can exist without fiscal data. Choose the issuing country before adding fiscal fields: Mexico or Colombia. The table and test fixture below apply to Mexico. Before issuing a Mexican CFDI, collect:

API field	Ask the customer for
`tax_id`	RFC
`legal_name`	Registered name or razón social
`tax_system`	Régimen fiscal code
`address.zip`	Fiscal postal code, as a string
`address.country`	`MEX` for this Mexican recipient example
`use`	Intended Uso CFDI

A successful client creation is not proof that its fiscal details were validated. Inspect data.fiscal_validation when returned. A contact-only creation can report status: "skipped" because required fiscal fields were not supplied. The SAT lists the required recipient data. Customers can supply those values directly; the CSF document itself is not mandatory. Next: build an invoice draft. For all fields and customer search options, read the client reference.

Test fiscal customer

For the tutorial in a configured Mexican test environment, this synthetic fiscal fixture completed the preview and stamping flow. Use real customer data for real invoices; these sample fiscal values are not a substitute for collecting it.

curl --fail-with-body "$GIGSTACK_BASE_URL/clients" \
  -H "Authorization: Bearer $GIGSTACK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Documentation fiscal example",
    "legal_name": "ESCUELA KEMPER URGATE",
    "tax_id": "EKU9003173C9",
    "tax_system": "601",
    "use": "G03",
    "address": {"country": "MEX", "zip": "42501"},
    "metadata": {"external_id": "fiscal-example-1042"},
    "search": {"on_key": "metadata.external_id", "on_value": "fiscal-example-1042", "update": false}
  }' > fiscal-client.json

CLIENT_ID=$(jq -er '.data.id' fiscal-client.json)
export CLIENT_ID
jq '{id: .data.id, livemode: .data.livemode}' fiscal-client.json

Confirm livemode: false before continuing to the invoice recipe. Complete issuer setup for the provider and test certificates before stamping.

Start here

Fields by country

Shared examples

Mexico · CFDI examples

Build and troubleshoot

Invoicing

Customers and payments

Mexico · SAT

Accounts

Mexico · SAT catalogs

Create a customer once

Create or find the customer

Add fiscal details when you need to invoice

Test fiscal customer

​Create or find the customer

​Add fiscal details when you need to invoice

​Test fiscal customer

Create or find the customer

Add fiscal details when you need to invoice

Test fiscal customer