> ## 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.
# Get team settings
> Read the authorized team defaults without credential values. PUT on this route patches supplied fields only.
## OpenAPI
````yaml openapi.json GET /teams/{id}/settings
openapi: 3.0.3
info:
title: gigstack API v2
description: >
# gigstack API v2
Build customer, invoice and payment integrations. Start with the
[quickstart](https://docs.gigstack.io/quickstart), then select the [issuing
country](https://docs.gigstack.io/concepts/shared-fields).
## Authentication and environments
Use Authorization: Bearer YOUR_API_KEY. Standard live and test keys use
https://api.gigstack.io/v2. Internal staging uses
https://gigstack-staging-9z9nnaat.uc.gateway.dev/v2 and separate keys. Test
mode is a data mode within an environment; a body field does not switch a
key's mode.
See [authentication](https://docs.gigstack.io/authentication) for key
handling, OAuth team scope and gigstack Connect. Internal partner
provisioning is outside this public contract; health probes have their own
security declarations. Operations marked unavailable have no configured
public gateway route.
## Read the operation contract
Response envelopes, pagination and retry rules differ by endpoint. HTTP
success alone does not prove external fiscal completion or movement of
money. Reconcile ambiguous writes before retrying. Use [responses and
recovery](https://docs.gigstack.io/responses) and the operation's error
codes; document credits and daily limits are not generic retryable rate
limits.
The issuing team's configuration selects Mexico or Colombia; customer
country and currency do not. Read
[Mexico](https://docs.gigstack.io/countries/mexico) or
[Colombia](https://docs.gigstack.io/countries/colombia) before choosing
fiscal fields. Accepted public input differs from a provider's direct
payload.
Examples and schema checks do not imply every operation has been executed
live. [Verification coverage](https://docs.gigstack.io/verification)
distinguishes source review, offline checks and observed staging behavior.
Documentation describes operations and does not authorize execution.
version: 2.0.0
contact:
name: Gigstack API Support
url: https://gigstack.io
email: support@gigstack.io
license:
name: Proprietary
url: https://gigstack.io/terms
termsOfService: https://gigstack.io/terms
servers:
- url: https://api.gigstack.io/v2
description: >
Public API for standard live and test-mode keys. Test data is isolated by
the key mode
(`livemode: false`). Internal staging is a separate deployment and key
store; see
https://docs.gigstack.io/authentication#environments for its base URL.
security:
- bearerAuth: []
externalDocs:
description: Complete API Documentation & Guides
url: https://docs.gigstack.io
paths:
/teams/{id}/settings:
get:
tags:
- Teams
summary: Get team settings
description: >-
Read the authorized team defaults without credential values. PUT on this
route patches supplied fields only.
operationId: getTeamSettings
parameters:
- name: id
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/TeamParameter'
responses:
'200':
description: >-
Operation completed; inspect data for the persisted state and
external delivery status
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: object
nullable: true
properties:
avoid_legal_name_replacer:
type: boolean
nullable: true
enforce_client_country_taxes:
type: boolean
nullable: true
global_invoice_disabled:
type: boolean
nullable: true
example: false
automate_complement_for_ppd_invoices:
example: true
type: boolean
nullable: true
automate_partial_payment_complements:
type: boolean
nullable: true
use_foreign_public_in_usd:
type: boolean
nullable: true
avoid_receipts:
type: boolean
nullable: true
cancel_receipts_on_refunds:
type: boolean
nullable: true
invoice_per_receipt:
type: boolean
nullable: true
allow_notes_on_self_invoice:
type: boolean
nullable: true
allow_product_code_on_self_invoice:
type: boolean
nullable: true
send_invoice_english_pdf:
type: boolean
nullable: true
default_description:
type: string
nullable: true
example: Default invoice description
override_item_description:
type: string
nullable: true
example: Custom item description
invoice_pdf_notes:
type: string
nullable: true
example: Additional notes for PDF
product_key:
type: string
nullable: true
example: '81112209'
unit_key:
example: E48
type: string
nullable: true
unit_name:
type: string
nullable: true
use:
example: G03
type: string
nullable: true
sku:
type: string
nullable: true
addenda:
type: string
nullable: true
custom_payment_description:
type: string
nullable: true
customer_portal_id:
type: string
nullable: true
example: portal_1234567890
force_series:
type: string
nullable: true
avoid_automations_on_currencies:
type: array
nullable: true
items:
type: string
example:
- USD
- EUR
uses_on_self_invoice_portal:
type: array
nullable: true
items:
type: string
example:
- G03
- S01
concepts_catalog:
type: array
nullable: true
items:
type: string
taxes:
type: array
nullable: true
items:
type: object
taxes_usd:
oneOf:
- type: array
nullable: true
items:
type: object
- type: boolean
nullable: true
withholding_taxes:
type: array
nullable: true
items:
type: object
local_taxes:
type: array
items:
type: object
additionalProperties: true
properties: {}
nullable: true
complements:
type: array
nullable: true
items:
type: object
properties:
data:
type: string
nullable: true
description:
type: string
nullable: true
type:
type: string
nullable: true
allowed_product_codes:
type: array
items:
type: object
additionalProperties: false
required:
- key
- description
properties:
key:
type: string
description:
type: string
nullable: true
periodicity:
type: object
nullable: true
properties:
label:
type: string
example: Mes
value:
type: string
example: month
pdf_language:
type: string
enum:
- en
- es
- null
nullable: true
global_invoicing_monthly_cuts:
type: number
enum:
- 2
- 3
- 4
- 5
- null
nullable: true
eom_ppd_threshold_days:
type: integer
nullable: true
minimum: 0
maximum: 31
limit_days_to_pay:
type: integer
minimum: 0
nullable: true
payment_reminders:
type: object
additionalProperties: false
properties:
days:
type: integer
minimum: 0
nullable: true
enabled:
type: boolean
nullable: true
before_body:
type: string
nullable: true
before_subject:
type: string
nullable: true
after_body:
type: string
nullable: true
after_subject:
type: string
nullable: true
nullable: true
reinvoice:
type: object
additionalProperties: false
properties:
window_days:
type: integer
minimum: 0
nullable: true
handler:
type: string
enum:
- credit_note
- cancel_resources
- null
nullable: true
nullable: true
refunds:
type: object
additionalProperties: false
properties:
automatic_refunds:
type: boolean
nullable: true
current_month_handler:
type: string
enum:
- credit_note
- cancel_resources
- null
nullable: true
nullable: true
emails:
type: object
properties:
invoices_bcc:
type: array
nullable: true
items:
type: string
example:
- accounting@example.com
avoid_invoice_emails:
type: boolean
nullable: true
example: false
avoid_test_invoice_emails:
example: true
type: boolean
nullable: true
avoid_receipts_emails:
type: boolean
nullable: true
example: false
email_templates:
type: object
additionalProperties: false
properties:
invoices:
type: object
additionalProperties: false
properties:
es:
type: object
additionalProperties: false
properties:
body:
type: string
nullable: true
subject:
type: string
nullable: true
nullable: true
en:
type: object
additionalProperties: false
properties:
body:
type: string
nullable: true
subject:
type: string
nullable: true
nullable: true
nullable: true
complements:
type: object
additionalProperties: false
properties:
es:
type: object
additionalProperties: false
properties:
body:
type: string
nullable: true
subject:
type: string
nullable: true
nullable: true
en:
type: object
additionalProperties: false
properties:
body:
type: string
nullable: true
subject:
type: string
nullable: true
nullable: true
nullable: true
credit_notes:
type: object
additionalProperties: false
properties:
es:
type: object
additionalProperties: false
properties:
body:
type: string
nullable: true
subject:
type: string
nullable: true
nullable: true
en:
type: object
additionalProperties: false
properties:
body:
type: string
nullable: true
subject:
type: string
nullable: true
nullable: true
nullable: true
payments:
type: object
additionalProperties: false
properties:
es:
type: object
additionalProperties: false
properties:
body:
type: string
nullable: true
subject:
type: string
nullable: true
nullable: true
en:
type: object
additionalProperties: false
properties:
body:
type: string
nullable: true
subject:
type: string
nullable: true
nullable: true
nullable: true
receipts:
type: object
additionalProperties: false
properties:
es:
type: object
additionalProperties: false
properties:
body:
type: string
nullable: true
subject:
type: string
nullable: true
nullable: true
en:
type: object
additionalProperties: false
properties:
body:
type: string
nullable: true
subject:
type: string
nullable: true
nullable: true
nullable: true
receipt_reminders:
type: object
additionalProperties: false
properties:
es:
type: object
additionalProperties: false
properties:
body:
type: string
nullable: true
subject:
type: string
nullable: true
nullable: true
en:
type: object
additionalProperties: false
properties:
body:
type: string
nullable: true
subject:
type: string
nullable: true
nullable: true
nullable: true
nullable: true
default_series:
type: object
properties:
income:
type: object
properties:
serie:
type: string
nullable: true
example: A
complements:
type: object
properties:
serie:
type: string
nullable: true
example: P
credit_note:
type: object
properties:
serie:
type: string
nullable: true
example: NC
success:
type: boolean
message:
type: string
timestamp:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/AuthForbidden'
'404':
description: Resource not found or outside authorized account
'409':
description: State conflict; retrieve the current resource before retrying
'500':
$ref: '#/components/responses/ServerError'
security:
- bearerAuth: []
components:
parameters:
TeamParameter:
name: team
in: query
required: false
schema:
type: string
description: >
**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`
responses:
Unauthorized:
description: >
Authentication failed. Two different bodies can come back with a `401`:
1. **From the authentication layer**, before the endpoint runs: a raw
object with
`message` and — for OAuth access tokens only — `error` / `error_description`. It does
**not** use the standardized envelope (`success` and `timestamp` are absent). Messages:
`Unauthorized` (missing header, missing `Bearer ` prefix, unparseable token),
`Unauthorized, missing team in token`, `Unauthorized, not a master team` and
`Unauthorized, no matched teams` (gigstack Connect), `Invalid access token`,
`Access token has expired. Please refresh your token.`, `Access token has been revoked`.
2. **From the endpoint itself**: the standardized envelope with
`error.code: unauthorized`.
Branch on the HTTP status, not on the body shape.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/AuthMiddlewareError'
- $ref: '#/components/schemas/UnauthorizedError'
examples:
missing_or_invalid_key:
summary: Authentication layer — missing or unparseable API key
value:
message: Unauthorized
oauth_token_expired:
summary: Authentication layer — expired OAuth access token
value:
message: Access token has expired. Please refresh your token.
error: token_expired
error_description: Access token has expired. Please refresh your token.
connect_not_master_team:
summary: >-
Authentication layer — `team` sent by a team without gigstack
Connect
value:
message: Unauthorized, not a master team
endpoint_envelope:
summary: Endpoint — standardized envelope
value:
success: false
error:
code: unauthorized
message: Unauthorized access
timestamp: 1767225600000
AuthForbidden:
description: >
Rejected by the authentication layer after the credential was
recognised. The body is a raw
object (`message`, sometimes `details`), **not** the standardized
envelope. Causes:
- The API key was revoked or disabled: `message: "API Key inválida."`,
`details: "Invalid API Key"`.
- The billing account's plan does not include API access. `message` is a
Spanish sentence
containing an HTML link to `https://app.gigstack.pro/memberships`. Branch on the status
code; do not display or match the text.
- gigstack Connect: the plan lacks the `multipleIssuerAccounts` feature
(Spanish message
starting `Tu plan no incluye múltiples cuentas emisoras.`), or an OAuth access token was
sent with a `team` other than its own (`Team mismatch with OAuth token`).
An endpoint may also answer `403` for its own reasons; those are
documented on the
operation when they exist.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthMiddlewareError'
examples:
revoked_api_key:
summary: API key revoked or disabled
value:
message: API Key inválida.
details: Invalid API Key
plan_without_api_access:
summary: Plan does not include API access
value:
message: >-
La API se encuentra disponible para un plan más grande, por
favor actualiza tu plan aquí o ponte
en contacto con soporte.
connect_plan_without_multiple_issuers:
summary: gigstack Connect — plan lacks multipleIssuerAccounts
value:
message: >-
Tu plan no incluye múltiples cuentas emisoras. Actualiza tu
plan en https://app.gigstack.pro/memberships o ponte en
contacto con soporte para operar sobre otros equipos.
oauth_team_mismatch:
summary: gigstack Connect — OAuth token used for another team
value:
message: Team mismatch with OAuth token
ServerError:
description: >-
Unexpected server error (`error.code: internal_server_error`). The
failure is logged on gigstack's side.
content:
application/json:
schema:
$ref: '#/components/schemas/StandardErrorResponse'
example:
success: false
error:
code: internal_server_error
message: An internal server error occurred
timestamp: 1767225600000
schemas:
AuthMiddlewareError:
type: object
description: >
Raw error body produced by the authentication layer (before any endpoint
runs). It is not
the standardized envelope: there is no `success` and no `timestamp`.
required:
- message
properties:
message:
type: string
description: >-
Human-readable reason. Some messages are in Spanish; branch on the
HTTP status, not on this text.
example: Unauthorized
error:
type: string
description: >-
OAuth error code. Present only when an OAuth access token was
presented.
enum:
- invalid_token
- token_expired
- token_revoked
- server_error
example: token_expired
error_description:
type: string
description: Same text as `message`. Present only alongside `error`.
example: Access token has expired. Please refresh your token.
details:
description: >-
Extra detail, e.g. `Invalid API Key` when a revoked key is rejected
with `403`.
oneOf:
- type: string
- type: object
example: Invalid API Key
UnauthorizedError:
allOf:
- $ref: '#/components/schemas/StandardErrorResponse'
example:
success: false
error:
code: unauthorized
message: Unauthorized access
timestamp: 1767225600000
StandardErrorResponse:
type: object
description: >
Standardized error envelope emitted by `sendErrorResponse` and its
helpers
(`sendValidationError`, `sendNotFoundError`, `sendUnauthorizedError`,
`sendForbiddenError`, `sendConflictError`, `sendBadRequestError`,
`sendInternalServerError`).
required:
- success
- error
- timestamp
properties:
success:
type: boolean
enum:
- false
example: false
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: >
Stable machine-readable code. Values emitted by the shared
helpers:
`unauthorized`, `forbidden`, `invalid_token`,
`validation_failed`,
`invalid_request_body`, `missing_required_field`,
`invalid_field_value`,
`resource_not_found`, `resource_already_exists`,
`resource_conflict`,
`business_rule_violation`, `operation_not_allowed`,
`insufficient_permissions`, `external_service_error`,
`payment_processor_error`, `cfdi_service_error`,
`internal_server_error`, `service_unavailable`,
`rate_limit_exceeded`,
`database_error`, `data_integrity_error`, `file_not_found`,
`file_upload_error`, `invalid_file_format`. Individual handlers
may
emit additional endpoint-specific codes, documented per
operation.
example: validation_failed
message:
type: string
example: Request validation failed
details:
oneOf:
- type: string
- type: array
items:
type: string
description: >
Present only when the handler supplies detail. Validation
failures
emit an array of `": "` strings.
example:
- 'currency: Field is required'
timestamp:
type: integer
format: int64
description: Server time in epoch milliseconds.
example: 1767225600000
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
**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](https://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.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.