Get a UCP merchant by domain or merchant id

curl --request GET \
  --url https://api.sumvin.com/v0/ucp/merchants/{merchant} \
  --header 'x-sumvin-ucp-token: <api-key>'

const options = {method: 'GET', headers: {'x-sumvin-ucp-token': '<api-key>'}};

fetch('https://api.sumvin.com/v0/ucp/merchants/{merchant}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sumvin.com/v0/ucp/merchants/{merchant}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-sumvin-ucp-token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sumvin.com/v0/ucp/merchants/{merchant}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-sumvin-ucp-token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sumvin.com/v0/ucp/merchants/{merchant}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-sumvin-ucp-token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "_links": {
    "about": {
      "href": "https://shop.example.com"
    },
    "collection": {
      "href": "/v0/ucp/merchants"
    },
    "describedby": {
      "href": "https://shop.example.com/.well-known/ucp"
    },
    "self": {
      "href": "/v0/ucp/merchants/shop.example.com"
    }
  },
  "data": {
    "domain": "shop.example.com",
    "merchant": {
      "categories": [
        "apparel"
      ],
      "locale": {
        "country": "US",
        "language": "en"
      },
      "name": "Example Shop"
    },
    "merchant_id": "k3jf7q2xmn4pz",
    "meta": {
      "first_hit_at": 1704067200000,
      "last_hit_at": 1706745600000
    },
    "ucp": {
      "a2a": {
        "enabled": true
      },
      "capabilities": [
        "dev.ucp.shopping.checkout"
      ],
      "oauth": {
        "enabled": false
      },
      "payment_handlers": [
        "com.google.pay"
      ],
      "services": [
        {
          "endpoint": "https://example-shop.myshopify.com/api/ucp/mcp",
          "namespace": "dev.ucp.shopping",
          "transport": "mcp"
        },
        {
          "endpoint": "",
          "namespace": "dev.ucp.shopping",
          "transport": "embedded"
        }
      ],
      "transports": [
        "mcp",
        "embedded"
      ],
      "version": "2026-04-08"
    }
  }
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

Merchants

Get a UCP merchant by domain or merchant id

Fetch a single UCP merchant by either its domain (e.g. shop.example.com) or its merchant_id. The merchant_id is the short identifier returned on every merchant resource; passing it resolves the merchant directly, so a caller that already holds a record can look it up without knowing the domain.

A merchant_id is derived from the merchant’s domain, so a merchant that moves to a new domain is issued a new one. Two domains could in principle derive the same id, though it is vanishingly unlikely; were that to happen, the id would resolve to one of them. Look up by domain when an exact match is required.

The two forms have different freshness guarantees. A merchant_id reads the record directly and always sees the latest write. A domain is resolved through the search index, which updates a moment later, so a newly indexed merchant may briefly be retrievable by id before it is retrievable by domain.

ucp.services gives the endpoints the merchant’s UCP servers are reachable at, one per service and transport. Those endpoints frequently sit on a different host from the merchant’s domain.

GET

ucp

merchants

{merchant}

Get a UCP merchant by domain or merchant id

curl --request GET \
  --url https://api.sumvin.com/v0/ucp/merchants/{merchant} \
  --header 'x-sumvin-ucp-token: <api-key>'

const options = {method: 'GET', headers: {'x-sumvin-ucp-token': '<api-key>'}};

fetch('https://api.sumvin.com/v0/ucp/merchants/{merchant}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sumvin.com/v0/ucp/merchants/{merchant}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-sumvin-ucp-token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sumvin.com/v0/ucp/merchants/{merchant}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-sumvin-ucp-token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sumvin.com/v0/ucp/merchants/{merchant}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-sumvin-ucp-token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "_links": {
    "about": {
      "href": "https://shop.example.com"
    },
    "collection": {
      "href": "/v0/ucp/merchants"
    },
    "describedby": {
      "href": "https://shop.example.com/.well-known/ucp"
    },
    "self": {
      "href": "/v0/ucp/merchants/shop.example.com"
    }
  },
  "data": {
    "domain": "shop.example.com",
    "merchant": {
      "categories": [
        "apparel"
      ],
      "locale": {
        "country": "US",
        "language": "en"
      },
      "name": "Example Shop"
    },
    "merchant_id": "k3jf7q2xmn4pz",
    "meta": {
      "first_hit_at": 1704067200000,
      "last_hit_at": 1706745600000
    },
    "ucp": {
      "a2a": {
        "enabled": true
      },
      "capabilities": [
        "dev.ucp.shopping.checkout"
      ],
      "oauth": {
        "enabled": false
      },
      "payment_handlers": [
        "com.google.pay"
      ],
      "services": [
        {
          "endpoint": "https://example-shop.myshopify.com/api/ucp/mcp",
          "namespace": "dev.ucp.shopping",
          "transport": "mcp"
        },
        {
          "endpoint": "",
          "namespace": "dev.ucp.shopping",
          "transport": "embedded"
        }
      ],
      "transports": [
        "mcp",
        "embedded"
      ],
      "version": "2026-04-08"
    }
  }
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

Authorizations

x-sumvin-ucp-token

string

header

required

Org-scoped key for the UCP Merchant Search endpoints. Sent in the x-sumvin-ucp-token header.

Headers

X-Timestamp-Format

string

Controls how timestamp fields are serialized in JSON response bodies.

Default (header omitted or any other value): epoch milliseconds as integers. iso8601: UTC ISO 8601 strings of the form YYYY-MM-DDTHH:MM:SSZ.

Example: with X-Timestamp-Format: iso8601, the field value 1704067200000 becomes "2024-01-01T00:00:00Z".

Affected fields (recursively, in dicts and arrays): any field whose name ends in _at, plus the literal field names timestamp, period_start, and period_end. All other fields are passed through unchanged.

Only iso8601 is recognized. Any other value (or omitting the header) yields the default epoch-ms representation; the server does not reject unknown values, so this is documented as an example rather than an enum to keep generated clients permissive.

Example:

"iso8601"

Path Parameters

merchant

string

required

Response

Merchant retrieved successfully

A single UCP merchant.

_links

Links · object

required

HAL-style hypermedia links for navigation and available actions.

Show child attributes

data

MerchantResource · object

required

The requested merchant.

Show child attributes

⌘I

Introduction

Quickstarts

Guides

Product Guides

API Reference

Get a UCP merchant by domain or merchant id

Authorizations

Headers

Path Parameters

Response