For retailers

Merchant API

Send your store’s products, prices and stock to lowerSpendings from your own systems. It’s free, and it’s the same API our own store integrations use. This page has everything a developer needs to judge the work before you create an account.

Base URL https://lowerspendings.com/api

Authentication

Every request carries an API key in two headers, x-api-key and x-api-secret. Create keys in your store dashboard once you’ve signed in. The secret is shown only once; we store a hash of it. Revoke a key there and it stops working at once.

KeyActs onHow to name the store
Account key (what the dashboard creates)Every store your account owns; it can also register new onesThe store’s slug in the x-merchant-slug header (required)
Store key (older keys)One store onlyImplied by the key: don’t send x-merchant-slug

A key can only register your own stores and send their products: it can’t read, change or delete anything else. A store’s slug is its name in the API: 2 to 64 lowercase letters, digits and hyphens, unique among your stores. The dashboard shows it and makes one when you register a store there.

Register a store PUT /merchants/{slug}

Optional if you registered the store in the dashboard. Useful when you run several stores or want your system to set itself up. Needs an account key. It’s idempotent: calling it again for a slug you already have changes nothing, except that it fills in a website the store doesn’t have yet. Add ?update=1 to overwrite the name, logo and website with what you send.

curl -X PUT https://lowerspendings.com/api/merchants/harbour-home-supplies \
  -H "x-api-key: $API_KEY" \
  -H "x-api-secret: $API_SECRET" \
  -H "content-type: application/json" \
  -d '{"name": "Harbour Home Supplies", "website": "https://www.harbourhome.com.au"}'
Request body (JSON object)
FieldTypeDescription
name requiredstringYour store's name as shoppers know it, 1 to 200 characters. Example: "Harbour Home Supplies"
website optionalstringYour store's website, starting with http:// or https://. Example: "https://www.harbourhome.com.au"
avatar optionalstringThe address of your store's logo. Example: "https://www.harbourhome.com.au/logo.png"
isAdultsOnly optionalbooleantrue when your store mainly sells adults-only (18+) products. Once set, only we can clear it. Example: false

201 when it created the store, 200 when the store was already there (outcome exists) or an older store of yours with exactly this name got the slug (adopted). updated lists the fields that changed.

{
  "id": "Xk3v9TqL2mP8wR4a",
  "slug": "harbour-home-supplies",
  "outcome": "created",
  "updated": []
}

An account can register up to 20 stores this way; talk to us if you need more.

Send products POST /product/bulk

Creates or updates up to 500 products of one store. A product is identified by your sku: sending a SKU again updates that product. The body is a JSON array.

curl -X POST https://lowerspendings.com/api/product/bulk \
  -H "x-api-key: $API_KEY" \
  -H "x-api-secret: $API_SECRET" \
  -H "x-merchant-slug: harbour-home-supplies" \
  -H "content-type: application/json" \
  -d '[
    {
      "sku": "CAT-TOY-1",
      "name": "Feather Wand Cat Toy",
      "price": 10.99,
      "url": "https://www.yourstore.com.au/products/feather-wand",
      "image": "https://www.yourstore.com.au/images/feather-wand.jpg",
      "brand": "Purrfect",
      "categoryHint": "Pet Supplies > Cat Supplies > Cat Toys",
      "inStock": true,
      "gtin": "9312345678907",
      "modelNumber": "PF-WAND-01",
      "colour": "Pink",
      "size": "Large"
    }
  ]'
Each product (JSON object)
FieldTypeDescription
sku requiredstringYour own code for the product, unique within your store. It identifies the product from one upload to the next: send the same SKU to update it. A request may not repeat a SKU. Example: "CAT-TOY-1"
name requiredstringThe product's name as your store shows it. HTML entities are decoded. Example: "Feather Wand Cat Toy"
price requirednumberWhat a shopper pays today, in Australian dollars, greater than 0. Every change is kept in the product's price history. Example: 10.99
url requiredstringThe product's page on your website, starting with http:// or https://. Shoppers who click through land here. Example: "https://www.yourstore.com.au/products/feather-wand"
image optionalstringThe address of the product's main image. Example: "https://www.yourstore.com.au/images/feather-wand.jpg"
description optionalstringThe product's description, as HTML or plain text; we convert it to text. One over 256 KiB is left out (the product is still imported). Example: "<p>A feather wand for indoor cats.</p>"
brand optionalstringThe product's brand. Example: "Purrfect"
categoryHint optionalstringYour own category for the product, for example its breadcrumb. A hint: we place every product in our own category tree. Example: "Pet Supplies > Cat Supplies > Cat Toys"
inStock optionalboolean or nullWhether the product is in stock. Omit it or send null when you don't know; the last value you reported is kept. Example: true
gtin optionalstringThe barcode number (GTIN, EAN or UPC: 8, 12, 13 or 14 digits). One with a wrong check digit is ignored. The most useful field for matching your product with other stores'. Example: "9312345678907"
modelNumber optionalstringThe manufacturer's model or part number (MPN), up to 200 characters. Example: "PF-WAND-01"
colour optionalstringThe product's colour as your store names it, up to 200 characters. Example: "Pink"
size optionalstringThe product's size as your store names it (a clothing size, a length, a capacity), up to 200 characters. Example: "Large"

Text fields are stored as you send them, apart from decoded HTML entities. For gtin, modelNumber, colour and size, a value you send replaces the one you sent before, and leaving the field out keeps it. Other fields not listed here are ignored.

Limits and retries

  • 1 to 500 products per request, and at most 4 MiB per request body. Our own uploaders keep each request under about 1 MB.
  • A description over 256 KiB is left out; the product is still imported.
  • There’s no fixed rate limit. Send requests one after another rather than in parallel.
  • Requests are safe to repeat: an upload is an update keyed on your SKU. Retry a timeout, a 429 or any 5xx with an increasing delay. Don’t retry other 4xx answers unchanged: fix the request.

Keeping it current, and removing products

  • Every product you send is marked as seen that day. Send your whole catalogue at least once a day; sending changes as they happen as well is welcome.
  • There’s no delete call. To remove a product, stop sending it: a product not sent for 5 days leaves search and category pages, and after 7 days its product page lists it as no longer available at your store.
  • Prices and stock: we show the price you sent last. Each price change is added to the product’s price history, which drives price-drop labels and shoppers’ price alerts.

Responses and errors

StatusMeaning
200POST /product/bulk: every product was saved (body OK).
201 / 200PUT /merchants/…: created / already there or adopted.
400The body or a header doesn’t validate: a missing required field, a price of 0, a URL without http(s)://, more than 500 products, a SKU twice in one request, a missing or malformed x-merchant-slug with an account key, or one sent with a store key. The body says which (message or error). Nothing in the request was saved.
401The key or secret is missing or wrong, or the key was revoked.
403The key may not act on that store, a store key tried to register a store, or your account has reached its 20 registered stores.
404You have no store with that slug: register it first.
409Registering: several of your older stores have that exact name; pick one with us.
413The request body is over 4 MiB: send smaller batches.
5xxOur side failed; nothing was saved. Retry later.

Error bodies are JSON with an error (and for validation errors a message) string.

After the import

  • Publication. There’s no review queue: products are on the site, in search and on your store’s page, usually within minutes.
  • Categories. We place each product in our own category tree (based on the Shopify Product Taxonomy) automatically, from its name, description and your categoryHint. People review uncertain cases; you don’t need to map your categories to ours.
  • Matching. We match your products with other stores’ listings of the same item, so shoppers see your price next to theirs on one product page, and group sizes and colours as options of one product. Barcodes (gtin) and model numbers make this much more reliable; matching usually settles over the following day.
  • Ranking. Nobody can pay for a better place. See how we rank.

Ready to connect?