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

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

{
  "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

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

{
  "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

• Get Merchant

• List Merchants