MedGrid API Integration Guide

MedGrid Marketplace is a B2B digital platform for the healthcare and medical supply industry — connecting clinics and healthcare practitioners with pharmacies and fulfillment vendors. This guide covers every integration needed to connect your system to MedGrid.

Endpoint Structure

All MedGrid endpoints follow this pattern:

GET  /api/method/{module}.{function}   ← fetching / reading data
POST /api/method/{module}.{function}   ← creating / sending data

For example, to search the catalog:

GET /api/method/medgrid.catalog.search_items?query=BPC

What is MedGrid?

MedGrid sits between the people who need medical products and the people who supply them. When a clinic places an order, the platform automatically routes each line item to the correct fulfillment vendor. All API communication uses HTTPS — data is encrypted in transit.

Integration Overview

MedGrid connects with six external systems. The table below is a high-level view of every integration covered in this guide.

Integration Types

Product Mapping Fields

Authentication

Before MedGrid will respond to any API request, you must prove your identity. MedGrid supports two authentication methods depending on what type of system is connecting.

Method 1: API Key + API Secret (Recommended)

This is the preferred method for any software or automated system. Works like a username and password — but designed for machines.

How to Get Your Credentials

1. Log in to the MedGrid Portal
2. Go to User Settings > API Access
3. Generate your API Key and API Secret
4. Store them securely — treat them like passwords; never share them publicly

Authorization Header

Include this header in every API call:

Authorization: token YOUR_API_KEY:YOUR_API_SECRET
Content-Type: application/json
Accept: application/json

Example Request

curl -X GET "https://app.medgrid.com/api/method/medgrid.catalog.list_warehouses" \
  -H "Authorization: token abc123key:xyz789secret" \
  -H "Content-Type: application/json"

Method 2: Session Token (Portal Users)

Used when a human vendor logs into the MedGrid Vendor Dashboard through a browser. After logging in, MedGrid issues a session cookie that is automatically included in subsequent requests.

{
  "usr": "vendor@example.com",
  "pwd": "your-password"
}

The response sets a session cookie called sid. Your browser will automatically send this cookie on every follow-up request within the same session.

Public Endpoints (No Auth Required)

A small number of endpoints do not require authentication. These are specifically designed to receive inbound data from external partners (such as Shopify OAuth callbacks and vendor webhooks). Each public endpoint is clearly marked throughout this guide.

Error Codes & Troubleshooting

When an API call fails, MedGrid returns a standard error response that makes it easy to understand what went wrong.

Standard Error Response Format

{
  "exc_type": "ValidationError",
  "exception": "...",
  "_server_messages": "[{\"message\": \"Human-readable error message\"}]"
}

HTTP Status Codes

Vendor-Specific Error Indicators

Rate Limits & Performance

A rate limit is a cap on how many API requests can be made within a given time window. Rate limits protect systems from being overloaded.

MedGrid API Rate Limits

MedGrid does not enforce a hard rate limit on authenticated API calls. However, burst traffic may be throttled server-side. Follow the best practices below to avoid issues.

Vendor API Rate Limits

Performance Best Practices

• Use webhook-driven updates instead of polling for order status wherever possible
• Cache list_warehouses results — warehouses change infrequently
• Always use the Sandbox environment for development and testing
• Implement exponential backoff in your code for any 429 or 5xx response
• Use the aggregate_shipments endpoint for consolidated tracking rather than individual vendor calls

PerfectRx — Prescription Pharmacy

PerfectRx is a compounding pharmacy that handles prescription (Rx) medications and over-the-counter (OTC) products. MedGrid uses PerfectRx for orders that require a prescription — for example, custom-compounded medications for a clinic's patients.

How It Works

Clinic places order → MedGrid checks patient in PerfectRx (creates if not found) → MedGrid sends prescription or OTC order → PerfectRx fills & ships → PerfectRx sends webhook → MedGrid updates order status

Credentials Required

Authentication — OAuth2 Token

PerfectRx uses OAuth2. MedGrid handles token acquisition and refresh automatically (tokens are refreshed 30 seconds before expiry).

{
  "credentials": {
    "clientId":     "your-client-id",
    "clientSecret": "your-client-secret"
  }
}

Order Flow — API Calls

PerfectRx returns an immediate acknowledgement with a referenceId. All further status updates arrive via webhook.

Inbound Webhook from PerfectRx

MedGrid verifies the authenticity of every webhook using HMAC-SHA256 signature verification.

X-PerfectRx-Signature: {hmac_hex}
X-PerfectRx-Nonce:     {uuid}
X-PerfectRx-Timestamp: {unix_epoch}

Webhook Events

Sales Order Fields Updated

ShipStation — Shipping & Fulfillment

ShipStation is a shipping platform used by warehouses to generate shipping labels and track packages. MedGrid uses ShipStation for physical products that need to be picked from a warehouse, packed, and shipped to a customer.

Self-Service Connection

1. Log in to the MedGrid Vendor Portal
2. Go to Integrations at /portal/integrations
3. Click Connect under the ShipStation card
4. Enter your API Key and API Secret (found in ShipStation under Settings > API Settings)

// Request
{ "api_key": "your-shipstation-key", "api_secret": "your-shipstation-secret" }

// Success response
{ "ok": true, "integration": "shipstation", "status": "connected" }

Order Sync: MedGrid → ShipStation

When a Sales Order is confirmed in MedGrid, it automatically sends the order to ShipStation. Re-submitting the same order updates the existing ShipStation order rather than creating a duplicate.

{
  "orderNumber":   "SO-2026-00123",
  "orderDate":     "2026-06-01 00:00:00",
  "orderStatus":   "awaiting_shipment",
  "customerEmail": "patient@clinic.com",
  "amountPaid":    149.00,
  "shipTo": {
    "name": "Jane Smith", "street1": "123 Main St",
    "city": "Austin", "state": "TX", "postalCode": "78701"
  },
  "items": [{ "sku": "ITEM-001", "quantity": 2, "unitPrice": 74.50 }],
  "advancedOptions": { "warehouseId": 2001705 }
}

Tracking Sync: ShipStation → MedGrid (Webhook)

Configure this webhook URL in ShipStation Admin under Settings > Webhooks > Add Webhook:

ShipStation sends a notification containing a resource_url. MedGrid automatically fetches the full tracking details from that URL.

ShipStation Event → MedGrid Status Mapping

Sales Order Fields Updated

SINQ Ops — OTC & HRT Fulfillment

SINQ Ops is the fulfillment partner for over-the-counter (OTC) products and hormone replacement therapy (HRT) items sold under the Skydell brand. MedGrid automatically routes these orders to SINQ for fulfillment.

Credentials Required

Order Sync: MedGrid → SINQ

// Request headers
key: {sinq_api_key}

// Request body
{
  "reference": "SO-2026-00123",
  "lineItems": [{ "serviceSKU": "SINQ-ITEM-001", "quantity": 1 }],
  "shippingAddress": {
    "firstName": "Jane", "address1": "123 Main St",
    "city": "Austin", "provinceCode": "TX", "zip": "78701", "countryCode": "US"
  }
}

// Success (HTTP 201)
{ "reference": "SO-2026-00123", "transactionId": "sinq-txn-abc123" }

Inbound Webhook from SINQ

key: {sinq_webhook_key}
X-Webhook-Signature: sha256={hmac_hex}   (optional)

SINQ may send status updates in two payload formats. MedGrid handles both automatically:

// Format A — Flat
{
  "reference": "SO-2026-00123",
  "status": "shipped",
  "tracking": { "trackingNumber": "1Z999...", "trackingUrl": "...", "shipBy": "UPS" }
}

// Format B — Nested
{
  "type": "order.shipped",
  "data": { "reference": "SO-2026-00123", "tracking": { ... } }
}

SINQ Status Values

Sales Order Fields Updated

Centre Research — Peptides

Centre Research Peptides is a manufacturer and fulfillment partner for peptide products. MedGrid acts as an authorized sales channel — selling Centre Research products and automatically routing orders for fulfillment.

Credentials Required

Request Headers

X-API-Key: {centre_research_api_key}
Content-Type: application/json
Accept: application/json

Placing an Order

{
  "partnerOrderId": "SO-2026-00123",
  "customer": {
    "firstName": "Jane", "lastName": "Smith",
    "email": "jane@clinic.com", "phone": "5125550100"
  },
  "shippingAddress": {
    "firstName": "Jane", "lastName": "Smith",
    "address1": "123 Main St", "city": "Austin",
    "state": "TX", "zip": "78701", "country": "US"
  },
  "items": [{ "variantId": "cr-variant-id-001", "quantity": 2 }]
}

// Success response
{ "success": true, "data": { "orderId": "cr-order-id-abc", "status": "PENDING" } }

Checking Order Status

Order status progresses through these stages:

PENDING → PROCESSING → LABEL_CREATED → SHIPPED → DELIVERED

Sales Order Fields Updated

Shopify / Exoceuticals

MedGrid integrates with Shopify in two ways: vendors with their own Shopify stores can self-connect to sync products and orders; Exoceuticals, a specific vendor, has a platform-level connection managed directly by MedGrid admins.

A6a — Vendor Self-Connect (Any Shopify Store)

Any vendor running their own Shopify store can connect it to MedGrid directly from the Integrations Portal.

Step 1 — Initiate the Connection

// Request
{ "shop_domain": "your-store.myshopify.com" }

// Response
{
  "ok": true,
  "authorize_url": "https://your-store.myshopify.com/admin/oauth/authorize?...",
  "state": "abc123def456"
}

Step 2 — Authorize in Shopify

Open the authorize_url in a browser. Log in and approve the permissions MedGrid is requesting (read_products, write_products, read_orders, write_orders).

Step 3 — Automatic Callback

Shopify redirects back to MedGrid automatically. MedGrid verifies the response, exchanges the authorization code for a permanent access token, and stores it. The connection is now active.

What Data Syncs?

A6b — Exoceuticals (Admin-Managed)

Exoceuticals' Shopify store is managed directly by MedGrid admins using the Shopify Admin GraphQL API (version 2026-04).

Daily Catalog Sync

Daily Inventory Sync

Inbound Webhook from Exoceuticals

Configure in Shopify Admin > Settings > Notifications > Webhooks:

Topics:   orders/updated, orders/cancelled, orders/fulfilled
Verification header:
X-Shopify-Hmac-Sha256: {base64(HMAC-SHA256(webhook_secret, raw_body))}

Sales Order Fields Updated

Catalog & Inventory Endpoints

These endpoints let external platforms and internal sales reps browse MedGrid's product inventory. All require API Key + API Secret authentication.

List Available Warehouses

Returns all active warehouses that hold saleable inventory. Use this to populate a warehouse picker in your interface.

// Response
[
  { "name": "Skydell Main - SM",         "warehouse_name": "Skydell Main" },
  { "name": "Skydell Exoceuticals - SM", "warehouse_name": "Skydell Exoceuticals" }
]

Browse Items in a Warehouse

Returns all items currently in stock at a specific warehouse, including pricing and available quantity.

GET /api/method/medgrid.catalog.items_in_warehouse
  ?warehouse=Skydell+Main+-+SM
  &price_list=Standard+Selling   (optional)

// Response
[
  {
    "item_code": "ITEM-001",
    "item_name": "BPC-157 5mg",
    "description": "Body Protection Compound 157, 5mg lyophilized peptide",
    "stock_uom": "Nos",
    "rate": 89.00,
    "available_qty": 142.0
  }
]

Parameters

Search Across the Catalog

Search items by name or description. If a warehouse is specified, results are strictly limited to that warehouse. Without a warehouse, results span all warehouses and include a warehouse column in the response.

GET /api/method/medgrid.catalog.search_items
  ?query=BPC
  &warehouse=Skydell+Main+-+SM   (optional)

// Response
[
  {
    "item_code": "ITEM-001",
    "item_name": "BPC-157 5mg",
    "rate": 89.00,
    "available_qty": 142.0,
    "warehouse": "Skydell Main - SM"
  }
]

Search Parameters

Placing an Order

Orders are placed as Sales Orders using the standard Frappe document API. Each sales channel partner is assigned a dedicated Customer record by MedGrid.

Step 1 — Create a Draft Order

{
  "customer": "Your-Customer-Name",
  "transaction_date": "2026-06-01",
  "delivery_date":    "2026-06-08",
  "currency": "USD",
  "selling_price_list": "Standard Selling",
  "items": [{
    "item_code": "ITEM-001",
    "qty": 5,
    "rate": 89.00,
    "warehouse": "Skydell Main - SM"
  }],
  "shipping_address_name": "Your-Shipping-Address"
}

// Response
{ "data": { "name": "SO-2026-00456", "status": "Draft", "grand_total": 445.00 } }

Step 2 — Submit the Order

After creating the draft, submit it to trigger the Fulfillment Router. The router automatically dispatches each line item to the correct vendor connector.

{ "docstatus": 1 }

Step 3 — Check Order Status

Shipment Tracking

Use the aggregate shipments endpoint to get a unified view of all per-vendor shipments for a single order — perfect for building a consolidated tracking page.

// Request
{ "sales_order": "SO-2026-00456" }

// Response
{
  "sales_order": "SO-2026-00456",
  "shipments": [
    {
      "vendor": "centre_research",
      "vendor_label": "Centre Research Peptides",
      "status": "Shipped",
      "tracking_number": "1Z999AA10123456784",
      "carrier": "UPS",
      "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
    }
  ]
}

Parameters

Response Fields

Webhook Reference

A webhook is an automated message sent from one system to another when a specific event occurs. Instead of MedGrid constantly polling for changes, vendors proactively notify MedGrid the moment something happens.

All Inbound Webhook Endpoints

Webhook Best Practices

Onboarding & Support

A complete reference for getting started with MedGrid integrations, plus role-based summaries and contact information.

Onboarding Checklist

• 1Request a Vendor Profile from MedGrid
• 2Receive your MedGrid login and access to the Vendor Dashboard
• 3For self-service integrations (ShipStation, Shopify): connect from /portal/integrations
• 4For managed integrations (PerfectRx, SINQ, Centre Research): provide credentials to the MedGrid integrations team
• 5Work with the MedGrid catalog team to complete product mapping
• 6Test all order flows in the Sandbox environment
• 7Configure webhook endpoints in your vendor platform
• 8Verify webhook signature verification is working correctly
• 9Confirm a test order flows end-to-end (order placed → vendor receives → tracking returned)
• 10Go live in production

Roles Summary

Internal Sales Rep Access Control

Getting Help