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 ishttps://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:
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 havesuccess, 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’snext 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.
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’saddress.country does not.
For a Mexican issuer, run these steps with your own test-mode records:
- 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.
- Supply valid fiscal data before issuance. Customer creation alone is not fiscal validation. The recipe includes a separate Mexican test fixture.
- Follow draft, preview, and issue. Keep the original request body so a later draft update can send all intended fields.
- If money was received, follow payment registration. Choose invoice automation deliberately to avoid issuing the sale twice.
- If the invoice is paid later, follow the PPD recipe and check the complement and remaining balance, not only the payment’s creation status.
- Exercise your parser with redacted success/error fixtures and your retry logic with timeout simulations before enabling real writes.
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 deliveryid; 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.