List all sub-merchants

GEThttps://api.omise.co/sub_merchants

Retrieve a paginated list of all sub-merchants belonging to your platform account. Results can be filtered by date range, status, and sorted chronologically.

---

Request Parameters

Recommended - 6 fieldsRecommended Parameters

▼

`limit`INTEGER(optional)

Number of records to return per page.

Example:20

Constraints:Minimum: 1, Maximum: 100

Default:20

`offset`INTEGER(optional)

Number of records to skip before returning results. Used for pagination.

Example:0

Default:0

`order`STRING(optional)

Sort order for results based on creation date.

Example:"chronological"

Values:chronological, reverse_chronological

Default:"chronological"

`status`STRING(optional)

Filter sub-merchants by status.

Example:"active"

Values:pending, active, suspended, deactivated, rejected

`from`STRING(optional)

Filter sub-merchants created on or after this UTC datetime. ISO 8601 format.

Example:"2025-01-01T00:00:00Z"

`to`STRING(optional)

Filter sub-merchants created on or before this UTC datetime. ISO 8601 format.

Example:"2025-12-31T23:59:59Z"

---

Responses

200

Successful request

Sub-merchants list retrieved successfully. Returns paginated list with metadata.

Response structure:

• object - Always "list"
• data - Array of sub-merchant objects
• total - Total number of sub-merchants matching filters
• limit - Number of records per page
• offset - Current pagination offset
• from, to - Applied date filters

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Invalid date format for from or to
• Invalid order value
• Invalid status value
• Negative offset or limit
• limit exceeds maximum (100)

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

Platform account not found or sub-merchant feature not enabled.

Common causes:

• Account is not a platform account
• Sub-merchant feature not enabled
• Contact support to enable platform features

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/sub_merchants \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

sub_merchants = Omise::SubMerchant.list(limit: 20, offset: 0)

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

sub_merchants = omise.SubMerchant.retrieve(limit=20, offset=0)

Node.js

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

const subMerchants = await omise.subMerchants.list({
  limit: 20,
  offset: 0
});

PHP

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

$subMerchants = OmiseSubMerchant::retrieve([
    'limit' => 20,
    'offset' => 0
]);

Java

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

ScopedList<SubMerchant> subMerchants = client.subMerchants()
    .list(new ScopedList.Options()
        .limit(20)
        .offset(0));

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var subMerchants = await client.SubMerchants.List(new ListOptions
{
    Limit = 20,
    Offset = 0
});

Go

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

subMerchants, _ := client.SubMerchants().List(&operations.ListSubMerchants{
    Limit:  20,
    Offset: 0,
})

---

Pagination

Use limit and offset parameters to paginate through results:

# First page (0-19)
curl https://api.omise.co/sub_merchants?limit=20&offset=0 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

# Second page (20-39)
curl https://api.omise.co/sub_merchants?limit=20&offset=20 \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

---

Filtering by status

Filter sub-merchants by their verification status:

# List only active sub-merchants
curl https://api.omise.co/sub_merchants?status=active \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

# List pending sub-merchants
curl https://api.omise.co/sub_merchants?status=pending \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

---

🔑API Credentials

▼

Try it out

Recommended - 6 fields

▼

Your IP: ...Loading...