Skip to content

API.md

Latest commit

 

History

History
145 lines (112 loc) · 5.43 KB

API.md

File metadata and controls

145 lines (112 loc) · 5.43 KB
Raw

Shipley Farms public data

Last reviewed 2026-09-28.

There is exactly one stable public surface today: a read-only product catalog. This document describes it honestly, including what it will not do for you.

This is not a transactional API. There is no ordering endpoint, no authentication, no stock, no wholesale pricing, and no order status. You can read what we sell. You cannot buy it programmatically, and nothing here will let you. If you need that, you need the partner API, which does not exist yet: see FOR-BUSINESSES.md.

The catalog feed

GET https://shipleyfarmsbeef.com/files/catalog.json

No authentication. No key. No rate limit. It is a static file, so reading it costs us nothing and you can fetch it as often as you find useful.

It is a schema.org ItemList of Product objects. Read numberOfItems rather than hardcoding a count; the catalog changes.

A product record

{
  "@type": "Product",
  "sku": "SS1231",
  "name": "Signature Huston Ribeye",
  "url": "https://shipleyfarmsbeef.com/products/ss1231",
  "category": "Dry-Aged Steaks",
  "brand": { "@type": "Brand", "name": "Shipley Farms" },
  "description": "Our signature steak. Well-marbled and full of flavor.",
  "image": "https://shipleyfarmsbeef.com/files/SS1231.png",
  "offers": {
    "@type": "Offer",
    "url": "https://shipleyfarmsbeef.com/products/ss1231",
    "priceCurrency": "USD",
    "price": 60.3,
    "description": "Sold by the pound. This price is an estimate based on average weight..."
  },
  "x_shipley_catch_weight": true
}
Field Always present Notes
sku yes Our stable identifier. Use this as your key, not name
name yes Display name. Changes for marketing reasons; do not key on it
url yes Canonical product page. Absolute
category yes For example Dry-Aged Steaks, Ground Beef
brand yes Always Shipley Farms
description yes
image yes Absolute. Served at up to 768px; our uploader downscales
offers.price yes USD. Read the catch weight section below before you show this
x_shipley_catch_weight no Present and true on catch weight items
x_shipley_note no Free text when an item needs a caveat

Catch weight: the one thing to get right

Some items are sold by the pound, and beef does not come in exact pounds. For those items offers.price is an estimate based on average weight, and the customer's final charge is the actual weight packed, which may be higher or lower.

If you display our prices, say so. A menu board or storefront that shows $60.30 as a firm price for a catch weight item is showing your customer a number we cannot honour.

price = item["offers"]["price"]
if item.get("x_shipley_catch_weight"):
    label = "about ${:.2f}".format(price)   # estimate, final charge is by actual weight
else:
    label = "${:.2f}".format(price)         # firm

Freshness: this is a snapshot, not a live endpoint

The file carries its own provenance block:

"x_shipley_provenance": {
  "generated_at_utc": "2026-09-26T00:59:05Z",
  "snapshot": true,
  "freshness_warning": "Prices, product availability, and the product list itself change."
}

Read generated_at_utc and act on it. We regenerate after price changes, but there is no guarantee of how recent any given copy is. If your integration quotes a price to a paying customer, link through to url for the live figure, or warn when the snapshot is stale:

import datetime
gen = catalog["x_shipley_provenance"]["generated_at_utc"]
age = datetime.datetime.now(datetime.timezone.utc) - datetime.datetime.fromisoformat(gen)
if age.days > 14:
    ...  # treat prices as indicative only

Availability

availability appears only on items explicitly on backorder. Its absence means unknown, not in stock. Do not build a stock display on this field. If you need real availability, that is a partner API conversation.

What is deliberately not documented here

Our store exposes other endpoints that its own pages call. They are not documented, not supported, not stable, and we ask you not to build on them. They change without notice and anything you build on them will break.

Use catalog.json. If it does not do what you need, open an issue and say so, and we will look at documenting a supported way to get it.

The partner API, in design

A scoped, authenticated API for partners who buy from us. Planned surface:

  • Your price list, scoped to your account
  • Order placement and order status
  • Your invoices and payment terms
  • Shipment tracking and delivery windows

Explicitly never in it: anyone else's data, our costs or margins, and anything touching payment processing.

If you are a restaurant, a distributor, or a store that would buy from us, open an issue tagged partner-api describing what system you are on and what you need to do. We would much rather design this against a real integration than guess at one.

Other public files

URL What it is
/llms.txt Site summary for AI assistants
/agents.md What we ask automated agents to do and not do
/sitemap.xml Standard sitemap
/robots.txt Crawl rules. Please honour them

Questions

Open an issue, or use https://shipleyfarmsbeef.com/helloworld?utm_source=github&utm_medium=repo&utm_campaign=shipley-integrations&utm_content=api-docs if you would rather not use GitHub.