← Back to Home

OrignaGTA MCP Server — API Reference

Complete documentation for all 14 production-ready tools

Quick Navigation: Jump to tool categories:

Search & Browse (3 tools)
Shopping Cart (3 tools)
Discounts (1 tool)
Checkout (1 tool)
Orders (3 tools)
Reviews (1 tool)
Analytics (1 tool)

Search & Browse Tools

search_products(query, filters...)

Search the product catalog with optional filters for category, price, and sorting.

Read-Only

Parameters

query

string (required)

Search keywords. Searches across product title, description, and keywords.

Response Example

{
  "items": [
    {
      "id": "products:abc123",
      "title": "Laptop Pro",
      "priceCents": 129900,
      "imageUrls": [
        "https://cdn.example.com/product1.jpg"
      ],
      "stockQuantity": 25,
      "categoryId": "electronics",
      "rating": 4.8,
      "reviewCount": 156
    }
  ],
  "total": 45,
  "limit": 20,
  "offset": 0
}

get_product(id)

Retrieve detailed product information including reviews and seller info.

Read-Only

Parameters

string (required)

Product ID in format "products:abc123xyz".

Response Example

{
  "id": "products:abc123",
  "title": "Laptop Pro",
  "description": "High-performance laptop with...",
  "priceCents": 129900,
  "imageUrls": ["https://...", "https://..."],
  "stockQuantity": 25,
  "categoryId": "electronics",
  "sellerId": "users:seller456",
  "seller": {
    "name": "TechStore Inc",
    "rating": 4.9,
    "reviewCount": 523
  },
  "rating": 4.8,
  "reviewCount": 156,
  "reviews": [
    {
      "rating": 5,
      "comment": "Excellent quality!",
      "author": "Anonymous",
      "dateCreated": 1710763200
    }
  ],
  "dateCreated": 1710763200
}

check_inventory(product_id, quantity)

Real-time inventory check for a product.

Read-Only

Parameters

product_id

string (required)

Product ID (e.g., "products:abc123").

quantity

number (optional)

Quantity to check. Default: 1.

Response Example

{
  "product_id": "products:abc123",
  "available": true,
  "stock_quantity": 25,
  "requested_quantity": 1,
  "message": "In stock"
}

Shopping Cart Tools

add_to_cart(product_id, quantity, variant?)

Add items to the shopping cart with quantity validation.

Write

Parameters

product_id

string (required)

Product ID (e.g., "products:abc123").

quantity

number (required)

Quantity to add (≥ 1).

variant

string (optional)

Product variant or SKU if applicable.

Response Example

{
  "product_id": "products:abc123",
  "quantity": 1,
  "added": true,
  "cart": {
    "items": [
      {
        "product_id": "products:abc123",
        "quantity": 1,
        "unitPriceCents": 129900
      }
    ],
    "itemCount": 1,
    "subtotalCents": 129900,
    "taxAmountCents": 16887,
    "shippingCostCents": 0,
    "totalAmountCents": 146787
  }
}

remove_from_cart(product_id, quantity?)

Remove items from the cart.

Write

Parameters

product_id

string (required)

Product ID to remove.

quantity

number (optional)

Quantity to remove. If omitted, removes all items.

Response Example

{
  "removed": true,
  "quantity_removed": 1,
  "cart": {
    "items": [],
    "itemCount": 0,
    "subtotalCents": 0,
    "taxAmountCents": 0,
    "totalAmountCents": 0
  }
}

get_cart()

Retrieve the current shopping cart.

Read-Only

Response Example

{
  "items": [
    {
      "product_id": "products:abc123",
      "title": "Laptop Pro",
      "quantity": 1,
      "unit_price_cents": 129900,
      "line_total_cents": 129900,
      "image_url": "https://..."
    }
  ],
  "itemCount": 1,
  "subtotalCents": 129900,
  "taxAmountCents": 16887,
  "shippingCostCents": 0,
  "coupon_applied": null,
  "discount_cents": 0,
  "totalAmountCents": 146787,
  "lastUpdated": 1710763200
}

Discounts & Coupons

apply_coupon(code)

Apply a discount code to the current cart.

Write

Parameters

code

string (required)

Coupon code (e.g., "SAVE15", "WELCOME20").

Response Example

{
  "applied": true,
  "code": "SAVE15",
  "discount_cents": 19485,
  "discount_percent": 15,
  "new_total_cents": 127302,
  "expiration_date": "2026-12-31",
  "terms": "15% off orders over $50"
}

Checkout & Payments

create_checkout(shipping_address, coupon?)

THE KEY CAPABILITY — Create a Stripe Checkout Session with embedded checkout, automatic tax, shipping rates, and multiple payment methods.

Write

Parameters

shipping_address

object (required)

Shipping address with the following fields:

street (string, required) — Street address

city (string, required) — City name

province (string, required) — 2-letter code (ON, BC, AB, etc.)

postalCode (string, required) — Format: "A1A 1A1"

country (string, required) — Must be "CA" (Canada only)

phone (string, required) — E.164 format "+1XXXXXXXXXX"

coupon

string (optional)

Discount code (must be applied to cart first).

Response Example

{
  "sessionId": "cs_test_...",
  "sessionUrl": "https://checkout.stripe.com/pay/cs_test_...",
  "clientSecret": "...",
  "publishableKey": "pk_test_...",
  "subtotalCents": 129900,
  "taxAmountCents": 16887,
  "shippingCostCents": 0,
  "discountCents": 0,
  "totalCents": 146787,
  "status": "ready_for_payment",
  "paymentMethods": [
    "card",
    "link",
    "cash_app",
    "afterpay_clearpay"
  ],
  "expiresAt": 1710776400
}

Features

Embedded Checkout — ui_mode: 'embedded' for seamless in-context payments
Automatic Tax — Real-time HST/GST/PST calculation for Canada
Shipping Rates — Real-time calculation based on address and destination
Multiple Payment Methods — Card, Stripe Link, Cash App, Afterpay/Clearpay
Idempotent Requests — Safe to retry without duplicate charges
Webhook Security — Stripe webhook confirms payment before order creation

Order Management

list_orders(status?, limit, offset, sort?)

View order history with optional filtering by status.

Read-Only

Parameters

status

string (optional)

Filter by status: "pending", "confirmed", "shipped", "delivered", "cancelled".

limit

number (optional)

Results per page. Default: 20. Max: 100.

offset

number (optional)

Pagination offset. Default: 0.

sort

string (optional)

Sort order: "newest" (default) or "oldest".

Response Example

{
  "orders": [
    {
      "id": "orders:order123",
      "buyerId": "users:buyer456",
      "status": "confirmed",
      "totalAmountCents": 146787,
      "itemCount": 1,
      "createdAt": 1710763200,
      "estimatedDelivery": "2026-03-25"
    }
  ],
  "total": 5,
  "limit": 20,
  "offset": 0
}

get_order(id)

Retrieve detailed order information including items, totals, and tracking.

Read-Only

Parameters

string (required)

Order ID (e.g., "orders:abc123").

Response Example

{
  "id": "orders:order123",
  "buyerId": "users:buyer456",
  "sellerId": "users:seller789",
  "status": "confirmed",
  "items": [
    {
      "productId": "products:xyz",
      "name": "Laptop Pro",
      "quantity": 1,
      "unitPriceCents": 129900,
      "imageUrl": "https://..."
    }
  ],
  "subtotalCents": 129900,
  "taxAmountCents": 16887,
  "shippingCostCents": 0,
  "totalAmountCents": 146787,
  "shippingAddress": {
    "street": "123 Main St",
    "city": "Toronto",
    "province": "ON",
    "postalCode": "M5V 3A8",
    "country": "CA"
  },
  "trackingNumber": null,
  "createdAt": 1710763200,
  "confirmedAt": 1710763200,
  "shippedAt": null,
  "deliveredAt": null,
  "paymentIntentId": "pi_test_...",
  "refundRequested": false
}

request_return(order_id, reason, description?)

Initiate a return/refund request for an order or specific items.

Write

Parameters

order_id

string (required)

Order ID (e.g., "orders:abc123").

reason

string (required)

Return reason: "damaged", "wrong_item", "not_as_described", "other".

description

string (optional)

Additional details about the return.

Response Example

{
  "return_id": "returns:ret123",
  "order_id": "orders:order123",
  "status": "pending",
  "reason": "damaged",
  "created_at": 1710763200,
  "window_closes_at": 1713441600,
  "estimated_refund_amount_cents": 146787,
  "message": "Return request received. Seller will review within 2 business days."
}

Reviews

submit_review(product_id, rating, title?, comment?, order_id?)

Submit a product review with 1-5 star rating.

Write

Parameters

product_id

string (required)

Product ID (e.g., "products:abc123").

rating

number (required)

Star rating (1-5).

title

string (optional)

Review title.

comment

string (optional)

Review text.

order_id

string (optional)

Link to order (for verified purchase badge).

Response Example

{
  "review_id": "reviews:rev123",
  "product_id": "products:abc123",
  "rating": 5,
  "title": "Excellent quality!",
  "comment": "Great laptop, highly recommend",
  "verified_purchase": true,
  "published": true,
  "created_at": 1710763200
}

Analytics (Admin Only)

get_analytics(period?, start_date?, end_date?)

Sales and performance analytics. Requires admin role.

Read-Only • Admin

Parameters

period

string (optional)

Time period: "day", "week", "month", "year".

start_date

string (optional)

ISO date format "2026-03-01".

end_date

string (optional)

ISO date format "2026-03-31".

Response Example

{
  "period": "month",
  "total_revenue_cents": 1500000,
  "total_orders": 42,
  "average_order_value_cents": 35714,
  "total_items_sold": 98,
  "top_products": [
    {
      "product_id": "products:abc123",
      "title": "Laptop Pro",
      "units_sold": 15,
      "revenue_cents": 1948500
    }
  ],
  "top_sellers": [
    {
      "seller_id": "users:seller789",
      "name": "TechStore Inc",
      "revenue_cents": 750000,
      "orders": 21
    }
  ],
  "conversion_rate": 3.2,
  "returning_customers": 18,
  "new_customers": 24
}

Error Handling

Standard Error Response

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "statusCode": 400
}

Common Error Codes

Code	HTTP	Meaning
VALIDATION_ERROR	400	Invalid input (bad postal code, price range, etc.)
AUTH_ERROR	401	Missing or invalid JWT token
AUTHZ_ERROR	403	Insufficient permissions (e.g., non-admin accessing admin tool)
NOT_FOUND	404	Product/order/user doesn't exist
CONFLICT	409	Business logic violation (e.g., out of stock, return window closed)
RATE_LIMIT	429	Too many requests — wait before retrying
STRIPE_ERROR	400	Stripe API error (payment declined, invalid address, etc.)
INTERNAL_ERROR	500	Server error — report to support