Developer API Reference

Complete technical reference for all public-facing MedGrid APIs. This guide covers authentication, endpoint specifications, request/response schemas, error handling, and integration details for Shopify and ShipStation.

Base URLs

Endpoint URL Pattern

All API endpoints follow the Frappe RPC pattern:

https://app.medgrid.com/api/method/{python.module.path.function_name}

RESTful resource endpoints follow:

https://app.medgrid.com/api/resource/{DocType}/{name}

API Groups

Authentication

MedGrid supports two authentication methods. Token-based authentication is required for all server-to-server integrations.

Token Authentication (Recommended)

Every authenticated request must include the following HTTP header:

Authorization: token {api_key}:{api_secret}
Content-Type: application/json
Accept: application/json

Generate API Credentials

1. Log in to the MedGrid Portal.
2. Navigate to User Settings → API Access.
3. Click Generate Keys.
4. Copy the API Key and API Secret — the secret is shown only once.

Session Token (Browser)

Browser-based portal users authenticate via session cookie obtained at login:

{ "usr": "user@example.com", "pwd": "password" }

On success, a sid session cookie is set automatically for all subsequent browser requests.

Public Endpoints (No Auth)

The following endpoints accept unauthenticated requests. Each is designed to receive inbound data from external systems:

API Conventions

Consistent patterns used across all MedGrid APIs.

HTTP Methods

Response Envelope

All RPC method responses wrap the return value in a message key:

{ "message": { ...your data... } }

REST resource responses wrap data in a data key:

{ "data": { ...document fields... } }

Dates & Times

• Dates: YYYY-MM-DD (e.g. 2026-06-18)
• Datetimes: YYYY-MM-DD HH:MM:SS (e.g. 2026-06-18 14:30:00)
• All times are in UTC.

Pagination

List endpoints accept limit_start (offset) and limit_page_length (page size, default 20, max 500) parameters for pagination.

# Get items 21–40
GET /api/resource/Sales Order?limit_start=20&limit_page_length=20

Returns all active, non-group warehouses. Use to populate a warehouse picker.

Parameters

None.

Response

{
  "message": [
    {
      "name": "ShipStation Warehouse - SM",
      "warehouse_name": "ShipStation Warehouse",
      "company": "Skydell Medical"
    }
  ]
}

Response Fields

Returns warehouses ordered by the priority list configured in Medgrid Settings, then alphabetically. Preferred warehouses appear first.

Parameters

None.

Response

{
  "message": [
    { "name": "ShipStation Warehouse - SM", "label": "ShipStation Warehouse - SM" },
    { "name": "Exoceuticals Warehouse - SM", "label": "Exoceuticals Warehouse - SM" }
  ]
}

Returns all items with actual_qty > 0 in the specified warehouse, joined with Item Price for the given price list.

Query Parameters

Response

{
  "message": [
    {
      "item_code": "VD3-5000-120",
      "item_name": "Vitamin D3 5000 IU (120 Softgels)",
      "description": "High-potency Vitamin D3 supplement.",
      "stock_uom": "Box",
      "rate": 28.50,
      "available_qty": 150
    }
  ]
}

Response Fields

Full-text search across item_name and description. Returns only items with positive stock. When warehouse is supplied, results are strictly filtered to that warehouse only.

Query Parameters

Response

{
  "message": [
    {
      "item_code": "VD3-5000-120",
      "item_name": "Vitamin D3 5000 IU (120 Softgels)",
      "description": "High-potency Vitamin D3 supplement.",
      "stock_uom": "Box",
      "rate": 28.50,
      "available_qty": 150,
      "warehouse": "ShipStation Warehouse - SM"
    }
  ]
}

Returns the integration registry plus the calling user's current connection status for each integration. Credentials are never returned — only metadata and status flags.

Parameters

None.

Response

{
  "message": {
    "integrations": [
      {
        "id": "shipstation",
        "label": "ShipStation",
        "tagline": "Push your MedGrid orders into ShipStation, pull tracking back.",
        "auth_kind": "api_key_secret",
        "status": "connected",
        "last_sync_at": "2026-06-18 10:30:00",
        "last_error": null,
        "stats": { "orders_pushed": 12, "tracking_pulled": 8 },
        "has_credentials": true,
        "credential_keys": ["api_key", "api_secret"]
      },
      {
        "id": "shopify",
        "label": "Shopify",
        "status": "not_connected",
        "last_sync_at": null,
        "last_error": null,
        "stats": {},
        "has_credentials": false
      },
      {
        "id": "sendblue",
        "label": "SMS / iMessage support",
        "status": "connected",
        "last_sync_at": "2026-05-10 08:00:00",
        "stats": { "verified_phone": "+15551234567" }
      }
    ],
    "user": "vendor@example.com"
  }
}

Status Values

Validates and saves ShipStation API credentials in one step. Credentials are tested against ShipStation before being persisted — if they are invalid, nothing is saved.

Request Body

Request

{
  "api_key": "ss-api-key-here",
  "api_secret": "ss-api-secret-here"
}

Response — Success

{
  "message": {
    "ok": true,
    "integration": "shipstation",
    "status": "connected"
  }
}

Response — Failure

{
  "message": {
    "ok": false,
    "error": "Invalid API Key or Secret — ShipStation rejected the credentials.",
    "status": "error"
  }
}

Re-tests an existing connection's stored credentials against the external service. Updates the integration status to connected or error.

Request Body

Response

{ "message": { "ok": true, "error": null } }

Triggers a manual full sync for the specified integration. For ShipStation: pushes up to 25 unfulfilled orders and pulls tracking for previously pushed orders. For Shopify: pulls the product catalog.

Request Body

Response — ShipStation

{
  "message": {
    "ok": true,
    "stats": {
      "orders_pushed": 3,
      "tracking_pulled": 5,
      "round_trip_ok": true,
      "push_errors": [],
      "pull_errors": []
    }
  }
}

Response — Shopify

{
  "message": {
    "ok": true,
    "stats": {
      "products_pulled": 47,
      "round_trip_ok": true,
      "sample_titles": ["Product A", "Product B"]
    }
  }
}

Removes stored credentials for an integration. The integration status returns to not_connected.

Request Body

{ "integration_type": "shipstation" }

Response

{ "message": { "ok": true, "integration": "shipstation" } }

Generates the Shopify OAuth authorisation URL for the vendor's store. The caller opens this URL in a browser popup to begin the OAuth flow.

Request Body

Request

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

Response

{
  "message": {
    "ok": true,
    "authorize_url": "https://your-store.myshopify.com/admin/oauth/authorize?client_id=...&scope=...&state=abc123",
    "state": "abc123nonce"
  }
}

Open authorize_url in a browser. After the merchant approves, Shopify calls shopify_callback automatically.

Shopify OAuth redirect target. Called automatically by Shopify after the merchant approves the connection. Exchanges the authorization code for an access token and persists the integration.

This endpoint is called by Shopify — you do not call it directly. Shopify appends these query parameters automatically:

Success Response

{
  "message": {
    "ok": true,
    "shop": "your-store.myshopify.com",
    "redirect": "/portal/integrations?shopify=connected"
  }
}

Shopify (Exoceuticals) Integration

MedGrid connects to the Exoceuticals Shopify store via the Shopify Admin GraphQL API (version 2026-04). This integration handles catalog sync, inventory sync, order creation, and inbound fulfillment webhooks.

Configuration (System Settings)

The following fields must be configured in System Settings → API Integration → Exoceuticals before using these APIs:

Item-Level Mapping Fields

These custom fields are added to the Item DocType to link MedGrid items with Shopify variants:

Builds the Shopify install URL for the Exoceuticals Custom App OAuth flow. Admin opens this URL in a browser to authorise the connection.

Parameters

Response

{
  "message": {
    "install_url": "https://2899e4.myshopify.com/admin/oauth/authorize?client_id=...&scope=...&state=...",
    "shop": "2899e4.myshopify.com",
    "redirect_uri": "https://app.medgrid.com/api/method/medgrid.exoceuticals.oauth_callback"
  }
}

Shopify redirects here after the merchant authorises the app. Verifies the HMAC, exchanges the code for an Admin API access token, and persists it in System Settings.

Called automatically by Shopify. Verifies: (1) .myshopify.com domain, (2) state nonce, (3) HMAC-SHA256 signature across all query params.

Success Response

{
  "status": "success",
  "shop": "2899e4.myshopify.com",
  "scope": "read_products,write_products,read_orders,write_orders,read_inventory,write_inventory",
  "message": "Exoceuticals connected. You can close this tab."
}

Error Response

{
  "status": "error",
  "message": "HMAC verification failed."
}

Pulls all products and variants from Shopify and writes their GIDs onto matching MedGrid Items (matched by SKU). Does NOT auto-create Items — catalog membership is curated, not auto-imported.

Parameters

None.

Response

{
  "message": {
    "status": "ok",
    "matched": 142,
    "unmatched_count": 3
  }
}

Response Fields

Refreshes inventory quantities from Shopify for all Items that have an exoceuticals_inventory_item_id set. Also mirrors quantities into the Exoceuticals warehouse Bin records.

Response

{
  "message": {
    "status": "ok",
    "updated": 138,
    "warehouse": "Exoceuticals Warehouse - SM"
  }
}

Creates a Shopify order from a submitted MedGrid Sales Order. Tags the order "Skydell" per Exoceuticals' requirements. Can only be called once per Sales Order (idempotent guard).

Request Body

Request

{ "sales_order": "SAL-2026-00123" }

Response

{
  "message": {
    "status": "success",
    "exoceuticals_order_id": "gid://shopify/Order/4567890123",
    "exoceuticals_order_name": "#1042"
  }
}

Prerequisites

• Sales Order must be submitted (docstatus = 1).
• Order must not already have an exoceuticals_order_id.
• At least one line item must have exoceuticals_variant_id set on the Item — run sync_catalog first.
• Sales Order must have a valid shipping address.

Queries Shopify for the current fulfillment status of a previously synced order and updates the Sales Order fields accordingly. Used as belt-and-suspenders alongside webhooks.

Request

{ "sales_order": "SAL-2026-00123" }

Response

{ "message": "Fulfilled" }

Returns the new exoceuticals_status string. Also updates exoceuticals_tracking_number, exoceuticals_carrier, and exoceuticals_tracking_url on the Sales Order if shipping data is available.

Inbound webhook endpoint for Shopify order updates. Register this URL in Shopify Admin → Settings → Notifications → Webhooks for the topics listed below.

Required Headers (sent by Shopify)

Supported Topics

Example Payload (orders/fulfilled)

{
  "id": 4567890123,
  "fulfillment_status": "fulfilled",
  "cancelled_at": null,
  "fulfillments": [
    {
      "tracking_number": "1Z999AA10123456784",
      "tracking_company": "UPS",
      "tracking_urls": ["https://ups.com/track?number=1Z999AA10123456784"]
    }
  ]
}

Response

{
  "message": {
    "status": "ok",
    "topic": "orders/fulfilled",
    "sales_order": "SAL-2026-00123"
  }
}

ShipStation Integration

The ShipStation integration enables vendors to receive MedGrid Sales Orders in their ShipStation account and automatically synchronise tracking numbers back to MedGrid.

Authentication

ShipStation uses HTTP Basic Auth. MedGrid constructs the header internally from the vendor's stored credentials:

Authorization: Basic BASE64(api_key:api_secret)

Integration Flow

Order Push to ShipStation

When sync_now is called for ShipStation, MedGrid queries for submitted Sales Orders whose items' default_supplier matches the calling vendor and that have not yet been pushed (shipstation_order_id is empty).

Order Payload Structure

MedGrid sends this payload to POST https://ssapi.shipstation.com/orders/createorder:

{
  "orderNumber":   "SAL-2026-00123",
  "orderKey":      "SAL-2026-00123",
  "orderDate":     "2026-06-18",
  "orderStatus":   "awaiting_shipment",
  "customerEmail": "customer@example.com",
  "amountPaid":    91.00,
  "items": [
    {
      "lineItemKey": "row-id-1",
      "sku":         "VD3-5000-120",
      "name":        "Vitamin D3 5000 IU (120 Softgels)",
      "quantity":    2,
      "unitPrice":   28.50
    }
  ]
}

On success, ShipStation returns an orderId which MedGrid stores in Sales Order.shipstation_order_id to track the push.

Multi-Vendor Order Splitting

When a Sales Order contains items from multiple vendors, only the calling vendor's line items are included in the ShipStation payload. Items belonging to other vendors are pushed separately by those vendors on their own sync.

Tracking Number Pull

During each sync, MedGrid queries ShipStation for shipments on previously pushed orders and writes tracking info to the corresponding Delivery Note.

How Tracking Pull Works

1. MedGrid queries all Sales Orders with a non-empty shipstation_order_id.
2. For each, it calls GET https://ssapi.shipstation.com/shipments?orderId={shipstation_order_id}.
3. For any shipment with a trackingNumber, MedGrid finds the linked Delivery Note and sets:
   • Delivery Note.lr_no = tracking number
   • Delivery Note.transporter = carrier code (uppercase)

// ShipStation shipment response (excerpt)
{
  "shipments": [
    {
      "trackingNumber": "1Z999AA10123456784",
      "carrierCode": "ups",
      "shipDate": "2026-06-19"
    }
  ]
}

Data Models

Key data structures returned by MedGrid APIs.

Integration Connection Object

{
  "id": "shipstation",
  "label": "ShipStation",
  "tagline": "Push your MedGrid orders into ShipStation, pull tracking back.",
  "auth_kind": "api_key_secret",
  "status": "connected",
  "last_sync_at": "2026-06-18 10:30:00",
  "last_error": null,
  "stats": {
    "orders_pushed": 12,
    "tracking_pulled": 8
  },
  "has_credentials": true,
  "credential_keys": ["api_key", "api_secret"],
  "permits": ["orders.write", "tracking.read"],
  "what_we_push": ["MedGrid Sales Orders (line items, ship-to address, weight)"],
  "what_we_pull": ["Tracking numbers", "Carrier + service", "Ship date"]
}

Catalog Item Object

{
  "item_code": "VD3-5000-120",
  "item_name": "Vitamin D3 5000 IU (120 Softgels)",
  "description": "High-potency Vitamin D3 supplement.",
  "stock_uom": "Box",
  "rate": 28.50,
  "available_qty": 150,
  "warehouse": "ShipStation Warehouse - SM"
}

Sales Order Status Fields (Exoceuticals)

{
  "exoceuticals_order_id":       "gid://shopify/Order/4567890123",
  "exoceuticals_order_name":     "#1042",
  "exoceuticals_status":         "Fulfilled",
  "exoceuticals_tracking_number": "1Z999AA10123456784",
  "exoceuticals_carrier":        "UPS",
  "exoceuticals_tracking_url":   "https://ups.com/track?number=1Z999AA10123456784",
  "exoceuticals_sync_date":      "2026-06-18 14:00:00"
}

Error Reference

Complete reference of HTTP status codes, error response formats, and integration-specific error codes.

Standard MedGrid Error Response

{
  "exc_type": "ValidationError",
  "exception": "frappe.exceptions.ValidationError: Both API Key and API Secret are required.",
  "_server_messages": "[{\"message\": \"Both API Key and API Secret are required.\"}]"
}

HTTP Status Code Reference

Integration-Specific Error Codes

Webhook Error Response

{
  "status": "error",
  "code": "INVALID_TOKEN",
  "message": "Authentication failed"
}

Rate Limits & Best Practices

Rate limits prevent API overload. MedGrid manages all external rate limits automatically.

MedGrid API Rate Limits

MedGrid does not enforce a hard rate limit on authenticated API calls from customers and vendors. Burst traffic may be throttled server-side. Implement exponential backoff for any 429 or 5xx response.

External System Rate Limits

Performance Best Practices

• Cache list_warehouses results — warehouses change infrequently (safe to cache for 15 minutes).
• Use webhooks for order status updates instead of polling poll_exoceuticals_status continuously.
• Always develop and test against the Sandbox environment before switching to Production.
• Implement exponential backoff in your own code for any 429 or 500 response from MedGrid.
• Keep sync_catalog as a scheduled daily job rather than calling it on every order.