Fold Laboratories

Use this when a buyer wants to stop an alert for new works. Nothing more is sent, and the saved words, filters and address are erased. Needs the search_alert_id and manage_token save_search_alert gave; a buyer can also stop it from any alert e-mail in one click.

Use this when time has passed since a search or a work’s detail answered — the buyer came back later, or is weighing several works — to re-check whether specific impressions can still be bought before offering them. Each work here is unique or from a small edition, so an impression can sell at any time: never offer one as available from an old answer. A search’s offers and get_artwork say what can be bought as they answer, and the checkout checks again itself, so no call is needed between them and the checkout.

Use this when someone wants the full facts about one work before deciding: what it is, its size, how it looks, what delivery costs and when it ships, whether it can be returned, who made it, and what Fold verified about the seller. Full detail for one artwork: attribution, medium, dimensions, edition structure, provenance, seller, and every individual impression that can be bought with its own price and availability. A numbered edition has one entry per impression — including artist proofs (AP), printer proofs (PP), and the bon à tirer (BAT), which are separate objects from the numbered run and usually priced differently. Each entry in `attributes` says who stands behind it (seller_stated, fold_derived or fold_verified), and a null means unspecified rather than estimated. Also returns image URLs to show the buyer. A signed URL is TEMPORARY: honour its `expires_at` and re-fetch rather than caching or redistributing it. An image marked `permanent` is one of the work’s public images, with no expiry: a clean display copy, or, where it also says `preview`, a reduced copy watermarked by Fold. Use this before presenting a work to a buyer, and quote the `impression` label exactly as given. Its public images, up to 3, also come as small pictures attached after the answer, so you can see how it looks.

Use this when a buyer asks what a work will cost delivered to them and when it would arrive. Given one listing_id and a US destination (a five-digit ZIP code, and the state if known), it answers with the price, the seller’s delivery charge, an ESTIMATE of sales tax from Fold’s tax engine for that ZIP code, the total, the date the seller says it ships by and the arrival window their transit estimate gives, the returns that apply, the policy links and how to check out. Read-only: nothing is opened or reserved. Checkout calculates the exact tax from the full address before the buyer pays. Fold delivers only to the 50 US states and DC.

Use this when a buyer asks where their order is or what they can still claim. With the token from the order page’s address, or the order reference from the confirmation e-mail and the e-mail address the buyer gave at checkout, it answers with the order’s status, the tracking the seller recorded, and each return or claim window with when it closes. An order is shown only to whoever proves they placed it; an unknown order and a wrong proof get the same answer.

Use this when a buyer asks about an alert for new works they saved: whether it is waiting for them to confirm it, active or ended, what it watches, when it last sent works and when it ends. Needs the search_alert_id and manage_token save_search_alert gave.

Use this when a buyer wants to return a work or report a problem with an order: damage or a difference from the description on arrival, non-delivery, a doubt about authenticity or title, an agent purchase they did not authorise, cancelling before dispatch, or a 30-day return. It checks the ground against the Returns policy’s window for this order, records the request for a person at Fold, and answers with a link for sending photographs. It refunds nothing: a person at Fold decides every request and replies by e-mail. Needs the same proof as get_order_status.

Use this when a buyer wants to hear about works listed later that match what they are looking for. It saves the search — the buyer’s words in query and the same filters as search_artworks — and tells the buyer by e-mail, or your own system by webhook, when a work that matches it is listed: only works that meet everything asked, never near matches, at most one alert a day, for 180 days. An e-mail alert starts only when the buyer confirms it from the one e-mail Fold sends to ask; ask the buyer before giving Fold their address. Every alert e-mail has one-click unsubscribe. A webhook alert starts once webhook_url answers a signed verification event by echoing its challenge. Works flagged as mature content are left out unless include_mature is true, which only the buyer’s own request should set. Answers with search_alert_id and manage_token, shown once: get_search_alert reads the alert and cancel_search_alert ends it.

Use this when someone wants to find original paintings, prints, photographs or sculpture from independent artists: by subject, style, colour, size or budget; for a particular wall; or like a work or a photo they have. It returns only works that meet everything asked for, each with what it met. near_matches come apart, each saying what it misses or what its seller left unsaid: a blank fact is unknown, never a no. Write the request in words ("a large blue abstract painting under $2,000"; misspellings, and Spanish, Portuguese, French, Italian and German, are read) or send filters — min_price_usd, max_price_usd, orientation, subject, style, medium, colors, min_height_in, max_height_in, min_width_in, max_width_in, ships_to, framed, ready_to_hang, signed, edition — and a filter wins over the words. applied_filters lists every constraint and where it came from; understood says how each word was read (read_as, corrected); correct a misreading with a filter. A word about the work that names no constraint must appear in its own words to match ("lighthouse"). Words of mood ("calm") and of where it will hang ("hallway") only order the results; "to hang" and "a gift" are not used. A place it ships to, with its state or ZIP, is read as ships_to. fold_derived marks Fold’s reading of the seller’s words. This catalogue CANNOT be filtered by authenticity or provenance strength: Fold verifies sellers, not works (see _verification). Works on sale now; include_sold adds sold works. Attributes are the seller’s; null means unspecified, never estimated. completeness says whether every work was checked. A wall — wall: {width, height, furniture_width, furniture_height, unit} — keeps only works whose size suits it by Fold’s rules of thumb, and wall_fit gives the size range and the reasoning to relay: a rule of thumb, not a measurement of the room. With a wall, query may be left out. similar_to {artwork_id | image_url | image_base64} keeps only works that look like it, at or above Fold’s simi…

Use this when the buyer has chosen one work and wants to buy it. It answers with checkout_url, a page on Fold’s own site for that one work, where the buyer enters the delivery address, sees the total with sales tax and the terms, and pays. It charges nothing and reserves nothing: the work can still sell to someone else until the buyer presses Pay, and the link works once and lapses at expires_at. Give the link to the buyer or open it in your browser. It checks availability itself, so call it straight from a search’s offer.listing_id or get_artwork’s listings, with no other call first; one listing_id per call, since each work is its own purchase. The buyer needs no account and never signs in: on the page they give a name, an e-mail for the order confirmation and a US delivery address, and pay. If the work has sold, or another buyer is paying for it, the refusal carries out_of_stock: what the work is now, and up to three similar works on sale here to offer the buyer instead.