Skip to main content
Move one business workflow at a time, beginning with reads and test-mode records. Keep the old integration available until the new one produces the expected result. Changing the base URL alone is not enough: v2 has different resource routes, payload fields, pagination and operation-specific side effects. This guide describes the current v2 contract. Compare it with the v1 requests your application actually sends; v1 integrations do not all have the same wrappers or response assumptions. The archived v1 reference is historical context, not a contract for v2.

1. Inventory the existing integration

For each workflow, record the method and path, credential environment, owning team, request shape, saved identifiers, response checks, retry behavior and downstream effects. Include background jobs and webhook consumers, not just interactive screens. Use the API reference for exact methods, bodies and responses. An operation with an availability warning is not accessible through the public gateway, even if a backend handler exists.

2. Set the environment and credential

The public v2 base URL is https://api.gigstack.io/v2 for both standard live and test API keys. A test key selects test data; it is not an internal staging key. Internal staging is a different deployment with its own URL and credentials. See authentication and environments. Create a test key in API settings, then load it locally in Bash rather than embedding it in source code:
Expect HTTP 200 and a data array. Empty test data is valid. curl exits 22 on an HTTP error with --fail-with-body; inspect the saved response before proceeding. Do not send keys from browser code. Account signup uses a separate partner credential, and public health routes are separate from authenticated resource calls.

3. Update response and error handling

Most responses have success, data and a millisecond timestamp, but this is not universal. Authentication failures, fiscal issuance and some SAT endpoints use other shapes. Check the HTTP status first and then parse the operation’s documented body. A successful status code alone may acknowledge asynchronous work. Do not turn every 400 into “fix your input.” A repeated payment or receipt creation key can return 400 resource_conflict for an already-existing record. See responses and retries, troubleshooting, and the resource’s error-handling section.

4. Replace pagination loops

For ordinary cursor lists, send the previous response’s next back as next, keeping all other filters. Stop when has_more is false. Metadata-filtered lists and search can use page-based pagination; SAT invoices and nested batch/document responses have other names. Do not reuse a cursor loop blindly across resources. The following is a complete read-only customer-list example for Node.js with built-in fetch. Save it as list-clients.mjs, with the environment variables from step 2 already exported. It counts records rather than printing customer data.
Run node list-clients.mjs. Exit code 0 means the loop reached its final page; a nonzero exit means the export is incomplete. The example intentionally adds no metadata filter. For one, use the endpoint’s page-based response and page parameter instead. A live listing is not a transactional snapshot: reconcile changes that occur during a long export.

5. Migrate one complete test workflow

Use the customer recipe, then select the issuing country: Mexico or Colombia. The team’s invoicing configuration selects the provider; the recipient’s address.country does not. For a Mexican issuer, run these steps with your own test-mode records:
  1. Create or find a customer using a stable reference from your application. Save the returned ID; resolve ambiguous matches rather than picking the first result.
  2. Supply valid fiscal data before issuance. Customer creation alone is not fiscal validation. The recipe includes a separate Mexican test fixture.
  3. Follow draft, preview, and issue. Keep the original request body so a later draft update can send all intended fields.
  4. If money was received, follow payment registration. Choose invoice automation deliberately to avoid issuing the sale twice.
  5. If the invoice is paid later, follow the PPD recipe and check the complement and remaining balance, not only the payment’s creation status.
  6. Exercise your parser with redacted success/error fixtures and your retry logic with timeout simulations before enabling real writes.
The Colombia guide documents current public-schema compatibility and limitations. The Mexican recipe verification is not evidence of a completed Colombian flow.

Side effects to preserve or disable deliberately

6. Move webhooks and retries

Build the new webhook receiver before redirecting production traffic. Read webhook payload versions and delivery behavior: resource events are unsigned, while SAT-sync and batch-completion events can carry signatures and are sent only once. A secret returned by webhook creation does not sign every event. Persist verified notifications before acknowledgment and use a durable worker. V2 has a stable delivery id; v1 has no unique delivery ID, so event + data.id is not a safe permanent deduplication key for repeated updates. Reconcile current resource state and protect your own side effects with business identifiers. For API retries, keep an operation’s existing idempotency key for the same business event. Do not invent a universal Idempotency-Key header: batch creation and some other operations use that header; payment/invoice creation can use a body field; refund and cancellation have no documented equivalent. After an ambiguous write, read and reconcile before repeating it.

7. Cut over and verify

First compare read results between your application and the v2 integration using known identifiers and amounts. Then enable one workflow for a small, deliberate scope. Monitor failures, duplicate business references, pending asynchronous work and webhook inbox age. Keep the previous application version deployable. A rollback of your application does not undo a payment, issued fiscal document or refund. Preserve the IDs and completed results from the cutover period so the old integration does not submit those business events again. Do not run both writers for the same sale while comparing them. Before declaring the migration complete, verify:
  • Correct environment, team and mode on returned records.
  • Full pagination without silently stopping at the first page.
  • Exact amount units, taxes and resulting totals for your workflows.
  • Successful asynchronous results, not merely accepted requests.
  • Duplicate and timeout handling for each write operation.
  • Webhook authentication, durable intake, worker recovery and missed-event reconciliation.
  • Customer delivery settings and every intended automation.

v1 retirement and support

This guide does not publish a confirmed v1 retirement date. Ask gigstack for the current policy that applies to your integration before scheduling a mandatory cutover; placeholder dates are not a deprecation notice. For help, contact support@gigstack.io with the method, path, environment, time, HTTP status and a redacted error body. Include a resource or process reference when appropriate, but never API keys, signing secrets, certificates or signed download URLs. See verification coverage for what the published recipes actually tested.