Skip to main content
Version: 2019-05-29 (Current)

Search API

Overviewโ€‹

The Search API provides a powerful way to search across all your Omise resources using full-text search capabilities. Find charges, customers, disputes, recipients, and more using keywords, metadata, or specific fields.

Available Endpointโ€‹

What You Can Doโ€‹

  • Full-Text Search - Search by keywords across all resources
  • Scope-Based Search - Limit search to specific resource types
  • Metadata Search - Find resources by custom metadata values
  • Card Search - Find charges by card last 4 digits
  • Customer Search - Find by email, name, or description
  • Date Filtering - Combine search with date ranges
  • Pagination - Navigate through large result sets

Searchable Resourcesโ€‹

Chargesโ€‹

Search charges by:

  • Description
  • Metadata values
  • Card last 4 digits
  • Customer email
  • Reference numbers
  • Failure messages

Customersโ€‹

Search customers by:

  • Email address
  • Description
  • Metadata values
  • Name (from cards)

Disputesโ€‹

Search disputes by:

  • Charge description
  • Reason code
  • Metadata
  • Customer information

Recipientsโ€‹

Search recipients by:

  • Name
  • Email
  • Bank account name
  • Description
  • Metadata

Refundsโ€‹

Search refunds by:

  • Related charge description
  • Metadata values

Search Scopesโ€‹

Specify which resource types to search:

  • charge - Search only charges
  • customer - Search only customers
  • dispute - Search only disputes
  • recipient - Search only recipients
  • refund - Search only refunds
  • transfer - Search only transfers

Use Casesโ€‹

Find Charges by Descriptionโ€‹

GET /search?scope=charge&query=order+12345

Find Customer by Emailโ€‹

GET /search?scope=customer&query=john@example.com

Find Charges by Card Last 4โ€‹

GET /search?scope=charge&query=4242

Search Metadataโ€‹

GET /search?scope=charge&query=order_id:12345
GET /search?query=john@example.com
# Returns all resources matching the email

Example Usageโ€‹

Search for a Specific Orderโ€‹

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

// Search charges by order ID in metadata
const results = await omise.search.list({
  scope: 'charge',
  query: 'order_id:ORD-12345',
  limit: 10
});

console.log(`Found ${results.total} charges`);
results.data.forEach(charge => {
  console.log(`Charge: ${charge.id}, Amount: ${charge.amount}`);
});

Find All Charges for a Customerโ€‹

import omise

omise.api_secret = 'skey_test_...'

# Search by customer email
results = omise.Search.execute(
    scope='charge',
    query='customer@example.com',
    limit=50
)

print(f'Found {results["total"]} charges')
for charge in results['data']:
    print(f'Charge {charge["id"]}: {charge["amount"]} {charge["currency"]}')

Search with Date Filtersโ€‹

# Find charges in February containing "subscription"
curl "https://api.omise.co/search?scope=charge&query=subscription&from=2025-02-01T00:00:00Z&to=2025-02-28T23:59:59Z" \
  -u skey_test_YOUR_SECRET_KEY:

Search Query Syntaxโ€‹

query=keyword

Searches all fields for the keyword.

query=email:john@example.com
query=description:order
query=metadata.order_id:12345

Multiple Keywordsโ€‹

query=john+doe
query=order+12345

Uses AND logic - finds resources matching all keywords.

Exact Phrasesโ€‹

query="Blue T-Shirt"

Searches for exact phrase match.

Response Formatโ€‹

{
  "object": "search",
  "data": [
    {
      "object": "charge",
      "id": "chrg_test_5xuy4w91xqz7d1w9u0t",
      "amount": 100000,
      "currency": "thb",
      "description": "Order #12345 - Blue T-Shirt",
      "metadata": {
        "order_id": "12345"
      },
      ...
    }
  ],
  "total": 1,
  "from": "2025-01-01T00:00:00Z",
  "to": "2025-02-07T23:59:59Z",
  "limit": 20,
  "page": 1
}

Paginationโ€‹

Search results are paginated:

# First page
GET /search?query=order&limit=20&page=1

# Second page
GET /search?query=order&limit=20&page=2

Calculate total pages:

const totalPages = Math.ceil(results.total / results.limit);

Best Practicesโ€‹

โœ… Do Thisโ€‹

  • Use specific scopes - Search single resource types for better performance
  • Add date filters - Narrow results with from/to parameters
  • Use metadata search - Structure searchable data in metadata
  • Implement pagination - Handle results in manageable chunks
  • Cache search results - Cache for short periods (1-5 minutes)
  • Sanitize queries - Validate and escape user input

โŒ Don't Do Thisโ€‹

  • Don't search without scope - Always specify a scope when possible
  • Don't use for real-time lookups - Use direct GET requests for known IDs
  • Don't skip pagination - Always handle paginated results
  • Don't over-rely on search - Use for finding, not for regular retrieval
  • Don't search too broadly - Use filters to narrow results

Performance Tipsโ€‹

Index Your Metadataโ€‹

Structure metadata for efficient searching:

// Good - searchable structure
metadata: {
  order_id: 'ORD-12345',
  customer_email: 'john@example.com',
  product_sku: 'TSHIRT-BLUE-L'
}

// Less efficient - nested structures harder to search
metadata: {
  order: {
    id: '12345',
    customer: { email: 'john@example.com' }
  }
}

Use Appropriate Limitsโ€‹

// For UI display
const results = await omise.search.list({
  query: 'keyword',
  limit: 20  // Good for initial display
});

// For exports
const results = await omise.search.list({
  query: 'keyword',
  limit: 100  // Fewer API calls for large exports
});

Common Questionsโ€‹

What fields are searchable?โ€‹

All text fields including descriptions, metadata values, email addresses, card last 4 digits, and reference numbers.

Is search case-sensitive?โ€‹

No, search is case-insensitive.

How are results ranked?โ€‹

Results are ranked by relevance, with exact matches ranked higher.

Can I use wildcards?โ€‹

No, wildcard search is not supported. Use partial keywords instead.

How recent is the search index?โ€‹

The search index is updated within 1-2 seconds of resource creation/update.

See Alsoโ€‹

Need help? Contact support@omise.co