My inventory

Sellers can authenticate through any platform with Login with MGX and submit inventory to the MGX marketplace — staying anonymous to every buyer until a trade settles. Listings enter the public anonymized marketplace; buyers only ever see them through the anonymized inventory view, never your identity.

The inventory-import scopes (listings.read, listings.write, farms.read, farms.write) are granted to approved partners, not self-service. If you run an inventory-management platform and want to interface with MGX, contact us to have these enabled on your API client.

To list inventory on the marketplace, the seller must have a valid payment method on file with MGX (on the farm the inventory belongs to). A submit or relist without one returns 403 payment_method_required. You can still create a draft with "list": false and publish it later once a payment method is added.

Farms and privacy

A listing is tied to one of your farms. How much farm detail the API returns depends on what the seller consented to:

Without farms.read (e.g. an anonymous-submission platform that could be buyer-operated), farms are returned as an opaque id + coarse location only — never the name or exact coordinates, so the farm can't identify the seller. Map the opaque id to your own records on your side.
With farms.read (a trusted import tool the seller authorized), the full farm name and coordinates are returned, and farms.write lets you create and edit farms via the API.

Either way, you pass the farm's id as farm_id when submitting a listing.

GET/v1/me/farms

List your farms

Your own farms. Opaque by default; full detail with farms.read.

List farms

GET

/v1/me/farms

curl https://api.mygrainexchange.com/v1/me/farms \
  -H "Authorization: Bearer {token}"

GET/v1/me/farms/:id

Get a farm

Full detail for one of your farms. Requires farms.read.

Request

GET

/v1/me/farms/farm_3Kd9

curl https://api.mygrainexchange.com/v1/me/farms/farm_3Kd9 \
  -H "Authorization: Bearer {token}"

POST/v1/me/farms

Create a farm

Name
name
Type
string
Description
Farm name (required).
Name
latitude
Type
number
Description
Latitude (required).
Name
longitude
Type
number
Description
Longitude (required).
Name
nearest_city
Type
string
Description
Nearest city (required).
Name
nearest_province
Type
string
Description
Province / state (required).

Request

POST

/v1/me/farms

curl https://api.mygrainexchange.com/v1/me/farms \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "name": "North Quarter", "latitude": 52.1, "longitude": -106.6, "nearest_city": "Saskatoon", "nearest_province": "SK" }'

PATCH/v1/me/farms/:id

Update a farm

Edit a farm's name or location. Requires farms.write.

Request

PATCH

/v1/me/farms/farm_3Kd9

curl -X PATCH https://api.mygrainexchange.com/v1/me/farms/farm_3Kd9 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "name": "North Quarter (updated)" }'

POST/v1/me/inventory

Submit a listing

Creates a listing and, when list is true (the default), publishes it to the marketplace immediately. Address commodity by slug and grade by name.

Name
commodity
Type
string
Description
Commodity slug, e.g. wheat (required).
Name
farm_id
Type
string
Description
One of your farm ids (required).
Name
quantity_mt
Type
number
Description
Quantity in tonnes (required).
Name
variety
Type
string
Description
Variety.
Name
crop_year
Type
integer
Description
Crop year.
Name
grade
Type
string
Description
Estimated grade name, e.g. 1CWRS.
Name
target_price
Type
object
Description
amount + firm.
Name
is_organic
Type
boolean
Description
Name
quality
Type
object
Description
protein, moisture, test_weight, dockage, falling_number.
Name
list
Type
boolean
Description
Publish immediately (default true).

Request

POST

/v1/me/inventory

curl https://api.mygrainexchange.com/v1/me/inventory \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "commodity": "wheat",
    "farm_id": "farm_id_here",
    "quantity_mt": 120.0,
    "crop_year": 2026,
    "grade": "1CWRS",
    "target_price": { "amount": 315.00, "firm": false },
    "list": true
  }'

GET/v1/me/inventory

List your listings

Your own listings. Filter by status: listed, unlisted, or archived.

Request

GET

/v1/me/inventory

curl https://api.mygrainexchange.com/v1/me/inventory?status=listed \
  -H "Authorization: Bearer {token}"

GET/v1/me/inventory/:id

Get a listing

Read one of your listings in full detail.

Request

GET

/v1/me/inventory/inv_9Hk2

curl https://api.mygrainexchange.com/v1/me/inventory/inv_9Hk2 \
  -H "Authorization: Bearer {token}"

PATCH/v1/me/inventory/:id

Update a listing

Change price, quantity, or listed (publish / unpublish).

Request

PATCH

/v1/me/inventory/inv_9Hk2

curl -X PATCH https://api.mygrainexchange.com/v1/me/inventory/inv_9Hk2 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "target_price": { "amount": 312.0 }, "listed": true }'

DELETE/v1/me/inventory/:id

Archive a listing

Remove a listing from the marketplace.

Request

DELETE

/v1/me/inventory/inv_9Hk2

curl -X DELETE https://api.mygrainexchange.com/v1/me/inventory/inv_9Hk2 \
  -H "Authorization: Bearer {token}"

GET/v1/me/inventory/:id/bids

Bids received

Bids buyers placed on your listing — the buyer stays masked until both invoices are paid. Respond with POST /v1/bids/:id/accept, /reject, or /counter (the same endpoints buyers use; they authorize you as the receiving party). Subscribe to the bid.received webhook to be notified in real time.

Request

GET

/v1/me/inventory/inv_9Hk2/bids

curl https://api.mygrainexchange.com/v1/me/inventory/inv_9Hk2/bids \
  -H "Authorization: Bearer {token}"