Skip to main content
PATCH
Update a payment link
Only ACTIVE links can be updated. Updating a cancelled, expired, or consumed link returns 409 INVALID_STATE.
Include only the fields you want to change. Each redirect_urls entry can be updated individually without affecting the others.

Authorizations

X-API-Key
string
header
required

API key enabled for the requested payment-link operation and associated with an eligible partner, merchant, or branch account.

Path Parameters

id
string<uuid>
required

The payment link ID (UUID v7).

Body

application/json

Include only the fields you want to change. currency, amount, line_items, and merchant_branch_reference_number cannot be updated. type is read-only and derived from max_uses.

description
string | null

New description. A supplied string must contain at least one non-whitespace character and be at most 500 characters. Send null to clear it.

Maximum string length: 500
Example:

"Updated order description"

order_reference
string | null

New order reference. String, max 100 characters. null clears it.

Maximum string length: 100
Example:

"ORD-2026-0618-002"

redirect_urls
object | null

Each URL must use HTTPS. Update individual members without changing the others; set a member to null to clear it, or set redirect_urls to null to clear all three.

max_uses
integer | null

Update the usage cap. Integer >= 1, null means unlimited. Link type is immutable: a ONE_TIME link's max_uses stays 1, and a MULTI_USE link's max_uses cannot be set to 1.

Required range: x >= 1
Example:

20

expires_at
string<date-time>

Must be in the future and later than the current expires_at.

Example:

"2026-08-18T00:00:00Z"

metadata
object | null

Merges supplied keys into existing metadata. An empty-string value deletes that key, null clears all metadata, and {} makes no change. Max 50 keys, key max 40 Unicode characters, value max 500 Unicode characters, and max 10,000 serialized bytes.

Response

The updated payment link

The payment link object returned by all endpoints.

id
string<uuid>
required

Unique identifier (UUID v7). Use this in API paths and for tracking.

Example:

"550e8400-e29b-41d4-a716-446655440000"

type
enum<string>
required

Payment-link usage model. ONE_TIME accepts one successful payment; MULTI_USE can accept multiple successful payments.

Available options:
ONE_TIME,
MULTI_USE
merchant_branch_reference_number
string
required

Reference number of the branch this link belongs to.

Example:

"SH-ANG-001"

currency
string
required

ISO 4217 currency code.

Example:

"PHP"

amount
integer<int64>
required

Payment amount in the currency's smallest unit (for PHP, centavos). 150000 = PHP 1,500.00.

Example:

150000

line_items
object[]
required

Items the customer is paying for.

description
string | null
required

Merchant-defined description displayed to the customer.

Example:

"Order for wireless earbuds"

status
enum<string>
required

Current payment-link lifecycle status.

Available options:
ACTIVE,
CONSUMED,
EXPIRED,
CANCELLED
expires_at
string<date-time>
required

RFC 3339 timestamp. When the link stops accepting payments.

Example:

"2026-07-18T00:00:00Z"

url
string<uri>
required

The URL to share with customers. Read-only.

Example:

"https://pay.sbx.moduluslabs.io/550e8400-e29b-41d4-a716-446655440000"

max_uses
integer | null
required

Maximum number of successful payments allowed. null means unlimited. ONE_TIME links always have a value of 1.

Example:

10

successful_payment_count
integer
required

Number of successful payments completed so far.

Example:

3

metadata
object
required

Merchant key-value pairs. Max 50 keys, key max 40 Unicode characters, value max 500 Unicode characters, and max 10,000 serialized bytes.

created_at
string<date-time>
required

RFC 3339 timestamp. When the link was created.

Example:

"2026-06-18T10:30:00Z"

updated_at
string<date-time>
required

RFC 3339 timestamp. When the link was last modified.

Example:

"2026-06-18T14:22:00Z"

cancelled_at
string<date-time> | null
required

RFC 3339 timestamp. When the link was cancelled. null if not cancelled.

cancellation_reason
string | null
required

Reason for cancellation. null if not cancelled.

Maximum string length: 500
order_reference
string | null

Merchant's internal order reference for reconciliation.

Maximum string length: 100
Example:

"ORD-2026-0618-001"

redirect_urls
object | null

Customer redirect destinations for successful, declined, or expired outcomes. null when no redirects are configured.