Atelier

Return a payment link for the person to open in a browser: either a subscription plan, or a single image bought outright (only where price.card_available is true) — or that image's commercial license, with licence=commercial, where price.commercial is not null. The commercial license is sold only this way; Stripe's page asks the person to name the licensee. THE AGENT NEVER HANDLES CARD DETAILS and must not ask for any — hand the url over and let the person pay on the payment page. Nothing is granted until they finish. After a one-off, call fulfil_image with the same listing_id: once the payment has landed it delivers the image at no credit cost, and until then it answers payment_pending. After a subscription, get_account shows it. Every result lists the plans with their prices. Use fulfil_image instead when the buyer already has credits or already owns the image, and start_trial when they have none and have not tried the store. Refused when the buyer already owns the image or already has a subscription, so that nobody pays twice — except an image the free trial bought, which is the screen file only: a one-off for it buys the print file at the full price. Each new link cancels the previous one — any earlier subscription link, or an earlier link for the same image — so give the person only the latest.

Deliver an image to the signed-in buyer, spending the image's price in credits (price.credits in search_images and get_image — often 1, sometimes more) if they do not already own it. Credits buy the personal license only; the commercial license is bought with create_checkout, and this then delivers it. If they DO already own it this is free and always will be — use it freely for re-downloads, and for a fresh download link. The purchased image comes as two links, both as the photographer framed it, uncropped: download_url, 2560px WebP on the long side, which a phone or desktop fits to its own screen as a wallpaper; and print_url, the original file at full resolution (often 10–35 MB), for printing (null when unavailable). Give the person both; they expire at download_expires_at, a day out, and their account page (account_url in get_account) lists every image they own with fresh links. The picture returned inline is a 1200px copy to show them what they got. Pass full_image: true to have the full file inline as well — often 1–3 MB — only if you can accept a result that large and save it yourself. Confirm the price with the person before spending credits. An image bought wholly with free-trial credits is the screen file only: print_url is null, print_included false, and print_offer says what the print costs — the full price again, in paid credits. With the person's agreement, call again with buy_print: true to spend them (or create_checkout kind=one_off to pay by card). After a card checkout for this image it spends nothing: it answers payment_pending until the payment lands, then delivers. Requires sign-in.

The signed-in buyer: their credit balance, subscription status, how many images they already own, and whether a free trial is still available. Call this before proposing a purchase, so you know what they can already afford. Requires sign-in.

Everything known about a single listing: its description, keywords, price in credits and money, the license it sells under, and a preview. Use after search_images when the person wants a closer look at one option.

The full terms an image is sold under: what the buyer may and may not do with it. Read this before recommending a purchase, and whenever the person asks what they are allowed to do with an image. "personal" (the default) is what credits and a card one-off buy; "commercial" is the business licence, sold by card where price.commercial is offered.

The collections available in the store, with how many images are in each. Use for browsing when there is no particular search in mind; prefer search_images when the person has described what they want.

Everything the signed-in buyer has bought, newest first. Re-downloading any of them with fulfil_image costs nothing. Pass include_previews: true whenever the person wants to see their library: small pictures (at most 12 per page) without a fulfil_image per image. Requires sign-in.

Find images for sale by description, mood, colour or subject — a plain description of the feeling or scene works as well as a keyword, so pass what the person actually said. Give target_width and target_height when the image is destined for a specific screen — results are then ranked by how close each frame is to that shape, and frames whose shape is badly wrong for it (a landscape frame for a phone) are left out. Images are sold as the photographer framed them, never cropped. Returns a preview of each image. Use get_image for one listing you already have the id of; use list_collections to browse rather than search.

Give the signed-in buyer 3 credits free, once per email address, ever, and never to an account that has paid here. Offer it when get_account says trial_available, someone wants an image, has no credits and has not tried the store before — AND the trial would buy that image: its price.credits is no more than 3 and price.trial_credits_accepted is true. Otherwise the trial is spent on nothing they wanted. Trial credits buy the screen file only — tell the person, so a print is not expected; the print can be bought afterwards at the full price. Requires sign-in.

Open a PRIVATE collection to the signed-in buyer, using the address and access code its photographer gave them — for example a wedding or client gallery whose pictures are also for sale. Afterwards search_images, get_image and list_collections include it for this buyer, and its images can be bought like any other. Use it only with a code the person gave you; never guess one. Requires sign-in.