medgrid — MedGrid Vendor CLI

The medgrid command line connects your systems to the MedGrid marketplace: push your catalog, prices, and stock; track product approval; receive and verify order notifications — no integration code required.

Install

pip install medgrid-cli        # or: pipx install medgrid-cli
medgrid --version

Requires Python 3.9+; no other dependencies. To update later: pip install -U medgrid-cli.

No pip in your environment? The tool is a single self-contained file — download it directly and run it with any Python 3.9+:

curl -O https://medgrid.com/assets/medgrid/cli/medgrid
python3 medgrid --help

Before you start

You need API credentials from MedGrid — three values, issued per environment:

They are shown exactly once when generated — store them securely. If lost, MedGrid can rotate them (the client_id stays; both secrets change).

Environments. MedGrid runs two copies of the platform:

• UAT — https://uat.medgrid.com — test environment. Build and verify here first; orders never result in real shipments or charges.
• Production — https://medgrid.com — the live marketplace.

Credentials belong to exactly one environment: a UAT client_id does not exist on production and vice versa. You'll receive UAT credentials to integrate against, and a separate production set at go-live.

Quick start

medgrid init                      # store credentials + verify (UAT is the default)
medgrid whoami                    # confirm who you're connected as
medgrid warehouses --create "Main Warehouse"
medgrid import products.csv --dry-run   # validate without sending
medgrid import products.csv
medgrid status SKU-001 SKU-002    # approval + publish state
medgrid webhook set-url https://yourdomain.com/medgrid-events
medgrid webhook test              # signed test event at that URL
medgrid orders                    # recent orders containing your items

init saves credentials to ./.medgrid/config.json (file mode 600) and immediately verifies them with a live connection test. Failures come back in plain language — including "this environment has never issued this client_id", the most common setup mistake. Access tokens are then obtained, cached, and refreshed automatically; you never handle them.

Every command accepts --env uat or --env prod. UAT is the default; production prints a visible banner before anything runs.

Command reference

Exit codes are honest: 0 only when everything succeeded, 1 otherwise — safe to use in scripts and schedulers. Add --json to warehouses, status, and orders for machine-readable output.

CSV import

Column headers are case-insensitive and common synonyms are understood (title → name, category → group, item_code → sku, …). Unrecognised columns are ignored with a warning. Prices accept $ signs and thousands commas. Rows that fail validation are skipped with a line-numbered reason and are never partially sent.

Behavior you can rely on:

• New products are not public. Everything you push enters MedGrid's review queue (Pending) and appears on the marketplace only when approved. Track it with medgrid status.
• Imports upsert. An existing SKU is updated, not duplicated. If a SKU appears twice in one file, the later row wins.
• Retries are safe. Every batch carries an idempotency key derived from the file's content. Re-running the same file — after a network failure, a crash, even two runs at once — replays the original result instead of applying it twice. Never creates duplicates.
• Large files are handled. Rows are sent in batches of up to 500 (the API's cap). One bad row fails that row only, reported with its CSV line number.
• Stale stock is rejected. Inventory snapshots are timestamped; an older snapshot can never overwrite newer stock.

Receiving notifications (webhooks)

MedGrid POSTs JSON events to your registered URL: order.new, order.cancelled, product.approved, product.rejected, and webhook.test. Each request carries:

X-MedGrid-Event:     order.new
X-MedGrid-Attempt:   1
X-MedGrid-Signature: sha256=<hex digest>

The signature is HMAC-SHA256 of the exact request body, keyed with your webhook_secret. Always verify it before trusting a payload:

import hashlib, hmac
expected = "sha256=" + hmac.new(webhook_secret.encode(), raw_body, hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, request.headers["X-MedGrid-Signature"])

Respond with any 2xx within 10 seconds. Failed deliveries are retried 3 times (after 1, 5, and 15 minutes). If your endpoint was down longer, reconcile with medgrid orders — its payload mirrors the webhook body.

Recommended bring-up sequence: medgrid listen locally to see real signed events → build your endpoint → medgrid webhook set-url → medgrid webhook test → confirm your endpoint answers 200 and the signature verifies.

Limits

• 120 API requests per minute per vendor. Exceeding it returns HTTP 429 with a Retry-After header; the CLI surfaces the message directly. (A full catalog import is only a handful of requests — you're unlikely to hit this outside of tight polling loops.)
• 500 records per batch, 500 SKUs per status call.
• 10 failed authentications per 15 minutes locks a client_id temporarily.

Troubleshooting

Questions or credential requests: contact your MedGrid integration representative.