Application API

For partner applications: browse merchants and products, hand customers a checkout link, and follow the orders it creates.

Getting started API reference Resources

Order webhooks MCP server Operational notes

Resources

MCP server

Use the Application API from an AI assistant. The MCP server exposes every endpoint as a tool and signs each call for you, as your application.

POST https://merchant.gini.iq/mcp/applications

How it works

You connect once with your app_id and app_secret. The server calls the Application API as your application, with the HMAC signature computed for you.
You see exactly what a direct integration sees: your merchants only, the payment methods enabled for you, and the orders your application created.
Three ways to connect: a custom connector in claude.ai, Claude Desktop or Claude mobile (you sign in once in the browser); headers on every request (Claude Code and other MCP clients); or the MCP connector in the Claude API, from your own backend.

Connect from claude.ai or Claude Desktop

Add the connector. In Claude, open Customize → Connectors, click +, choose Add custom connector, and paste the URL above. Leave the OAuth fields empty.

Authorize. Check that access is returned to claude.ai, then click Authorize. Claude can now use the tools below.

Notes

The server must be reachable from Anthropic's cloud — connectors are opened from there, not from your computer.
Access tokens last an hour and Claude refreshes them for up to 30 days; after that you sign in again.
Deactivating your application cuts the connector off at once. Rotating your app_secret does not — ask Gini to revoke existing connections too.

Connect with headers

Headers

Field	Type	Required	Description
`X-App-Id`	string	Required	Your app_id.
`X-App-Secret`	string	Required	Your app_secret, as-is. It never leaves HTTPS and is not signed — the server does the signing.

Claude Code

claude mcp add --transport http gini-applications https://merchant.gini.iq/mcp/applications \
  --header "X-App-Id: <your app_id>" \
  --header "X-App-Secret: <your app_secret>"

Other MCP clients (JSON config)

{
    "mcpServers": {
        "gini-applications": {
            "type": "http",
            "url": "https://merchant.gini.iq/mcp/applications",
            "headers": {
                "X-App-Id": "<your app_id>",
                "X-App-Secret": "<your app_secret>"
            }
        }
    }
}

Notes

Missing or wrong credentials, or a deactivated application → 401.
A client that can only send a bearer token can send Authorization: Bearer <app_id>:<app_secret> instead of the two headers.

Connect from the Claude API (MCP connector)

Let Claude use these tools inside your own product: pass the server in a Messages API request and Anthropic connects to it for you. Your app_id and app_secret go in authorization_token, joined by a colon.

cURL

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 16000,
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://merchant.gini.iq/mcp/applications",
        "name": "gini",
        "authorization_token": "<your app_id>:<your app_secret>"
      }
    ],
    "tools": [
      {
        "type": "mcp_toolset",
        "mcp_server_name": "gini",
        "configs": { "cancel-order": { "enabled": false } }
      }
    ],
    "messages": [
      { "role": "user", "content": "Find an iPhone 15 under 1,500,000 IQD and make me a cash-on-delivery checkout token." }
    ]
  }'

What each field does

Field	Type	Required	Description
`anthropic-beta`	header	Required	mcp-client-2025-11-20 — the MCP connector is in beta.
`mcp_servers[].url`	string	Required	This server's URL.
`mcp_servers[].name`	string	Required	Any name; the toolset refers to the server by it.
`mcp_servers[].authorization_token`	string	Required	<app_id>:<app_secret>. Sent to this server as a bearer token.
`tools[].mcp_toolset`	object	Required	Must name the same server in mcp_server_name, or the request is rejected.
`tools[].configs`	object	Optional	Per-tool switches. The example turns cancel-order off, since no person approves each call here.

Notes

The Claude API calls this server from Anthropic's cloud, so it must be reachable from the internet.
Keep the request on your backend: authorization_token carries your app_secret, so never build it in a browser or mobile app.

Tool	Calls	What it does
`list-merchants`	`GET /merchants`	Your merchants, searchable, optionally nearest-first.
`search-products`	`GET /products`	Product search and browse. Takes category ids as a list — the tool sends the CSV.
`get-product`	`GET /products/{slug}`	One product, by slug.
`list-categories`	`GET /categories`	Category tree with nested subcategories.
`list-sub-categories`	`GET /sub-categories`	Flat, paginated subcategories.
`list-reels`	`GET /reels`	Shuffled reel feed.
`create-checkout-token`	`POST /checkout-tokens`	Seal a basket into a single-use checkout token.
`list-orders`	`GET /orders`	Orders created through your application.
`get-order`	`GET /orders/{id}`	One order.
`cancel-order`	`POST /orders/{id}/cancel`	Cancel a pending order. Marked destructive — assistants ask before calling it.
`list-reject-reasons`	`GET /reject-reasons`	Reasons cancel-order accepts.
`list-states`	`GET /states`	States and districts, for checkout addresses.

Notes

Tool arguments are the endpoint's own parameters — see each page of this reference for their rules.
A failed call comes back as a tool error in plain words, carrying the API's message and key, rather than as raw HTTP.
Product results are trimmed to what an assistant needs — price, stock, image, merchant, rating, campaign; details add description, images and variants. Pass full: true to get the endpoint's complete payload.
In clients that support MCP apps, such as Claude, search-products results appear as product cards with Details and Checkout buttons.
60 requests per minute per app_id. Back off on 429.
A checkout token is a per-customer secret: the first customer to open it owns it. Do not let an assistant post one anywhere public.

Previous Order webhooks Next Operational notes