---
updatedAt: 2026-08-14T20:14:31.000Z
agentTools:
  projectIndex: https://docs.staxpayments.com/llms.txt
---

# Unlink User from Merchant

Revokes a user's access to a specific merchant by soft-deleting the membership record. Only the specified merchant is affected — the user's access to other merchants and the user record itself are never modified. Revocation takes effect immediately: once this call succeeds, the target user is rejected on every merchant-guarded route for that merchant, even when presenting a session token issued before the revocation. The caller must be an active admin of the merchant, or a system_admin. A caller cannot revoke their own access to the merchant they are currently acting on (self-lockout prevention). Removing the last admin from a merchant is blocked for non-system_admin callers.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "stax-api",
    "version": "0.1"
  },
  "servers": [
    {
      "url": "https://apiprod.fattlabs.com/"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "API key for merchant-level operations. Provides access to merchant-specific endpoints including transactions, payments, customer management, and merchant account settings. This key is scoped to a single merchant account and cannot access partner-level functionality."
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/team/user/{userId}/merchants/{merchantId}": {
      "delete": {
        "summary": "Unlink User from Merchant",
        "description": "Revokes a user's access to a specific merchant by soft-deleting the membership record. Only the specified merchant is affected — the user's access to other merchants and the user record itself are never modified. Revocation takes effect immediately: once this call succeeds, the target user is rejected on every merchant-guarded route for that merchant, even when presenting a session token issued before the revocation. The caller must be an active admin of the merchant, or a system_admin. A caller cannot revoke their own access to the merchant they are currently acting on (self-lockout prevention). Removing the last admin from a merchant is blocked for non-system_admin callers.",
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "description": "The ID of the user whose merchant access is being revoked.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "merchantId",
            "in": "path",
            "required": true,
            "description": "The ID of the merchant to revoke access from.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Access revoked successfully, or the membership was already revoked (idempotent).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "merchant_id": {
                      "type": "string"
                    },
                    "user_id": {
                      "type": "string"
                    },
                    "outcome": {
                      "type": "string",
                      "enum": [
                        "revoked",
                        "already_revoked"
                      ],
                      "description": "`revoked` if an active membership was soft-deleted, `already_revoked` if the membership was already inactive."
                    },
                    "merchants": {
                      "type": "array",
                      "description": "The target user's remaining active memberships, restricted to merchants the caller is authorized to see.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "merchant_id": {
                            "type": "string"
                          },
                          "company_name": {
                            "type": "string",
                            "nullable": true
                          },
                          "team_role": {
                            "type": "string"
                          },
                          "is_default": {
                            "type": "boolean"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller is not an active admin of this merchant.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "The user has never been attached to this merchant (no membership record exists at all).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation failed. Possible reasons include: unknown merchant or user ID, attempting to revoke your own access on the merchant you are currently using, or attempting to remove the last admin from a merchant (non-system_admin callers only).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```