Customer API Guide

How customers — clinics, practices, and healthcare sales channels — connect to MedGrid, access the approved product catalog, and place orders through the API.

Who Is This Guide For?

This guide is for customers — medical practices, clinics, and healthcare sales channels that want to:

• Browse the MedGrid product catalog and check real-time availability.
• Retrieve customer-specific pricing from their assigned price list.
• Submit orders programmatically through their own software or EHR system.
• Track the status and shipment of their orders.

How MedGrid Works for Customers

What Customers Can Access

Authentication

All MedGrid API calls require authentication. Use your API Key and Secret for all automated or server-to-server integrations.

API Key + Secret

Include this header on every request:

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

How to Get Your Credentials

1. Log in to the MedGrid Customer Portal.
2. Go to User Settings > API Access.
3. Click Generate Keys.
4. Copy both the API Key and API Secret and store them securely.

Example Authenticated Request

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

Base URLs

All API requests are made to the MedGrid base URL. Use the Sandbox environment for development and testing.

All API endpoints follow the pattern:

https://app.medgrid.com/api/method/{endpoint_name}

Returns all active warehouses in the MedGrid system. Use this to populate a warehouse selector before fetching inventory.

Authentication

Required. Include the Authorization: token KEY:SECRET header.

Parameters

None required. This endpoint takes no parameters.

Example Request

curl -X GET \
  "https://app.medgrid.com/api/method/medgrid.catalog.list_warehouses" \
  -H "Authorization: token abc123:xyz789"

Example Response

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

Response Fields

Returns the same warehouse list, but ordered by MedGrid's configured warehouse priority. Preferred warehouses (e.g. fastest fulfillment) appear first.

Parameters

None required.

Example Response

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

Returns all products that currently have available stock in a specific warehouse, along with your customer-specific price for each item.

Query Parameters

Example Request

curl -X GET \
  "https://app.medgrid.com/api/method/medgrid.catalog.items_in_warehouse?warehouse=ShipStation%20Warehouse%20-%20SM&price_list=Standard%20Selling" \
  -H "Authorization: token abc123:xyz789"

Example Response

{
  "message": [
    {
      "item_code": "VD3-5000-120",
      "item_name": "Vitamin D3 5000 IU (120 Softgels)",
      "description": "High-potency Vitamin D3 to support immune function and bone health.",
      "stock_uom": "Box",
      "rate": 28.50,
      "available_qty": 150
    },
    {
      "item_code": "OMEGA3-1000-90",
      "item_name": "Omega-3 Fish Oil 1000mg (90 Softgels)",
      "description": "Pharmaceutical-grade Omega-3 fatty acids.",
      "stock_uom": "Box",
      "rate": 34.00,
      "available_qty": 72
    }
  ]
}

Response Fields

Search for products by name or description. Optionally filter to a specific warehouse or apply a price list. Returns only items with available stock.

Query Parameters

Example Request — Search All Warehouses

curl -X GET \
  "https://app.medgrid.com/api/method/medgrid.catalog.search_items?query=vitamin+d&price_list=Standard%20Selling" \
  -H "Authorization: token abc123:xyz789"

Example Request — Search Within a Warehouse

curl -X GET \
  "https://app.medgrid.com/api/method/medgrid.catalog.search_items?query=omega&warehouse=ShipStation%20Warehouse%20-%20SM&price_list=Wholesale" \
  -H "Authorization: token abc123:xyz789"

Example Response

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

Sales Channel Pricing

MedGrid supports multiple price tiers. Different customers may see different prices for the same product based on their assigned Price List.

How Pricing Works

Every MedGrid customer account is assigned a Price List. When you call any catalog endpoint with your Price List name, MedGrid returns prices specific to your tier. If you do not supply a price_list parameter, MedGrid uses the system default (Standard Selling).

Understanding Your Price List

Contact your MedGrid account manager to confirm which Price List is assigned to your account. Common price tiers include:

Using Your Price List in API Calls

Pass your Price List name as the price_list parameter in any catalog endpoint:

curl -X GET \
  "https://app.medgrid.com/api/method/medgrid.catalog.items_in_warehouse?warehouse=ShipStation%20Warehouse%20-%20SM&price_list=Wholesale" \
  -H "Authorization: token abc123:xyz789"

Price Lists

Price lists determine what price each customer sees. Your price list is configured by MedGrid and tied to your customer account.

Contract Pricing

If you have a signed pricing agreement with MedGrid, you will be assigned a Contract Price List. This list reflects the negotiated prices for products covered by your contract. Prices in your contract list:

• Override the standard price for covered products.
• May have validity periods — confirm with your account manager if a contract renewal is needed.
• Are automatically applied when you pass your price list name in API calls.

Discount Rules

Discounts in MedGrid work at the Price List level — discounted prices are baked into the Price List rate rather than applied on top as a percentage. This means:

• The rate value you receive in catalog responses is your final price — no further discounts are applied automatically.
• Sales reps may apply additional manual discounts within the allowed rate tolerance (set per vendor).

Price Updates

Price changes from MedGrid or your vendors take effect immediately for all new orders. To get the latest prices, always fetch catalog data fresh for each ordering session rather than caching prices for extended periods.

Place an Order

Submit a new order to MedGrid. Once placed, the order is routed to the appropriate vendor for fulfillment.

Order Placement Overview

MedGrid orders are placed as Sales Orders. A Sales Order captures the customer, the items, the quantities, the agreed prices, and the shipping address. Once submitted, MedGrid routes each product line to the correct vendor automatically.

Required Headers

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

Request Body

{
  "customer": "MedGrid Customer ID or Name",
  "transaction_date": "2026-06-18",
  "delivery_date": "2026-06-25",
  "price_list": "Standard Selling",
  "currency": "USD",
  "shipping_address_name": "ADDR-00123",
  "items": [
    {
      "item_code": "VD3-5000-120",
      "qty": 2,
      "rate": 28.50,
      "warehouse": "ShipStation Warehouse - SM"
    },
    {
      "item_code": "OMEGA3-1000-90",
      "qty": 1,
      "rate": 34.00,
      "warehouse": "ShipStation Warehouse - SM"
    }
  ]
}

Request Fields

Success Response

{
  "data": {
    "name": "SAL-2026-00456",
    "docstatus": 0,
    "status": "Draft",
    "customer": "Sunrise Medical Clinic",
    "grand_total": 91.00,
    "transaction_date": "2026-06-18"
  }
}

Simplified Request / Response Example

Consistent with the format described in your integration spec:

// REQUEST
{
  "customer_id": "Sunrise-Medical-001",
  "product_id": "VD3-5000-120",
  "quantity": 2
}

// RESPONSE
{
  "status": "success",
  "order_id": "SAL-2026-00456"
}

Track an Order

Retrieve the current status, fulfillment details, and tracking information for a Sales Order.

Example Request

curl -X GET \
  "https://app.medgrid.com/api/resource/Sales%20Order/SAL-2026-00456" \
  -H "Authorization: token abc123:xyz789"

Example Response

{
  "data": {
    "name": "SAL-2026-00456",
    "status": "To Deliver and Bill",
    "customer": "Sunrise Medical Clinic",
    "transaction_date": "2026-06-18",
    "delivery_date": "2026-06-25",
    "grand_total": 91.00,
    "exoceuticals_status": "Fulfilled",
    "exoceuticals_tracking_number": "1Z999AA10123456784",
    "exoceuticals_carrier": "UPS",
    "exoceuticals_tracking_url": "https://ups.com/track?number=1Z999AA10123456784"
  }
}

Order Status Values

Tracking Fields

Doctor Checkout (503A)

Certain regulated products (503A compounded medications) require additional verification before a doctor can place an order. This section explains the special checkout flow for these items.

What is 503A?

503A compounded medications are pharmaceutical compounds prepared for specific patients by a licensed compounding pharmacy. Federal law requires that the ordering doctor hold a valid license, and that prescription information and patient details are captured at the time of ordering.

Required Fields for 503A Orders

In addition to the standard order fields, 503A orders require:

503A Order Example Request

{
  "customer": "Dr-Jane-Smith-001",
  "transaction_date": "2026-06-18",
  "price_list": "Standard Selling",
  "shipping_address_name": "ADDR-00123",
  "items": [
    {
      "item_code": "BHRT-PROG-200MG",
      "qty": 1,
      "rate": 145.00,
      "warehouse": "ShipStation Warehouse - SM"
    }
  ],
  "checkout_npi_number": "1234567890",
  "checkout_dea_number": "AB1234563",
  "checkout_doctor_first_name": "Jane",
  "checkout_doctor_last_name": "Smith",
  "checkout_doctor_email": "jane.smith@clinic.com",
  "checkout_patient_first_name": "John",
  "checkout_patient_last_name": "Patient",
  "checkout_patient_dob": "1975-03-15",
  "checkout_patient_gender": "Male",
  "professional_use_confirmation": 1,
  "compliance_agreement_accepted": 1
}

Error Handling

What to expect when an API request fails, and how to resolve common issues.

Standard Error Response Format

{
  "exc_type": "PermissionError",
  "_server_messages": "[{\"message\": \"You do not have permission to access this resource.\"}]"
}

HTTP Status Codes

Common Customer API Errors

FAQ

How do I know which Price List to use?

Contact your MedGrid account manager. They will provide the exact Price List name assigned to your account. Use this name as the price_list parameter in all catalog calls.

Can I order items from multiple warehouses in one order?

Yes. Each line item in the order can specify a different warehouse. MedGrid handles multi-warehouse orders automatically, routing each item to the correct fulfillment source.

Why is the rate field null for some items?

This means the item has no price configured in your assigned Price List. You can still see the item's availability but cannot order it until pricing is added. Contact MedGrid to resolve this.

How quickly are orders fulfilled?

Fulfillment time depends on the vendor and product type. Standard orders typically ship within 1–3 business days. Compounded medications (503A) may take 3–5 business days.

Can I cancel an order?

Orders in Draft or "To Deliver" status may be cancellable. Contact MedGrid support immediately if you need to cancel. Orders already shipped cannot be cancelled.

How do I get support?

Email support@medgrid.com or use the MedGrid Customer Portal support chat. Include your account name, order ID, and a description of the issue.