Sherpo merchant API
Rich text fields take HTML in a closed format; anything else is refused as invalid, naming the field's path and the reason, so fix it and retry. Allowed: p, h1 (Title), h2 (Heading), h3 (Subheading), br; marks strong, em, u, s, sup, sub, code (b as strong, i as em, del as s, strike as s); a with href (http, https, mailto, tel, ftp, ftps, callto, sms, cid, xmpp, irc, ircs or a relative path), target="_blank"; span with style color or background-color (#rgb or #rrggbb); style text-align (left, center, right, justify) on p and h1 to h3; ul; ol (start); li (data-checked="true" or "false" for a task list); table, thead, tbody, tr, th, td (colspan, rowspan); pre with one code (class="language-<id>", the id one of bash, c, cpp, csharp, css, go, xml, java, javascript, json, kotlin, markdown, php, python, ruby, rust, sql, swift, typescript, yaml); blockquote; hr; details (open) with its summary first; figure with at most one figcaption, first or last; a link's rel (noopener, noreferrer, nofollow) is read and never stored. Images, videos, audio, slideshows, formulas, diagrams, downloads and other blocks are <block type="…" props="{…JSON…}"></block> elements (no raw img or video); which types a field takes is in its description. getBodySchema answers each block's props, their values and which are required, for every kind of body; a block with an unknown type, an unknown prop or a value outside its set is refused, naming the block and what the prop takes. Refused: any other tag, attribute or style (div, section, img, iframe, script, comments…), a link or a block inside a link, a figure inside a figure. At most 1 MiB of UTF-8 (and each field's own limit), markup nested at most 32 deep, tables covering at most 10000 cells in all (each its rows times its widest row, spans counted). Reads return the stored canonical form, wrapped in <rich-text version="1">; send it back as it is to keep a text. To write Markdown instead, set text_format to "markdown": each text, up to 64 KiB, is converted into the format, raw HTML in it kept, a $$ fence or a paragraph that is one $$ … $$ line a formula block (a fence nothing closes stays text), and a mermaid fence a diagram block (one of a type the store's page doesn't draw, or that the diagram rules refuse, stays code; one that still can't be drawn, or past 10 new diagrams in a save, is refused), and validated the same way; a Markdown image is refused, since an image is a block. Example:
Welcome
Start with the intro, then read the notes.
Watch the intro
Take the quiz
Why it works
Short lessons stick.
store
product
- Lists the product categories the store may use.GET
/v1/stores/{store}/categories - Pages the store's products.GET
/v1/stores/{store}/products - Creates a draft product.POST
/v1/stores/{store}/products - Reads one product with its tiers and prices.GET
/v1/stores/{store}/products/{product} - Deletes a product no order, grant or subscription refers to.DEL
/v1/stores/{store}/products/{product} - Updates a product's fields.PATCH
/v1/stores/{store}/products/{product} - Reads the short summaries of up to a page of products by id, with where each stands.GET
/v1/stores/{store}/products/summaries - Publishes a product now or schedules it.POST
/v1/stores/{store}/products/{product}/publish - Takes a product back to draft.POST
/v1/stores/{store}/products/{product}/unpublish - Stops selling a product while keeping it for its holders.POST
/v1/stores/{store}/products/{product}/discontinue - Sells a discontinued product again.POST
/v1/stores/{store}/products/{product}/reinstate - Hides a product from the store's listings while keeping its page reachable.POST
/v1/stores/{store}/products/{product}/unlist - Shows an unlisted product in the store's listings again.POST
/v1/stores/{store}/products/{product}/relist - Pages the tiers of the store's products, or of one product.GET
/v1/stores/{store}/tiers - Pages the tiers of the store's products, or of one product.GET
/v1/stores/{store}/products/{product}/tiers - Adds a tier to a product, with the settings its category takes, such as the features a software tier's licenses unlock.POST
/v1/stores/{store}/products/{product}/tiers - Deletes a tier no price or holder refers to.DEL
/v1/stores/{store}/products/{product}/tiers/{tier} - Renames a tier or changes its settings, such as the features a software tier's licenses unlock.PATCH
/v1/stores/{store}/products/{product}/tiers/{tier} - Sets the order of a product's tiers.POST
/v1/stores/{store}/products/{product}/tiers/reorder - Lists the tiers that unlock a product, entry, page or file.GET
/v1/stores/{store}/{kind}/{id}/access_requirements - Requires a tier to unlock a resource.PUT
/v1/stores/{store}/{kind}/{id}/access_requirements - Removes a tier requirement from a resource.DEL
/v1/stores/{store}/{kind}/{id}/access_requirements - Reads the access requirements of many resources at once.POST
/v1/stores/{store}/access_requirements/query - Reads a product's sales and audience stats over a period.GET
/v1/stores/{store}/products/{product}/stats - Counts the store's products by status.GET
/v1/stores/{store}/products/stats - Reads a product's views, visitors, checkouts started and orders over a period, by channel.GET
/v1/stores/{store}/products/{product}/traffic/stats - Pages the registration questions a product asks its buyers in checkout, in order.GET
/v1/stores/{store}/products/{product}/questions - Adds a registration question to a product, its own or a standard detail: a text, a select or a checkbox, required or not.POST
/v1/stores/{store}/products/{product}/questions - Stops asking a product question, dropping its answers.DEL
/v1/stores/{store}/products/{product}/questions/{question} - Rewords a product question, makes it required or not, changes its options or pattern, or moves it.PATCH
/v1/stores/{store}/products/{product}/questions/{question} - Pages an event's sessions, earliest first.GET
/v1/stores/{store}/products/{product}/sessions - Adds a session to an event, with its start, end, time zone and place.POST
/v1/stores/{store}/products/{product}/sessions - Takes a session off an event's schedule.DEL
/v1/stores/{store}/products/{product}/sessions/{session} - Moves an event session or changes its place.PATCH
/v1/stores/{store}/products/{product}/sessions/{session} - Reads an event's cancellation and its refunds by status; null while the event stands.GET
/v1/stores/{store}/products/{product}/cancellation - Pages a software product's releases and notes, newest first.GET
/v1/stores/{store}/products/{product}/activity - Records a release, whose files become the current download, or a note on a software product.POST
/v1/stores/{store}/products/{product}/activity - Deletes a release, with its files, or a note.DEL
/v1/stores/{store}/products/{product}/activity/{event} - Updates a release's version, notes, files or tier, or a note.PATCH
/v1/stores/{store}/products/{product}/activity/{event}
price
- Pages the prices of the store's products, or of one product.GET
/v1/stores/{store}/prices - Pages the prices of the store's products, or of one product.GET
/v1/stores/{store}/products/{product}/prices - Adds a price to a product's tier.POST
/v1/stores/{store}/products/{product}/prices - Deletes a price no order or subscription refers to.DEL
/v1/stores/{store}/products/{product}/prices/{price} - Updates a price's fields.PATCH
/v1/stores/{store}/products/{product}/prices/{price} - Makes a price the one a product's page features.POST
/v1/stores/{store}/products/{product}/prices/{price}/highlight - Stops offering a price while keeping it for its buyers.POST
/v1/stores/{store}/products/{product}/prices/{price}/archive - Offers an archived price again.POST
/v1/stores/{store}/products/{product}/prices/{price}/restore - Prices each of a product's prices as the checkout would charge a customer, or a new one, with an optional coupon, quantity and later time, writing nothing; naming a customer needs `customer:read`, and a coupon `discount:read`.GET
/v1/stores/{store}/products/{product}/checkout/simulate
entry
- Pages a product's entries, a blog's drafts first then newest first, a podcast's newest first, unless sorted.GET
/v1/stores/{store}/products/{product}/entries - Creates a draft entry in a product.POST
/v1/stores/{store}/products/{product}/entries - Pages a product's entries, each read whole, a blog's drafts first then newest first, a podcast's newest first, unless sorted.GET
/v1/stores/{store}/products/{product}/entries/details - Reads one entry.GET
/v1/stores/{store}/products/{product}/entries/{entry} - Deletes an entry.DEL
/v1/stores/{store}/products/{product}/entries/{entry} - Updates an entry's fields.PATCH
/v1/stores/{store}/products/{product}/entries/{entry} - Counts a product's entries by status and section.GET
/v1/stores/{store}/products/{product}/entries/stats - Publishes an entry now or schedules it.POST
/v1/stores/{store}/products/{product}/entries/{entry}/publish - Takes an entry back to draft.POST
/v1/stores/{store}/products/{product}/entries/{entry}/unpublish - Sets the order of a product's entries.POST
/v1/stores/{store}/products/{product}/entries/reorder - Pages the distinct sections a product's entries hold, with how many hold each.GET
/v1/stores/{store}/products/{product}/entries/sections - Pages the distinct tags a product's entries hold, with how many hold each.GET
/v1/stores/{store}/products/{product}/entries/tags - Lists a product's entry sections.GET
/v1/stores/{store}/products/{product}/sections - Adds an entry section to a product.POST
/v1/stores/{store}/products/{product}/sections - Renames a product's entry section.POST
/v1/stores/{store}/products/{product}/sections/rename - Removes a product's entry section, its entries kept outside any section.POST
/v1/stores/{store}/products/{product}/sections/remove
custompage
- Pages the store's custom pages.GET
/v1/stores/{store}/pages - Creates a draft custom page.POST
/v1/stores/{store}/pages - Reads one custom page.GET
/v1/stores/{store}/pages/{page} - Deletes a custom page.DEL
/v1/stores/{store}/pages/{page} - Updates a custom page's fields.PATCH
/v1/stores/{store}/pages/{page} - Publishes a custom page now or schedules it.POST
/v1/stores/{store}/pages/{page}/publish - Takes a custom page back to draft.POST
/v1/stores/{store}/pages/{page}/unpublish
file
- Lists the files attached to a resource.GET
/v1/stores/{store}/{kind}/{id}/attachments - Attaches a file to a resource in a role.POST
/v1/stores/{store}/{kind}/{id}/attachments - Answers what a save takes for a kind of body: its block types, each block's props with their types, values and limits, which are required, and where blocks may sit.GET
/v1/stores/{store}/body_schema - Reads what the store's home, a page, a product or an entry renders, its body or the default layout without one, and a quiz's or certificate's body; staged reads the unpublished one, and default the default layout even over a body. `getBodySchema` answers the blocks and props each kind of body takes.GET
/v1/stores/{store}/{kind}/{id}/body - Writes the live body of the store's home, a page, a product or an entry, or with `staged: true` its unpublished next body, which `publishBody` publishes; `from` names the body read, so a write over one changed since is refused. Ask `getBodySchema` for the blocks, props and values its kind takes before writing: anything else is refused, naming the block, the prop and what it takes.PUT
/v1/stores/{store}/{kind}/{id}/body - Updates, inserts, moves or deletes blocks of a body by id, without sending it whole. `getBodySchema` answers the props each block takes.POST
/v1/stores/{store}/{kind}/{id}/body/edit - Publishes the staged body.POST
/v1/stores/{store}/{kind}/{id}/body/publish - Discards the staged body, keeping the published one.POST
/v1/stores/{store}/{kind}/{id}/body/discard - Updates an attachment's role, delivery or preview flag.PATCH
/v1/stores/{store}/attachments/{attachment} - Sets the order of a resource's attachments.POST
/v1/stores/{store}/{kind}/{id}/attachments/reorder - Detaches a file from a resource, keeping the file.POST
/v1/stores/{store}/attachments/{attachment}/detach - Pages a product's MCP prompts with their text.GET
/v1/stores/{store}/products/{product}/prompts - Adds an MCP prompt to a product.POST
/v1/stores/{store}/products/{product}/prompts - Reads one of a product's MCP prompts.GET
/v1/stores/{store}/products/{product}/prompts/{prompt} - Deletes an MCP prompt.DEL
/v1/stores/{store}/products/{product}/prompts/{prompt} - Updates an MCP prompt's fields, text or access.PATCH
/v1/stores/{store}/products/{product}/prompts/{prompt} - Sets, swaps or clears a product's thumbnail, its first poster, if it is still the one the caller saw.PUT
/v1/stores/{store}/products/{product}/poster - Pages the store's files.GET
/v1/stores/{store}/assets - Creates a link file, such as an external video.POST
/v1/stores/{store}/assets - Reads one file.GET
/v1/stores/{store}/assets/{asset} - Deletes a file nothing uses.DEL
/v1/stores/{store}/assets/{asset} - Updates a file's name, title, description and security level.PATCH
/v1/stores/{store}/assets/{asset} - Reads the store's storage use against its plan's allowance, and the time zone its files' deliveries are dated in.GET
/v1/stores/{store}/quota - Lists a video's or audio file's AI outputs (subtitles, transcript, summary, chapters) and where each one's generation stands.GET
/v1/stores/{store}/assets/{asset}/outputs - Reads one of a video's or audio file's AI outputs with its content.GET
/v1/stores/{store}/assets/{asset}/output - Deletes one of a video's or audio file's AI outputs.DEL
/v1/stores/{store}/assets/{asset}/output - Edits one of a video's or audio file's AI outputs: the subtitles' cues, or the transcript's, summary's or chapters' content.PATCH
/v1/stores/{store}/assets/{asset}/output - Generates one of a video's or audio file's AI outputs, or generates it again, landing as a draft; subtitles first, the rest from them.POST
/v1/stores/{store}/assets/{asset}/outputs/generate - Publishes one of a video's or audio file's AI outputs to customers, or takes it back to a draft.POST
/v1/stores/{store}/assets/{asset}/outputs/publish - Reserves a file and answers where to upload its bytes. A file of at most 2 MiB can go in the call instead, through the inline upload.POST
/v1/stores/{store}/uploads - Uploads a file of at most 2 MiB with its bytes in the call, for a client that cannot send them to an upload URL.POST
/v1/stores/{store}/uploads/inline - Marks an upload done once its bytes are in place.POST
/v1/stores/{store}/assets/{asset}/complete - Cancels an upload that was never completed.POST
/v1/stores/{store}/assets/{asset}/cancel - Mints a short-lived URL to a file's bytes.POST
/v1/stores/{store}/assets/{asset}/url - Moves a file between public and private storage.POST
/v1/stores/{store}/assets/{asset}/move - Replaces a file's bytes with another upload's, keeping where it is used and deleting a video's or audio file's AI outputs.POST
/v1/stores/{store}/assets/{asset}/replace - Counts a product's files and links by kind.GET
/v1/stores/{store}/products/{product}/file_stats - Pages the deliveries of files from the last year, newest first, with the file, who it went to and its state, in the store's time zone.GET
/v1/stores/{store}/asset_deliveries - Pages where files are used.GET
/v1/stores/{store}/asset_uses - Answers the bytes of a private file a capability names, to the bearer that asked for it.GET
/v1/stores/{store}/files/{capability}
transaction
- Reads the store's takings and audience stats over a period.GET
/v1/stores/{store}/stats - Reads the store's order totals over a period of any length, against the span before it.GET
/v1/stores/{store}/orders/stats - Reads the store's takings and audience totals since its first order.GET
/v1/stores/{store}/totals - Reads the store's views, visitors, sign-ins and sign-ups over a period, by channel, country and product, with visits by referrer, campaign and device.GET
/v1/stores/{store}/traffic/stats - Reads the store's product views, checkouts started and orders over a period, by channel and product.GET
/v1/stores/{store}/conversion/stats - Reads the calls customers' apps made to the store over the API and MCP over a period, by channel and client.GET
/v1/stores/{store}/calls/stats - Pages the store's orders.GET
/v1/stores/{store}/orders - Records an order paid outside the store, granting what it bought.POST
/v1/stores/{store}/orders - Reads one order.GET
/v1/stores/{store}/orders/{order} - Pages an order's lines.GET
/v1/stores/{store}/orders/{order}/items - Pages an order's settlements.GET
/v1/stores/{store}/orders/{order}/settlements - Pages an order's refunds.GET
/v1/stores/{store}/orders/{order}/refunds - Records a refund of an order, optionally revoking what it granted.POST
/v1/stores/{store}/orders/{order}/refunds - Pages the affiliate commissions an order earned.GET
/v1/stores/{store}/orders/{order}/affiliates - Pages the revocations of customers' access for cause, of one customer or one order when named, with each one's refund.GET
/v1/stores/{store}/revocations - Revokes a customer's access to a purchase's products, or a grant's, for cause: their access ends at once, their subscriptions to them stop, the customer is mailed with an optional message, and an optional refund is sent through Stripe or recorded.POST
/v1/stores/{store}/revocations - Sends a revocation's failed Stripe refund again.POST
/v1/stores/{store}/revocations/{revocation}/refund/retry - Cancels an event: it stops selling, its sessions ahead come off the schedule, and every attendee is told and refunded in full.POST
/v1/stores/{store}/products/{product}/cancel - Pages a canceled event's refunds: what each gives back, where it stands, and why one failed.GET
/v1/stores/{store}/products/{product}/event_refunds - Tries a canceled event's failed refund again.POST
/v1/stores/{store}/event_refunds/{refund}/retry