Vendor Integration Guide

Everything you need to connect your vendor system with the MedGrid Marketplace — from first authentication to live order tracking.

What is Vendor Integration?

Vendor integration means linking your business (pharmacy, fulfillment company, or product supplier) to the MedGrid platform so that orders, inventory, and shipment data flow automatically between your systems and MedGrid. Once connected, you no longer need to manually copy orders or update tracking numbers — it all happens in real time.

What Can Be Synchronized

Integration Types

Complete Integration Workflow

Vendor Onboarding

How a new vendor account is created and what happens at each stage.

Account Lifecycle

What Gets Created When You Are Approved

When MedGrid approves your vendor account, the following records are automatically created:

• User Account — Login credentials for the MedGrid portal and API access.
• Vendor Profile — Your public-facing profile on the marketplace (company name, description, logo, contact details).
• Supplier Record — Internal record used to route orders to your fulfillment queue.
• Contact & Address — Your primary contact and business address for invoicing.

Onboarding Checklist

• 1Log in to the MedGrid Vendor Portal with your welcome email credentials.
• 2Complete your Vendor Profile (logo, description, contact details, social links).
• 3Upload your initial product catalog with descriptions, SKUs, and pricing.
• 4Wait for MedGrid catalog review — products must be approved before they appear.
• 5Connect your ShipStation or Shopify account from the Integrations Portal.
• 6Optionally verify your phone for SMS helpdesk support.
• 7Run a test sync to confirm orders and tracking flow correctly.

Authentication

Every API request to MedGrid must include valid credentials. There are two methods depending on how you are connecting.

Method 1 — API Key + Secret (Recommended for Systems)

This is the correct method for automated integrations, background sync jobs, and any software-to-software communication. It works like a username and password combination but is designed for machines rather than humans.

How to Generate Your Credentials

1. Log in to the MedGrid Vendor Portal.
2. Navigate to User Settings > API Access.
3. Click Generate Keys to create your API Key and API Secret.
4. Copy both values and store them securely (treat them like passwords).

Authorization Header

Include the following header in every API request:

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

Example API Request

curl -X POST "https://app.medgrid.com/api/method/medgrid.integrations.list_connections" \
  -H "Authorization: token abc123key:xyz789secret" \
  -H "Content-Type: application/json"

Method 2 — Session Cookie (Browser Portal)

When you log in to the MedGrid Vendor Portal in a browser, MedGrid issues a session cookie (sid) that is automatically sent with every request. This method is only for browser-based portal access — not for automated systems.

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

On success, a session cookie is set automatically. The browser includes it on every subsequent request for the duration of the session.

Base URL

Vendor Profile

Your Vendor Profile is your public identity on the MedGrid marketplace. Customers and sales reps see your profile when browsing products.

Profile Fields

Social Profile

Optionally link your social media accounts to enhance your marketplace profile visibility. Supported platforms: LinkedIn, Instagram, Twitter/X, Facebook.

Product Synchronization

How vendors upload, update, and maintain their product catalog on MedGrid.

Product Lifecycle

Every product in MedGrid follows an approval workflow before it can be sold on the marketplace:

Product Data Fields

When creating or syncing a product, include the following fields:

Example Product Payload

{
  "item_code": "VD3-5000-120",
  "item_name": "Vitamin D3 5000 IU (120 Softgels)",
  "description": "<p>High-potency Vitamin D3 to support immune function, bone health, and mood.</p>",
  "item_group": "Supplements",
  "brand": "NutriCore Labs",
  "stock_uom": "Box",
  "standard_rate": 28.50,
  "is_stock_item": true,
  "default_supplier": "NutriCore-001",
  "image": "https://cdn.yourcompany.com/products/vd3-5000.jpg"
}

SKU Mapping

MedGrid uses your item_code as the primary SKU. When integrating with ShipStation or Shopify, the SKU is used to map products across systems:

Inventory Management

Keep your product availability up to date so customers always see accurate stock levels.

How Inventory Works in MedGrid

MedGrid tracks inventory per product per warehouse. Each warehouse represents a physical or virtual fulfillment location. When a customer browses your products, they see real-time available quantities from the relevant warehouse.

Inventory Data Fields

Inventory Update Methods

Pricing & Discounts

MedGrid supports flexible, multi-tier pricing so vendors can set different prices for different customer segments.

Price Lists

MedGrid uses named Price Lists to manage pricing. A Price List is a named set of prices that applies to a specific customer group or sales channel. When a customer views your product, MedGrid automatically applies the Price List assigned to their account.

Pricing Data Fields

Price Allowance (Rate Tolerance)

MedGrid may define a price rate allowance on your vendor account. This sets the maximum percentage by which a sales rep can adjust your catalog price during order creation. For example, a ±5% allowance means a rep can apply up to 5% discount or markup. This prevents pricing inconsistencies in the marketplace.

Promotional Pricing

To set a promotional price for a limited time, create an Item Price record with valid_from and valid_upto dates. The system automatically switches back to the standard price when the promotion expires. You do not need to manually revert it.

Order & Fulfillment

How vendors receive orders, confirm them, fulfill them, and update MedGrid with shipping information.

How Vendors Receive Orders

When a customer places an order on MedGrid that includes your products, a Sales Order is created and your items are automatically routed to your fulfillment system based on your integration setup:

• If you use ShipStation: The order is pushed directly into your ShipStation queue. You process it in ShipStation normally.
• If you use Shopify: A new order is created in your connected Shopify store automatically.
• If you use Direct (Portal): The order appears in your Vendor Dashboard under pending fulfillments.

Order Fields You Will Receive

Order Status Flow

Shipment Tracking Updates

Tracking numbers flow back to MedGrid automatically when using the ShipStation integration. MedGrid polls ShipStation for shipment data on your pushed orders and writes the tracking number and carrier to the Delivery Note record.

For Shopify-fulfilled orders, Shopify sends a webhook when the order is fulfilled, which MedGrid processes to update the order status and tracking information in real time.

Integrations Portal

The Integrations Portal at /portal/integrations is your self-service hub for connecting your third-party accounts to MedGrid. No admin involvement needed.

Available Integrations

Integration Status

Each integration shows a real-time status pill in the portal:

Integration Permissions

Each integration requests specific permissions (scopes) that describe exactly what data MedGrid can read or write. These are shown before you connect:

ShipStation Integration

Connect your own ShipStation account to push MedGrid orders directly into your shipping queue and pull tracking numbers back automatically.

What ShipStation Does in MedGrid

• MedGrid Sales Orders assigned to your products are pushed to your ShipStation account as new orders.
• You process and ship them normally inside ShipStation.
• MedGrid periodically pulls tracking numbers and carrier information from ShipStation and stamps them on the Delivery Note.
• Customers receive automatic shipping notifications via MedGrid.

Connecting ShipStation

1. Log in to ShipStation and go to Account Settings > API Settings.
2. Copy your API Key and API Secret.
3. In the MedGrid Vendor Portal, go to Integrations.
4. Click Connect next to ShipStation.
5. Enter your API Key and API Secret, then click Connect.
6. MedGrid tests the credentials immediately — you'll see a success confirmation.

Connect via API

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

Response on success:

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

Response on invalid credentials:

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

Manual Sync

You can trigger a manual sync at any time — either from the portal or via API. This pushes all unfulfilled MedGrid orders to ShipStation and pulls tracking numbers for previously pushed orders.

{
  "integration_type": "shipstation"
}

Response:

{
  "message": {
    "ok": true,
    "stats": {
      "orders_pushed": 3,
      "tracking_pulled": 5,
      "round_trip_ok": true
    }
  }
}

Test Connection

{
  "integration_type": "shipstation"
}

Response:

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

Disconnect

{
  "integration_type": "shipstation"
}

Order Payload Sent to ShipStation

When MedGrid pushes an order to ShipStation, the following data is included:

Shopify Integration

Connect your own Shopify store to MedGrid. Sync your product catalog bidirectionally and receive MedGrid orders as Shopify orders.

What the Shopify Integration Does

• MedGrid imports your Shopify product catalog and links each variant to its matching MedGrid Item via SKU.
• New MedGrid Sales Orders for your products are created as orders in your Shopify store.
• When Shopify marks an order as fulfilled, MedGrid receives the tracking information via webhook and updates the customer's order status.

OAuth Connection Flow

Shopify uses the industry-standard OAuth 2.0 protocol. You do not share your Shopify admin password — instead you grant MedGrid specific read/write permissions on your store.

Step 1 — Start the Install

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

Response:

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

Open the authorize_url in a browser (or a popup). You will be taken to Shopify's permission approval screen.

Step 2 — Approve Permissions in Shopify

Shopify shows you a screen listing the permissions MedGrid is requesting:

• Read and write your products
• Read and write your orders

Click Install app to approve. Shopify will redirect back to MedGrid automatically.

Step 3 — OAuth Callback (Automatic)

Shopify redirects to MedGrid's callback URL with a temporary code. MedGrid exchanges this code for a permanent access token and saves it to your integration. The popup closes and your Integrations Portal shows "Connected".

Manual Sync

{
  "integration_type": "shopify"
}

Response:

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

Permissions Requested

SMS / iMessage Integration

Verify your mobile phone number to get AI-powered MedGrid support via SMS or iMessage — on demand, from your phone.

What You Get

• Text the MedGrid helpdesk number at any time to ask questions about your orders, account, or catalog.
• The AI assistant knows your account — no need to re-explain who you are.
• Receive order status updates and tracking notifications on demand.

How to Connect

1. In the Vendor Portal, go to Integrations and find the SMS / iMessage card.
2. Enter your US mobile phone number.
3. Click Send Verification Code. You'll receive a 6-digit OTP via SMS.
4. Enter the code to confirm. Your phone is now verified and linked to your MedGrid account.

Webhooks

Webhooks allow external systems to push real-time updates to MedGrid as events happen — no polling required.

How Webhooks Work

A webhook is an HTTP POST request that an external system (Shopify, ShipStation) sends to MedGrid when something happens — for example, when a Shopify order is fulfilled. MedGrid receives the event, verifies its authenticity, and updates the relevant order or delivery record automatically.

Inbound Webhook Endpoints

Webhook Security — HMAC Verification

MedGrid verifies every inbound webhook using HMAC-SHA256 to ensure the request is genuine and has not been tampered with.

Each webhook must include an X-Shopify-Hmac-Sha256 header containing a Base64-encoded HMAC signature of the raw request body, signed with your shared webhook secret.

X-Shopify-Hmac-Sha256: BASE64(HMAC_SHA256(webhook_secret, raw_request_body))

Webhook Event Payload (Shopify Order Fulfilled)

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

Webhook Topics Supported

Error Handling

What to do when an API call or integration fails.

Standard Error Response

When a MedGrid API call fails, the response includes a server message describing what went wrong:

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

HTTP Status Codes

Integration-Specific Errors