Customer API

Authentication

Credentials are issued by a MedGrid administrator from your Customer record — there is no self-service signup. You exchange them once for a one-hour token, then send that token on every call. A raw token client_id:client_secret header is rejected with 401; the Bearer token is the only accepted method.

curl -X POST \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  "$BASE/api/method/medgrid.customer_api.auth_token"

{ "message": {
    "ok": true,
    "access_token": "eyJhbGciOi…",
    "token_type": "bearer",
    "expires_in": 3600,
    "scope": "customer_api",
    "customer": "CUST-00042"
} }

Conventions

Every response is wrapped by the framework in a message key, so the body is {"message": <result>} and each result carries an ok flag. The catalog endpoints are GET. auth_token, create_order and request_payment_link are POST-only; get_shipping_options and get_order_status are reads and accept GET.

{ "message": { "ok": false, "error": "Human-readable message.",
              "code": "PermissionError", "status": 403 } }

Catalog

Seven read endpoints under medgrid.customer_api.*, each scoped to your account: you only ever see your own catalog, your own prices and your own warehouses.

{ "message": {
    "ok": true,
    "customer": "CUST-00042",
    "status": "Active",
    "item_selection": "All",
    "price_list": "Sunrise Wholesale",
    "currency": "USD",
    "markup_pct": 0.0,
    "warehouses": ["Main Warehouse - MG", "East DC - MG"]
} }

Ordering

Four endpoints under medgrid.customer_api_orders.*. They use the same Bearer token as the catalog, but must be switched on separately — ask your administrator to tick Allow API Ordering. Until then every call here returns 403.

1. 1

   You call get_shipping_options

   Tells you which shipping methods your basket qualifies for and what each costs.

2. 2

   You call create_order

   MedGrid validates the SKUs against your catalog, checks stock and credentials, prices every line and builds a draft. Nothing is charged and no stock moves.

3. 3

   MedGrid emails the customer

   The same call emails the draft as a quotation carrying a payment link, valid for 48 hours.

4. 4

   The customer pays the link

   Payment triggers automatic order submission and invoicing. If submission fails after settlement, the payment stays Paid and the order remains a draft for recovery.

5. 5

   You poll get_order_status

   Check payment_status and docstatus separately, then monitor the order's delivery and billing progress. A paid draft needs MedGrid support, not another payment.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'items=[{"sku":"VD3-5000-120","qty":2}]' \
  -d "shipping_rule=Standard Shipping" \
  -d "external_ref=PO-2026-0184" \
  "$BASE/api/method/medgrid.customer_api_orders.create_order"

Payment lifecycle

The terminal values below end payment polling. Order submission and fulfilment have their own state: continue checking docstatus and the order status separately.

Rate limits

Each limit is a fixed 60-second window. Go over one and you get 429 with a Retry-After header naming the seconds until that window rolls over.

Errors

Failures return a clean, human-readable message — never a raw stack trace. The HTTP status and a stable code let you branch in software; the error string is safe to show a person.