cancel_purchase

Use this when the buyer decides not to buy. Abandon a purchase and release any hold on the work, so another collector can buy it. A purchase already being paid for cannot be cancelled: it will complete, or be resolved by a person at Fold, so read it again later; a completed one cannot be cancelled either, and needs a refund instead.

destructive

Argument	Type	Description
checkout_id*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "checkout_id"
  ],
  "properties": {
    "checkout_id": {
      "type": "string",
      "maxLength": 36,
      "minLength": 1
    }
  }
}

check_availability

Use this right before offering a buyer a specific work or impression, to confirm it can still be bought. Re-check whether specific impressions are still purchasable, immediately before presenting them to a buyer or attempting a purchase. Each work here is unique or from a small edition, so an impression can sell between search and checkout. ALWAYS call this before offering a specific impression — offering a sold original is worse than offering nothing.

read-only

Argument	Type	Description
listing_ids*	array	listing_id values from get_artwork.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "listing_ids"
  ],
  "properties": {
    "listing_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "maxItems": 50,
      "minItems": 1,
      "description": "listing_id values from get_artwork."
    }
  }
}

confirm_purchase

Use this only once the buyer has seen the full total and said yes: it pays for the work. Only for agents whose operator has a payment agreement with Fold. Charge for the work. Calling this ASSERTS that the buyer has seen the full total — work, delivery and tax — and approved it; that approval is recorded as the consent record for this sale, so do not call it speculatively or to "check" anything. Pass the approval_reference of the response the buyer was shown: it fingerprints the work, price, delivery, address, tax and total, and if any of them changed since, this is REFUSED before anything is reserved or charged — read the purchase again, re-present it, and confirm with the new reference. The work is reserved at this moment and not before. If the seller changed the price after the buyer approved, this DECLINES rather than silently charging the new figure — re-present the purchase and ask again. Retrying with the same idempotency_key replays the original result, a sale or a decline, and cannot charge twice; a new attempt after a decline, usually with another payment method, needs a new key, and a different key on the same purchase can charge.

destructive

Argument	Type	Description
checkout_id*	string
payment_token*	string	A scoped payment credential: a Stripe shared payment token issued to Fold’s own Stripe network business profile — the payment.network_business_profile_id on every purchase response — never to the seller’s. Never a card number.
idempotency_key*	string	UUID. The same key replays; a new one is a new attempt.
approval_reference

get_artwork

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.

read-only

Argument	Type	Description
artwork_id*	string	artwork_id from search_artworks.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "artwork_id"
  ],
  "properties": {
    "artwork_id": {
      "type": "string",
      "minLength": 1,
      "description": "artwork_id from search_artworks."
    }
  }
}

get_delivered_quote

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.

read-only

Argument	Type	Description
listing_id*	string	A listing_id from get_artwork.
destination*	object

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "listing_id",
    "destination"
  ],
  "properties": {
    "listing_id": {
      "type": "string",
      "maxLength": 128,
      "minLength": 1,
      "description": "A listing_id from get_artwork."
    },
    "destination": {
      "type": "object",
      "required": [
        "country",
        "postal_code"
      ],
      "properties": {
        "region": {
          "type": "string",
          "maxLength": 56,
          "description": "The state, e.g. CO or Colorado."
        },
        "country": {
          "type": "string",
          "maxLength": 56,
          "minLength": 2,
          "description": "US: Fold delivers only within the US."
        },
        "postal_code": {
          "type": "string",
          "maxLength": 10,
          "minLength": 5,
          "description": "A five-digit US ZIP code."
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

get_order_status

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.

read-only

Argument	Type	Description
buyer_email	string	The e-mail address the buyer gave at checkout. Send with order_reference.
order_token	string	The token in the order page’s address, from the confirmation e-mail: /order/<token>.
order_reference	string	The order reference printed in the confirmation e-mail. Send with buyer_email.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "buyer_email": {
      "type": "string",
      "maxLength": 320,
      "minLength": 3,
      "description": "The e-mail address the buyer gave at checkout. Send with order_reference."
    },
    "order_token": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The token in the order page’s address, from the confirmation e-mail: /order/<token>."
    },
    "order_reference": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The order reference printed in the confirmation e-mail. Send with buyer_email."
    }
  },
  "additionalProperties": false
}

get_purchase

Use this to see where a purchase the buyer started stands. Read the current state of a purchase you started. Totals and availability reflect this moment, not when it was started — a work can sell to another buyer while yours is deciding.

read-only

Argument	Type	Description
checkout_id*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "checkout_id"
  ],
  "properties": {
    "checkout_id": {
      "type": "string",
      "maxLength": 36,
      "minLength": 1
    }
  }
}

open_claim

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.

Argument	Type	Description
ground*	string	The ground, as Returns §2 names it.
buyer_email	string	The e-mail address the buyer gave at checkout. Send with order_reference.
description	string	What went wrong, in the buyer’s words.
order_token	string	The token in the order page’s address, from the confirmation e-mail: /order/<token>.
order_reference	string	The order reference printed in the confirmation e-mail. Send with buyer_email.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "ground"
  ],
  "properties": {
    "ground": {
      "enum": [
        "cancellation_before_dispatch",
        "unauthorised_agent_purchase",
        "damaged_or_not_as_described",
        "not_delivered",
        "authenticity_or_title",
        "thirty_day_return"
      ],
      "type": "string",
      "description": "The ground, as Returns §2 names it."
    },
    "buyer_email": {
      "type": "string",
      "maxLength": 320,
      "minLength": 3,
      "description": "The e-mail address the buyer gave at checkout. Send with order_reference."
    },
    "description": {
      "type": "string",
      "maxLength": 2000,
      "description": "What went wrong, in the buyer’s words."
    },
    "order_token": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The token in the order page’s address, from the confirmation e-mail: /order/<token>."
    },
    "order_reference": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The order reference printed in the confirmation e-mail. Send with buyer_email."
    }
  },
  "additionalProperties": false
}

search_artworks

Use this when someone wants to find original paintings, prints, photographs or sculpture from independent artists by subject, style, colour, size or budget. It returns only works that meet everything asked for, each with what it met; works that meet only part come back separately as near_matches, each saying what it misses. A request can be written in words ("a large blue abstract painting under $2,000") or sent as 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 same thing read from the words. applied_filters lists every constraint used and where it came from; check it, and correct a misreading with a filter. A word that names no constraint must appear in a work’s own words to match ("lighthouse"); words of mood ("calm") only order the results. This catalogue CANNOT be filtered by authenticity or provenance strength: Fold verifies sellers, not works (see _verification). Works on sale now are returned; include_sold adds sold works. Attributes are as the seller stated them, and a null means unspecified, never estimated. completeness says whether every work was checked.

read-only

Argument	Type	Description
limit	integer	Maximum matches. Default 10, hard cap 100.
query*	string	What the buyer is looking for, in their words.
style	array	Any of these styles.
colors	array	Every one of these among the colours the seller confirmed for the work.

set_delivery

Use this when the buyer gives the address the work should go to: it prices delivery and sales tax into the total. Supply the delivery address, which is what makes a total payable. Fold delivers only to the 50 states and DC. Sales tax depends on where the work is going and is recalculated on every call, so the total can change here. The work itself cannot be changed; start a new purchase instead. Until this succeeds, total_is_payable is false and the total must not be quoted as final. The response carries a new approval_reference: present THIS response to the buyer, and pass its approval_reference to confirm_purchase.

Argument	Type	Description
city*	string
line1*	string
line2	string
region*	string	One of the 50 states or DC, as its two-letter USPS code, e.g. CO (its name, e.g. Colorado, is read too). Stored as the code. Territories and military addresses are refused.
country*	string	US: Fold delivers only within the United States. ISO 3166-1 alpha-2.
buyer_name	string
buyer_email	string
checkout_id

start_purchase

Use this when the buyer has chosen one work and wants to buy it. Begin buying ONE impression. An impression is a single physical object — a unique painting, or one numbered print of an edition — so exactly one listing_id is accepted; to buy several works, start a separate purchase for each, because each is sold by its own seller and is a separate payment to Fold. Call check_availability first. Nothing is reserved by this call and the work can still sell to someone else until you call confirm_purchase. The price and delivery terms are the seller’s and are looked up here; anything you send is ignored. The returned total does NOT include tax until you call set_delivery. The purchase belongs to the credential that starts it, on this endpoint: no other credential can read, change, cancel or complete it, and is told it does not exist. Without an agent credential, this answers with a checkout_url instead: a page for this one work on which the buyer pays — hand it to the buyer or open it in your browser; the other purchase tools are for credentialed agents.

Argument	Type	Description
buyer_name	string
listing_id*	string	A single listing_id from get_artwork or check_availability.
buyer_email	string	Optional. The buyer’s order confirmation is sent here.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "listing_id"
  ],
  "properties": {
    "buyer_name": {
      "type": "string",
      "maxLength": 128
    },
    "listing_id": {
      "type": "string",
      "maxLength": 36,
      "minLength": 1,
      "description": "A single listing_id from get_artwork or check_availability."
    },
    "buyer_email": {
      "type": "string",
      "maxLength": 254,
      "description": "Optional. The buyer’s order confirmation is sent here."
    }
  }
}

Fold Laboratories Art Catalogue

Try it

cancel_purchase

Fold Laboratories Art Catalogue

Try it

cancel_purchase

Tools (11)