Update Link

PATCHhttps://api.omise.co/links/:link_id

Update a payment link's properties. You can modify the title, description, and metadata of an existing link. Note that amount and currency cannot be changed after creation.

Request Parameters

Required - 1 fieldRequired Parameters

▼

`link_id`STRING(required)

Link identifier matching pattern /link(_test)?_[0-9a-z]+/. This is provided in the URL path.

Example:"link_test_5xuy4w91xqz7d1w9u0t"

Constraints:Must be a valid link ID

Updatable - 3 fieldsUpdatable Parameters

▼

`title`STRING(optional)

Link name displayed to customers on the payment page.

Example:"Updated Invoice #12345 Payment"

`description`STRING(optional)

Link details and additional context shown to customers.

Example:"Updated payment description for February 2025"

`metadata`OBJECT(optional)

Custom key-value pairs (max 15,000 characters total). Useful for storing order IDs, customer references, or any custom data. Replaces existing metadata.

Example:{"order_id":"1234","customer_email":"john@example.com","updated_at":"2025-02-01"}

---

Responses

200

Successful update

Link updated successfully. Returns the complete updated link object.

Response includes:

• id - Link identifier
• title - Updated link title
• description - Updated link description
• metadata - Updated metadata object
• payment_uri - Shareable URL for customer payment (unchanged)
• amount - Payment amount (unchanged)
• currency - Currency code (unchanged)

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Attempting to update immutable fields (amount, currency)
• Invalid metadata format
• Metadata exceeds size limit
• Invalid data types

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

404

Not found

Link not found with the provided ID.

Common causes:

• Invalid link ID format
• Link does not exist
• Link belongs to different account
• Using test key with live link ID (or vice versa)

5xx

Server error

Server-side error occurred. These are rare but should be handled gracefully.

How to handle:

• Retry the request with exponential backoff
• Check status.omise.co for service incidents
• See Error Handling for detailed guidance

---

Code samples

cURL

curl https://api.omise.co/links/link_test_5xuy4w91xqz7d1w9u0t \
  -X PATCH \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -d "title=Updated Invoice #12345 Payment" \
  -d "description=Updated payment description for February 2025"

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

link = Omise::Link.retrieve('link_test_5xuy4w91xqz7d1w9u0t')
link = link.update(
  title: 'Updated Invoice #12345 Payment',
  description: 'Updated payment description for February 2025'
)

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

link = omise.Link.retrieve('link_test_5xuy4w91xqz7d1w9u0t')
link.update(
    title='Updated Invoice #12345 Payment',
    description='Updated payment description for February 2025'
)

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t'
});

const link = await omise.links.update('link_test_5xuy4w91xqz7d1w9u0t', {
  title: 'Updated Invoice #12345 Payment',
  description: 'Updated payment description for February 2025'
});

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$link = OmiseLink::retrieve('link_test_5xuy4w91xqz7d1w9u0t');
$link->update([
    'title' => 'Updated Invoice #12345 Payment',
    'description' => 'Updated payment description for February 2025'
]);

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

Link link = client.links().update("link_test_5xuy4w91xqz7d1w9u0t")
    .title("Updated Invoice #12345 Payment")
    .description("Updated payment description for February 2025")
    .send();

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var link = await client.Links.Update("link_test_5xuy4w91xqz7d1w9u0t", new UpdateLinkRequest
{
    Title = "Updated Invoice #12345 Payment",
    Description = "Updated payment description for February 2025"
});

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

link, _ := client.Links().Update("link_test_5xuy4w91xqz7d1w9u0t", &operations.UpdateLink{
    Title:       "Updated Invoice #12345 Payment",
    Description: "Updated payment description for February 2025",
})

---

Error and result codes

Common Error Codes

Code	Description	Resolution
authentication_failure	Invalid API key	Verify your secret key is correct
not_found	Link not found	Check link ID is correct and exists
invalid_link_id	Malformed link ID	Ensure ID matches format link(test)?[0-9a-z]+
immutable_field	Cannot update field	Amount and currency cannot be changed
invalid_metadata	Metadata validation failed	Check metadata format and size limits

Updatable vs Immutable Fields

Field	Updatable	Notes
title	Yes	Display name for customers
description	Yes	Additional context for customers
metadata	Yes	Replaces existing metadata entirely
amount	No	Cannot be changed after creation
currency	No	Cannot be changed after creation
multiple	No	Cannot be changed after creation

---

🔑API Credentials

▼

Try it out

Required - 1 fields

▼

link_id(Required)

Additional - 3 fields

▼

Your IP: ...Loading...