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.
https://lowerspendings.com/apiAuthentication
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.
| Key | Acts on | How to name the store |
|---|---|---|
| Account key (what the dashboard creates) | Every store your account owns; it can also register new ones | The store’s slug in the x-merchant-slug header (required) |
| Store key (older keys) | One store only | Implied 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"}' | Field | Type | Description |
|---|---|---|
name required | string | Your store's name as shoppers know it, 1 to 200 characters. Example: "Harbour Home Supplies" |
website optional | string | Your store's website, starting with http:// or https://. Example: "https://www.harbourhome.com.au" |
avatar optional | string | The address of your store's logo. Example: "https://www.harbourhome.com.au/logo.png" |
isAdultsOnly optional | boolean | true 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"
}
]' | Field | Type | Description |
|---|---|---|
sku required | string | Your 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 required | string | The product's name as your store shows it. HTML entities are decoded. Example: "Feather Wand Cat Toy" |
price required | number | What a shopper pays today, in Australian dollars, greater than 0. Every change is kept in the product's price history. Example: 10.99 |
url required | string | The 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 optional | string | The address of the product's main image. Example: "https://www.yourstore.com.au/images/feather-wand.jpg" |
description optional | string | The 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 optional | string | The product's brand. Example: "Purrfect" |
categoryHint optional | string | Your 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 optional | boolean or null | Whether 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 optional | string | The 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 optional | string | The manufacturer's model or part number (MPN), up to 200 characters. Example: "PF-WAND-01" |
colour optional | string | The product's colour as your store names it, up to 200 characters. Example: "Pink" |
size optional | string | The 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
429or any5xxwith an increasing delay. Don’t retry other4xxanswers 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
| Status | Meaning |
|---|---|
200 | POST /product/bulk: every product was saved (body OK). |
201 / 200 | PUT /merchants/…: created / already there or adopted. |
400 | The 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. |
401 | The key or secret is missing or wrong, or the key was revoked. |
403 | The key may not act on that store, a store key tried to register a store, or your account has reached its 20 registered stores. |
404 | You have no store with that slug: register it first. |
409 | Registering: several of your older stores have that exact name; pick one with us. |
413 | The request body is over 4 MiB: send smaller batches. |
5xx | Our 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.