> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/entity-management/merchant-management/update-merchant.md). # Update Merchant Use these endpoints to submit and track requests to update a merchant record after KYB approval. Update requests go through an approval workflow before changes are applied, and support scheduled and time-limited updates. ### How update requests work An update request captures a proposed change to a merchant record. Rather than applying changes directly, the request enters an approval queue. Once approved, Bead applies the changes automatically. If `effectiveAt` is set, the change applies at the scheduled time. If `expiresAt` is set, the change is reverted when that time passes. This workflow is appropriate for changes to merchant details, fee configuration, merchant status, pinned status, or removal requests. ### Endpoints ``` POST /Merchants/{merchantId}/update-requests GET /Merchants/{merchantId}/update-requests ``` *** ### Create Update Request Submits a new update request for a merchant. Set `submit: true` to enter the request into the approval queue immediately. Set `submit: false` to create the request in DRAFT status for later review or submission. #### Authentication ``` X-Api-Key: {adminApiKey} ``` #### Path parameter | Name | Type | Required | Description | | ---------- | ------ | -------- | --------------------------------- | | merchantId | string | Yes | The ID of the merchant to update. | #### Request body | Field | Type | Required | Description | | --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | submit | boolean | Yes | If true, the request is submitted for approval immediately. If false, the request is created in DRAFT status. | | precedence | integer | Yes | Priority level used when multiple update requests have overlapping time windows. Higher values take priority. Default is 100. | | changes | object | Yes | The changes to apply to the merchant. See changes object below. | | clientReference | string | No | Optional reference string for external tracking. | | effectiveAt | string (RFC3339 UTC) | No | When the changes should take effect. If omitted, changes apply immediately upon approval. | | expiresAt | string (RFC3339 UTC) | No | When the changes should expire and be reverted. Optional. | #### Changes object | Field | Type | Description | | --------------- | ------- | ------------------------------------------------------------------------------------------ | | merchantDetails | object | Updated merchant profile fields such as company name, description, or contact information. | | fee | object | Updated fee configuration for the merchant. | | status | string | Updated merchant status. Accepts a valid merchant status value. | | setPinned | boolean | Sets the pinned status of the merchant account. | | requestRemoval | boolean | Requests soft deletion of the merchant and its terminals and locations. | | removalReason | string | Reason for the removal request. Required when requestRemoval is true. | #### Example request ```bash curl -X POST "https://api.test.devs.beadpay.io/Merchants/{merchantId}/update-requests" \ -H "X-Api-Key: {adminApiKey}" \ -H "Content-Type: application/json" \ -d '{ "submit": true, "precedence": 100, "clientReference": "your-internal-ref-001", "effectiveAt": null, "expiresAt": null, "changes": { "merchantDetails": { "companyName": "Acme Coffee Roasters Inc" } } }' ``` #### Successful response — 200 ```json { "requestId": "ureq_abc123", "merchantId": "mer_123123", "clientReference": "your-internal-ref-001", "status": "submitted", "requesterId": "user_ab12", "createdAt": "2025-07-01T12:00:00Z" } ``` #### Response fields | Field | Description | | --------------- | ---------------------------------------------------------------------------- | | requestId | The unique ID of the update request. Store this to track the request status. | | merchantId | The ID of the merchant this request applies to. | | clientReference | The client reference you supplied, if any. | | status | The current status of the request. See status lifecycle below. | | requesterId | The ID of the user who created the request. | | createdAt | Timestamp when the request was created. | #### Request status lifecycle | Status | Meaning | | --------- | ----------------------------------------------------------------------------------- | | draft | The request was created with submit: false and has not been submitted for approval. | | submitted | The request is in the approval queue. | | approved | The request has been approved and is pending application. | | applied | The changes have been applied to the merchant record. | | rejected | The request was not approved. No changes were applied. | | expired | The request reached its expiresAt time and was reverted or not applied. | | cancelled | The request was cancelled before approval or application. | #### Error responses | Code | Condition | | ---- | ---------------------------------------------------------------------------- | | 400 | Request body is missing required fields or contains invalid values. | | 401 | Missing or invalid API key. | | 403 | Authenticated but not permitted to submit update requests for this merchant. | | 404 | Merchant does not exist or is not visible to your key. | ### List Update Requests Returns a paginated list of update requests for a merchant, with optional filters by status, date range, and search term. #### Authentication ``` X-Api-Key: {adminApiKey} ``` #### Path parameter | Name | Type | Required | Description | | ---------- | ------ | -------- | --------------------------------------------------------- | | merchantId | string | Yes | The ID of the merchant whose update requests to retrieve. | #### Query parameters | Parameter | Type | Description | | --------- | ---------------- | ------------------------------------------------------------------------------------- | | Statuses | array of strings | Filter by one or more request statuses. Returns the union across all supplied values. | | Search | string | Free text search across merchant name, request ID, and merchant display ID (MID). | | From | string | Filter by requests submitted on or after this date. | | To | string | Filter by requests submitted on or before this date. | | Page | integer | Page number. Starts at 1. | | PageSize | integer | Number of results per page. | #### Example request ```bash curl -X GET "https://api.test.devs.beadpay.io/Merchants/{merchantId}/update-requests?Statuses=submitted&Statuses=approved&Page=1&PageSize=25" \ -H "X-Api-Key: {adminApiKey}" ``` #### Successful response — 200 ```json { "data": [ { "requestId": "ureq_abc123", "merchantId": "mer_123123", "clientReference": "your-internal-ref-001", "status": "submitted", "requesterId": "user_ab12", "createdAt": "2025-07-01T12:00:00Z" } ], "total": 1, "page": 1 } ``` #### Response fields | Field | Description | | ----- | ------------------------------------------------------------------------------------------ | | data | Array of update request objects. Each object follows the same schema as the POST response. | | total | Total number of matching requests across all pages. | | page | The current page number returned. | #### Error responses | Code | Condition | | ---- | -------------------------------------------------------------------------- | | 401 | Missing or invalid API key. | | 403 | Authenticated but not permitted to view update requests for this merchant. | | 404 | Merchant does not exist or is not visible to your key. | ### Best practices Store `requestId` when creating a request so you can look it up or reference it later. Use `clientReference` to tie a Bead update request back to an action or record in your own system. Use `submit: false` when you want to stage a change for review before it enters the approval queue. Use `effectiveAt` when a change needs to take effect at a specific future time rather than immediately upon approval. Use `expiresAt` for temporary changes that should be automatically reverted. Use the `Statuses` filter when listing requests to focus on requests that are pending action such as submitted or approved. Check `status` after submitting to confirm whether the request entered the approval queue or requires additional action. ### Related pages * [Merchant Management](/entity-management/merchant-management.md) * [Get Merchant](/entity-management/merchant-management/get-merchant.md) * [List Merchants](/entity-management/merchant-management/list-merchants.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/entity-management/merchant-management/update-merchant.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.