curl --request PUT \
  --url https://api.gigstack.io/v2/payments/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "id": "service_1234567890",
      "description": "Servicio de consultoría profesional - corregido"
    }
  ]
}
'

{
  "success": true,
  "data": {
    "id": "payment_1234567890",
    "client": {
      "id": "client_1234567890",
      "name": "ESCUELA KEMPER URGATE",
      "legal_name": "ESCUELA KEMPER URGATE",
      "email": "contabilidad@ejemplo.com",
      "bcc": [],
      "phone": "+524421234567",
      "tax_id": "EKU9003173C9",
      "tax_system": "601",
      "use": "G03",
      "address": {
        "street": "Av. Constituyentes",
        "exterior": "1000",
        "neighborhood": "Centro",
        "city": "Querétaro",
        "state": "QRO",
        "zip": "76000",
        "country": "MEX"
      },
      "is_valid": true,
      "efos": {
        "is_valid": true
      },
      "metadata": {},
      "livemode": true,
      "from": "api",
      "owner": "user_1234567890",
      "team": "team_1234567890",
      "created_at": 1767225600000
    },
    "emails": [
      "contabilidad@ejemplo.com"
    ],
    "currency": "MXN",
    "allowed_payment_methods": [
      "card",
      "bank"
    ],
    "exchange_rate": 1,
    "items": [
      {
        "id": "service_1234567890",
        "description": "Servicios de consultoría profesional",
        "quantity": 1,
        "unit_price": 1000,
        "product_key": "80141503",
        "unit_key": "E48",
        "unit_name": "Unidad de servicio",
        "taxes": [
          {
            "type": "IVA",
            "rate": 0.16,
            "factor": "Tasa",
            "withholding": false
          }
        ],
        "team": "team_1234567890",
        "created_at": 1767225600000,
        "from": "api"
      }
    ],
    "metadata": {},
    "team": "team_1234567890",
    "idempotency_key": "payment-2026-0001",
    "from": "api",
    "invoices": [
      "B0C3E4F2-1A2B-4C5D-9E8F-0123456789AB"
    ],
    "livemode": true,
    "owner": "user_1234567890",
    "payment_form": "03",
    "payments": [],
    "receipts": [],
    "refunds": [],
    "short_url": "https://gigstack.xyz/Xk3mP9",
    "success_url": null,
    "status": "succeeded",
    "total": 1160,
    "total_refunded": 0,
    "subtotal": 1000,
    "taxes": 160,
    "discount": 0,
    "withholding_taxes": 0,
    "created_at": 1767225600000,
    "succeeded_at": 1767225900000,
    "payment_processor": "api"
  },
  "message": "Payment updated successfully",
  "timestamp": 1767225600000
}

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed",
    "details": [
      "currency: Field is required",
      "client_id: Unexpected field"
    ]
  },
  "timestamp": 1767225600000
}

{
  "success": false,
  "error": {
    "code": "invalid_request_body",
    "message": "An error occurred"
  },
  "timestamp": 1767225600000
}

{
  "success": false,
  "error": {
    "code": "invalid_request_body",
    "message": "An error occurred"
  },
  "timestamp": 1767225600000
}

Payments

Update payment

Update a payment. The endpoint supports modifying the description of items, attaching automation_type to a payment that has no automations, and patching the embedded client (with the change propagated to the /clients/{id} master record). The body must include at least one of items, automation_type or client.

gigstack Connect: Update other teams’ payments using the team parameter.

What can be updated

Item description: For each entry in items, the item is matched by id inside the payment and its description is replaced. Any other field on the item (taxes, discounts, quantity, unit_price, etc.) is rejected by validation. Item totals, taxes and itemsAmounts are not recalculated.
Automations: automation_type is only accepted when the payment has no existing automations. If the payment already has automations, the request returns 400. The same enum values used by POST /payments/register apply (pue_invoice, ppd_invoice_and_complement, none).
Client: The client object accepts a partial patch (name, company, phone, email, bcc, metadata, legal_name, tax_id, use, tax_system, address). The client id cannot be modified. Each provided field is written both to the client embedded in the payment and to the /clients/{id} master document via a partial merge. Fiscal/SAT validation is not re-run from this endpoint — call PUT /clients/{id} if full re-validation is needed.

Trigger re-fire for already succeeded payments

When non-empty automations are added (i.e. automation_type is pue_invoice or ppd_invoice_and_complement) and the payment is already succeeded, the endpoint performs a second write that sets status to succeeded_ so that the downstream automation trigger (which fires on transitions into succeeded) can re-fire on a subsequent flip back to succeeded.

Allowed payment statuses

The endpoint accepts updates regardless of payment status (including succeeded and cancelled) so descriptions can be corrected after the fact. Note that this endpoint does not re-issue or modify any CFDI already linked to the payment.

PUT

payments

{id}

curl --request PUT \
  --url https://api.gigstack.io/v2/payments/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "id": "service_1234567890",
      "description": "Servicio de consultoría profesional - corregido"
    }
  ]
}
'

{
  "success": true,
  "data": {
    "id": "payment_1234567890",
    "client": {
      "id": "client_1234567890",
      "name": "ESCUELA KEMPER URGATE",
      "legal_name": "ESCUELA KEMPER URGATE",
      "email": "contabilidad@ejemplo.com",
      "bcc": [],
      "phone": "+524421234567",
      "tax_id": "EKU9003173C9",
      "tax_system": "601",
      "use": "G03",
      "address": {
        "street": "Av. Constituyentes",
        "exterior": "1000",
        "neighborhood": "Centro",
        "city": "Querétaro",
        "state": "QRO",
        "zip": "76000",
        "country": "MEX"
      },
      "is_valid": true,
      "efos": {
        "is_valid": true
      },
      "metadata": {},
      "livemode": true,
      "from": "api",
      "owner": "user_1234567890",
      "team": "team_1234567890",
      "created_at": 1767225600000
    },
    "emails": [
      "contabilidad@ejemplo.com"
    ],
    "currency": "MXN",
    "allowed_payment_methods": [
      "card",
      "bank"
    ],
    "exchange_rate": 1,
    "items": [
      {
        "id": "service_1234567890",
        "description": "Servicios de consultoría profesional",
        "quantity": 1,
        "unit_price": 1000,
        "product_key": "80141503",
        "unit_key": "E48",
        "unit_name": "Unidad de servicio",
        "taxes": [
          {
            "type": "IVA",
            "rate": 0.16,
            "factor": "Tasa",
            "withholding": false
          }
        ],
        "team": "team_1234567890",
        "created_at": 1767225600000,
        "from": "api"
      }
    ],
    "metadata": {},
    "team": "team_1234567890",
    "idempotency_key": "payment-2026-0001",
    "from": "api",
    "invoices": [
      "B0C3E4F2-1A2B-4C5D-9E8F-0123456789AB"
    ],
    "livemode": true,
    "owner": "user_1234567890",
    "payment_form": "03",
    "payments": [],
    "receipts": [],
    "refunds": [],
    "short_url": "https://gigstack.xyz/Xk3mP9",
    "success_url": null,
    "status": "succeeded",
    "total": 1160,
    "total_refunded": 0,
    "subtotal": 1000,
    "taxes": 160,
    "discount": 0,
    "withholding_taxes": 0,
    "created_at": 1767225600000,
    "succeeded_at": 1767225900000,
    "payment_processor": "api"
  },
  "message": "Payment updated successfully",
  "timestamp": 1767225600000
}

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed",
    "details": [
      "currency: Field is required",
      "client_id: Unexpected field"
    ]
  },
  "timestamp": 1767225600000
}

{
  "success": false,
  "error": {
    "code": "invalid_request_body",
    "message": "An error occurred"
  },
  "timestamp": 1767225600000
}

{
  "success": false,
  "error": {
    "code": "invalid_request_body",
    "message": "An error occurred"
  },
  "timestamp": 1767225600000
}

Authorizations

Authorization

string

header

required

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

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.

Path Parameters

string

required

Query Parameters

team

string

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

Body

application/json

Body for the PUT /payments/{id} endpoint. At least one of items, automation_type or client must be present.

items: Update the description of one or more items in the payment, matched by item id. Only description can be modified — taxes, discounts, quantities and unit prices are immutable from this endpoint and any other field is rejected.
automation_type: Add automations to a payment that does not have any. If the payment already has automations, the request is rejected with 400. When non-empty automations are added and the payment status is succeeded, the status is flipped to succeeded_ after the update so the automation trigger can re-fire.
client: Update fields of the client embedded in the payment (name, email, fiscal info, address, etc.). The client id cannot be changed. Any provided field is also written to the matching /clients/{id} document via a partial merge, so the client master record stays in sync with the payment. Fiscal/SAT validation is not re-run from this endpoint — use PUT /clients/{id} if you need that.

items

object[] | null

List of items to update. Only the description of each item can be modified.

Minimum array length: 1

Show child attributes

automation_type

enum<string> | null

Automation to attach to the payment. Only allowed if the payment currently has no automations.

Available options:

pue_invoice,

ppd_invoice_and_complement,

none,

null

Example:

"pue_invoice"

invoice_config

object | null

Show child attributes

client

object | null

Partial update for the client embedded in the payment. Only the listed fields can be modified — the client id cannot be changed. Each provided field is propagated to the /clients/{id} master document via a partial merge.

Show child attributes

Response

Payment updated successfully

Standardized success envelope emitted by sendSuccessResponse.

success

enum<boolean>

required

Available options:

true

Example:

true

data

object

required

The operation payload.

timestamp

integer<int64>

required

Server time in epoch milliseconds (Luxon.now().toMillis()).

Example:

1767225600000

message

string

Human-readable summary. Present only when the handler supplies one.

Example:

"Operation completed successfully"

Clients

Services

Descarga Masiva SAT

Invoices

Payments

Receipts

Retentions

Teams

Users

Webhooks

Catalogs

Auth

SAT Lists

Documents

Platform Payouts

Update payment

What can be updated

Trigger re-fire for already succeeded payments

Allowed payment statuses

Authorizations

Path Parameters

Query Parameters

Body

Response