Shop, invoices and payments

Orders, carts, quotes, proposals, invoices, credit notes, refunds and payment accounts.

Scopes for this area: shop:read, shop:write and shop:admin.

180 operations

location

Method	Route	What it does	Level	Command
POST	/shop/locations	Add a stock location (warehouse, shop, supplier or virtual).	admin	rivier shop location create
GET	/shop/locations	The places stock is kept.	read	rivier shop location list
POST	/shop/locations/{id}/archive	Retire a stock place that holds nothing.	admin	rivier shop location archive

stock

Method	Route	What it does	Level	Command
GET	/shop/stock	Stock of every variant of a product at every place: on hand, held, promised, safety stock, what can still be sold.	read	rivier shop stock list
POST	/shop/stock	Receive stock (positive) or correct it (negative), idempotent on the key.	admin	rivier shop stock adjust

product

Method	Route	What it does	Level	Command
GET	/shop/products	The owner's product list in any state (draft, active, archived or all), with variants, prices and stock.	read	rivier shop product list
PUT	/shop/products/{id}/status	Put a product in draft (off the shop), active (on sale) or archived.	admin	rivier shop product set status

view

Method	Route	What it does	Level	Command
GET	/shop/views	Saved views of a list (search, filters, sort): the caller's own and the project's shared ones.	read	rivier shop view list
POST	/shop/views	Keep the current search, filters and sort of a list under a name, for oneself or shared.	write	rivier shop view save
DELETE	/shop/views/{id}	Delete one of one's own saved views.	write	rivier shop view remove

collection

Method	Route	What it does	Level	Command
GET	/shop/collections	Collections and the products in each.	read	rivier shop collection list
DELETE	/shop/collections/{id}/items/{productId}	Take a product out of a manual collection.	admin	rivier shop collection remove item
POST	/shop/collections	Add a collection.	admin	rivier shop collection create
POST	/shop/collections/{id}/items	Add products to a collection.	admin	rivier shop collection add items
GET	/shop/collection-search	Collections by name or slug.	read	rivier shop collection search
POST	/shop/collection-archive/{id}	Retire a collection; its products stay.	write	rivier shop collection archive

catalogue

Method	Route	What it does	Level	Command
GET	/shop/export.csv	The catalogue as a spreadsheet: one row per variant, with prices, stock, collections, search text and the addresses of published pictures.	read	rivier shop catalogue export
POST	/shop/import	Add and change products from a spreadsheet (same columns as the export). Dry run by default: says what would be created or changed. Pictures are fetched from https addresses by the safe reader.	admin	rivier shop catalogue import

variant

Method	Route	What it does	Level	Command
POST	/shop/variants	Add a variant (SKU, options, weight, tax class, cost and price floor) to a product.	admin	rivier shop variant create
GET	/shop/variants	The variants of a product.	read	rivier shop variant list
GET	/shop/variants/{id}	One variant with its SKU, options, weight, tax class, cost and price floor.	read	rivier shop variant get
PATCH	/shop/variants/{id}	Change a variant's SKU, options, weight, tax class, cost or price floor.	admin	rivier shop variant update
POST	/shop/variants/{id}/archive	Retire a variant. Refused while it is in a cart, an unshipped order or a bundle.	admin	rivier shop variant archive

price

Method	Route	What it does	Level	Command
POST	/shop/prices	Set a price. It goes into the price history; it may not go under the floor, and a previous price must be the lowest of the last 30 days.	admin	rivier shop price set
GET	/shop/prices	Live prices of a variant (all, with `all`).	read	rivier shop price list
GET	/shop/price-history	Every price a variant has been sold at, newest first.	read	rivier shop price history
POST	/shop/prices/{id}/end	End a live price.	admin	rivier shop price end

stock rule

Method	Route	What it does	Level	Command
PUT	/shop/stock-rules	Safety stock and backorder for a variant at a location.	admin	rivier shop stock rule set

bundle

Method	Route	What it does	Level	Command
PUT	/shop/bundles	Make a variant a bundle of other variants.	admin	rivier shop bundle set
GET	/shop/bundles/{id}	The parts of a bundle variant.	read	rivier shop bundle get
DELETE	/shop/bundles/{id}	Stop selling a variant as a bundle.	admin	rivier shop bundle remove

zone

Method	Route	What it does	Level	Command
POST	/shop/zones	Add a shipping zone (a set of countries).	admin	rivier shop zone create
GET	/shop/zones	Shipping zones with their countries and rates.	read	rivier shop zone list
PATCH	/shop/zones/{id}	Change a zone's name or countries, or archive it.	admin	rivier shop zone update

rate

Method	Route	What it does	Level	Command
POST	/shop/rates	Add a shipping rate to a zone (by weight, free over a total).	admin	rivier shop rate create
PATCH	/shop/rates/{id}	Change a shipping rate, or archive it.	admin	rivier shop rate update

tax rule

Method	Route	What it does	Level	Command
POST	/shop/tax-rules	Add a tax rule with its source and the date it was checked.	admin	rivier shop tax rule create
GET	/shop/tax-rules	Tax rules with their dates, source and when they were last checked.	read	rivier shop tax rule list
PATCH	/shop/tax-rules/{id}	Change a tax rule's rate, dates or source.	admin	rivier shop tax rule update

discount

Method	Route	What it does	Level	Command
POST	/shop/discounts	Add a discount: a code or automatic, percent, fixed or free shipping, with limits.	admin	rivier shop discount create
PUT	/shop/discounts/{id}/status	Pause, resume or archive a discount.	admin	rivier shop discount set status
GET	/shop/discounts	Discounts with their rule, limits, status and use.	read	rivier shop discount list
GET	/shop/discounts/{id}	One discount.	read	rivier shop discount get

catalog

Method	Route	What it does	Level	Command
GET	/shop/catalog	What is for sale: products with variants, the price for a currency and country, and what is in stock.	read	rivier shop catalog list

availability

Method	Route	What it does	Level	Command
GET	/shop/availability/{id}	How many of a variant can still be promised (a bundle: the smallest over its parts).	read	rivier shop availability get

completeness

Method	Route	What it does	Level	Command
GET	/shop/completeness	How complete a product is for a channel (storefront, google, openai, meta): the share of what the channel requires that it has, and what is missing.	read	rivier shop completeness get

feed

Method	Route	What it does	Level	Command
GET	/shop/feeds/{channel}	The product feed a channel reads (google, openai, meta) as JSON or tab-separated text: one row per variant for every product that has what the channel requires, and the products left out with what each lacks.	read	rivier shop feed get

order

Method	Route	What it does	Level	Command
GET	/shop/orders	Orders by state or customer.	read	rivier shop order list
GET	/shop/orders/{id}	One order with its lines, money and the terms it was sold under.	read	rivier shop order get
GET	/shop/orders/{id}/timeline	What happened to an order, in order.	read	rivier shop order timeline
POST	/shop/orders	Place an order from a cart. Prices, tax and shipping are worked out again; the stock is committed; idempotent on the key.	write	rivier shop order place
POST	/shop/orders/{id}/pay	A hosted checkout address for what is due on an order.	write	rivier shop order pay
POST	/shop/orders/{id}/cancel	Cancel an order nobody has paid for and give its stock back.	write	rivier shop order cancel
POST	/shop/orders/{id}/ship	Ship whole lines of a paid order with a carrier and tracking.	write	rivier shop order ship
POST	/shop/orders/{id}/complete	Close a delivered order.	write	rivier shop order complete
POST	/shop/orders/{id}/refund	Ask for a refund of part or all of what an order paid. A person approves it on the payments side before any money moves.	write	rivier shop order refund
POST	/shop/orders/{id}/cancel-paid	Cancel a paid order that has not shipped and ask for its refund. A person's decision.	write	rivier shop order cancel paid
POST	/shop/orders/{id}/invoice	Make the invoice for a paid order again (it is made on payment; this retries a failure). Idempotent per order.	write	rivier shop order invoice
POST	/shop/orders/sync	Bring in orders placed on the connected shops and marketplaces since a time (default: since the last order brought in). Each source order is imported once.	write	rivier shop order sync
PATCH	/shop/orders/{id}	Correct the contact or delivery address of an order that has not shipped.	write	rivier shop order update
GET	/shop/orders/{id}/payments	The payment history of an order: checkout, paid, refund asked, refunded.	read	rivier shop order payments

cart

Method	Route	What it does	Level	Command
POST	/shop/carts	Start a cart in a currency and country.	write	rivier shop cart create
GET	/shop/carts/{id}	A cart priced as it stands: lines, discounts, shipping options, tax and total.	read	rivier shop cart get
PATCH	/shop/carts/{id}	Set the cart's country and discount codes.	write	rivier shop cart update
POST	/shop/carts/{id}/lines	Add a variant to the cart. The stock is held for the buyer.	write	rivier shop cart add line
PUT	/shop/carts/{id}/lines/{variantId}	Change a line's quantity; zero removes it.	write	rivier shop cart set line

shipment

Method	Route	What it does	Level	Command
POST	/shop/shipments/{id}/deliver	Mark a shipment delivered.	write	rivier shop shipment deliver
GET	/shop/shipments	Shipments for an order or in a state.	read	rivier shop shipment list
GET	/shop/shipments/{id}	One shipment.	read	rivier shop shipment get
PATCH	/shop/shipments/{id}	Correct a shipment's carrier or tracking number.	write	rivier shop shipment update

return

Method	Route	What it does	Level	Command
POST	/shop/orders/{id}/returns	Ask to send shipped lines back. Only units that shipped and are not already returned or waiting can be asked for.	write	rivier shop return request
GET	/shop/returns	Returns by state or order.	read	rivier shop return list
POST	/shop/returns/{id}/decision	Accept or reject a return request.	write	rivier shop return decide
POST	/shop/returns/{id}/receive	Record that the goods came back; units go back on the shelf when the request said so.	write	rivier shop return receive
POST	/shop/returns/{id}/refund	Ask for the refund of an accepted return. A person approves it on the payments side before any money moves.	write	rivier shop return refund

refunds due

Method	Route	What it does	Level	Command
GET	/shop/refunds-due	Cancelled orders that hold money nobody has asked to give back.	read	rivier shop refunds due list

public catalog

Method	Route	What it does	Level	Command
GET	/public/shop/catalog	The storefront catalogue: prices, options and whether each variant can be bought.	read	rivier shop public catalog list

public cart

Method	Route	What it does	Level	Command
POST	/public/shop/carts	Start a cart.	read	rivier shop public cart create
GET	/public/shop/carts/{id}	A cart priced as it stands.	read	rivier shop public cart get
PATCH	/public/shop/carts/{id}	Set the cart's country and discount codes.	read	rivier shop public cart update
POST	/public/shop/carts/{id}/lines	Add a variant to the cart.	read	rivier shop public cart add line
PUT	/public/shop/carts/{id}/lines/{variantId}	Change a line's quantity; zero removes it.	read	rivier shop public cart set line

public checkout

Method	Route	What it does	Level	Command
POST	/public/shop/checkout	Place the order and, unless told not to, start the payment; answers with the order, its link and the payment address.	read	rivier shop public checkout place

public order

Method	Route	What it does	Level	Command
GET	/public/shop/orders/{id}/downloads	The files a buyer is owed, as short-lived addresses, once the order is paid.	read	rivier shop public order downloads
GET	/public/shop/orders/{id}	An order, through its own link.	read	rivier shop public order get
POST	/public/shop/orders/{id}/pay	A fresh payment address for an unpaid order.	read	rivier shop public order pay
POST	/public/shop/orders/{id}/returns	Ask to return shipped lines, through the order's link.	read	rivier shop public order return
POST	/public/shop/orders/{id}/cancel	Cancel an unpaid order through its link.	read	rivier shop public order cancel

supplier

Method	Route	What it does	Level	Command
GET	/shop/suppliers	Suppliers.	read	rivier shop supplier list
GET	/shop/suppliers/{id}	One supplier.	read	rivier shop supplier get
POST	/shop/suppliers	Add a supplier.	write	rivier shop supplier create
DELETE	/shop/suppliers/{id}	Stop buying from a supplier (an approver's decision).	write	rivier shop supplier archive

supplied

Method	Route	What it does	Level	Command
GET	/shop/supplied	Which variants each supplier sells and at what cost.	read	rivier shop supplied list
POST	/shop/supplied	Say that a supplier sells a variant, at a unit cost.	write	rivier shop supplied create

margin

Method	Route	What it does	Level	Command
GET	/shop/margin	Margin of a variant's price against the cheapest supplier cost.	read	rivier shop margin get

purchase order

Method	Route	What it does	Level	Command
GET	/shop/purchase-orders	Purchase orders by status.	read	rivier shop purchase order list
GET	/shop/purchase-orders/{id}	One purchase order.	read	rivier shop purchase order get
POST	/shop/purchase-orders	Draft a purchase order.	write	rivier shop purchase order create
POST	/shop/purchase-orders/{id}/approve	Approve a draft purchase order (a person; an agent never approves its own).	write	rivier shop purchase order approve
POST	/shop/purchase-orders/{id}/send	Send an approved purchase order; test mode only until live sending is opened.	write	rivier shop purchase order send
POST	/shop/purchase-orders/{id}/receive	Goods arrived: mark received and put the quantities on the shelf.	write	rivier shop purchase order receive
POST	/shop/purchase-orders/{id}/cancel	Cancel a purchase order that has not been received.	write	rivier shop purchase order cancel

reorder

Method	Route	What it does	Level	Command
POST	/shop/reorders/draft	Draft purchase orders for the variants whose stock is at or below its reorder point.	write	rivier shop reorder draft

payment account

Method	Route	What it does	Level	Command
GET	/payments/accounts	The payment accounts of the project with their state in plain words.	read	rivier shop payment account list
POST	/payments/accounts	Connect a payment account (the business's own Stripe through a connection, or Skerry).	admin	rivier shop payment account connect
POST	/payments/accounts/{id}/refresh	Ask the provider where onboarding stands.	admin	rivier shop payment account refresh
PUT	/payments/accounts/{id}/default	Make an account the default for its mode.	admin	rivier shop payment account set default
POST	/payments/accounts/{id}/approve-live	Approve live money on a verified account.	admin	rivier shop payment account approve live
POST	/payments/accounts/{id}/revoke-live	Take live approval away.	admin	rivier shop payment account revoke live

money policy

Method	Route	What it does	Level	Command
GET	/payments/policy	The money limits: the largest refund in one action and in a day, and the payment links an agent may make.	read	rivier shop money policy get
PUT	/payments/policy	Set the money limits.	admin	rivier shop money policy set

payment

Method	Route	What it does	Level	Command
GET	/payments/payments	Payments by reference (an order, a booking), status or page.	read	rivier shop payment list
GET	/payments/payments/{id}	One payment with its status, what was received and refunded, and the fee.	read	rivier shop payment get

refund

Method	Route	What it does	Level	Command
GET	/payments/refunds	Refunds by state or payment.	read	rivier shop refund list
POST	/payments/refunds	Ask for a refund. It waits for a person's approval; the limits of the money policy apply.	write	rivier shop refund request
POST	/payments/refunds/{id}/approve	Approve a refund; it is sent to the provider once.	write	rivier shop refund approve
POST	/payments/refunds/{id}/reject	Reject a refund request.	write	rivier shop refund reject

mismatch

Method	Route	What it does	Level	Command
GET	/payments/mismatches	Differences found between the books and the provider.	read	rivier shop mismatch list
POST	/payments/mismatches/{id}/resolve	Close a difference with a note, or dismiss it.	write	rivier shop mismatch resolve

reconcile

Method	Route	What it does	Level	Command
POST	/payments/reconcile	Compare the last days of payments with the provider and record differences. Nothing is corrected automatically.	write	rivier shop reconcile run

invoice settings

Method	Route	What it does	Level	Command
GET	/invoices/settings	The seller's details, default VAT and payment terms printed on invoices.	read	rivier shop invoice settings get
PUT	/invoices/settings	Set the seller's details, default VAT, payment days and footer.	admin	rivier shop invoice settings set

invoice series

Method	Route	What it does	Level	Command
GET	/invoices/series	The number series for invoices and credit notes.	read	rivier shop invoice series list
POST	/invoices/series	Add a number series (gapless, optionally restarting each year).	admin	rivier shop invoice series create

invoice

Method	Route	What it does	Level	Command
GET	/invoices	Invoices by status, what they are for (an order, a stay) or a search.	read	rivier shop invoice list
GET	/invoices/{id}	One invoice with its lines, tax groups, payments and what is due.	read	rivier shop invoice get
PATCH	/invoices/{id}	Change a draft invoice: dates, notes, payment terms, references, the customer and where the goods were delivered.	write	rivier shop invoice update
GET	/invoices/{id}/events	What happened to an invoice, in order.	read	rivier shop invoice events
GET	/invoices/{id}/pdf	The invoice as a PDF.	read	rivier shop invoice pdf
POST	/invoices	Draft an invoice; idempotent on the key. It has no number until it is finalised.	write	rivier shop invoice draft
POST	/invoices/{id}/finalise	Number and freeze an invoice. A numbered invoice can only be corrected by a credit note.	write	rivier shop invoice finalise
POST	/invoices/{id}/send	Email the invoice with its PDF to the customer.	write	rivier shop invoice send
POST	/invoices/{id}/payments	Record a payment received against an invoice (a bank transfer, cash); idempotent on the key. Marking an invoice paid is a person's decision.	write	rivier shop invoice record payment
POST	/invoices/{id}/void	Void an invoice nobody has paid.	write	rivier shop invoice void
POST	/invoices/{id}/link	A fresh private link to an invoice, where the client reads it and sees how to pay; the address is shown once.	write	rivier invoices link
GET	/invoices/{id}/links	The private links of an invoice: expiry, views, whether revoked.	read	rivier invoices links
POST	/invoices/{id}/links/{linkId}/revoke	Switch one link of an invoice off.	write	rivier invoices links revoke
POST	/invoices/{id}/links/{linkId}/regenerate	Replace a link of an invoice with a new one; the old address stops working.	write	rivier invoices links regenerate
POST	/invoices/{id}/send-link/preview	The mail that sending the invoice with its private link would produce, the PDF size and the checks that would stop it; nothing is sent.	write	rivier invoices send-link preview
POST	/invoices/{id}/send-link	Send the invoice to the client by mail with its PDF and a private link (or, with channel link, return the link without mail). Beside the plain send, which stays.	write	rivier invoices send-link
PUT	/invoices/{id}/client	Set which client of the organisation an invoice is for (null clears it) and who receives it; without recipients they come from the client's primary and default-copied contacts.	write	rivier invoices client
GET	/invoices/{id}/receipts	The bank-transfer receipts the client uploaded at the invoice link: file name, size, the amount and note they gave, and whether a payment was recorded after it.	read	rivier invoices receipts
GET	/invoices/{id}/receipts/{receiptId}/download	One uploaded receipt file (editor and above).	read	rivier invoices receipts download
GET	/invoices/{id}/doc-events	When an invoice was sent, opened by the client and reported paid by them.	read	rivier invoices doc-events

credit note

Method	Route	What it does	Level	Command
POST	/invoices/{id}/credit-notes	Ask for a credit note against a numbered invoice (the whole invoice or chosen lines). A person issues it.	write	rivier shop credit note request
GET	/invoices/credit-notes	Credit notes, optionally for one invoice.	read	rivier shop credit note list
POST	/credit-notes/{id}/issue	Issue a credit note: it is numbered and reduces what the invoice is owed.	write	rivier shop credit note issue
POST	/credit-notes/{id}/reject	Reject a credit note request.	write	rivier shop credit note reject

quote

Method	Route	What it does	Level	Command
GET	/quotes	Quotes by status, client or a search, newest first.	read	rivier quotes list
GET	/quotes/{id}	One quote with its lines, tax groups, status and the client's answer.	read	rivier quotes get
POST	/quotes	Draft a quote for a client; idempotent on the key (the body's idempotencyKey or the Idempotency-Key header). It has no number until it is sent.	write	rivier quotes create
PATCH	/quotes/{id}	Change a quote; fields left out stay as they are. A sent quote becomes a new revision and goes back to draft.	write	rivier quotes update
GET	/quotes/{id}/events	What happened to a quote, in order.	read	rivier quotes events
GET	/quotes/{id}/certificate	The certificate of completion of an accepted quote as a PDF: who accepted, when, from where, and the fingerprint of what they accepted.	read	rivier quotes certificate
GET	/quotes/{id}/pdf	The quote as a PDF.	read	rivier quotes pdf
POST	/quotes/{id}/preview	The mail that sending the quote would produce, the PDF size and the checks that would stop it; nothing is sent.	write	rivier quotes preview
POST	/quotes/{id}/send	Send the quote to the client by mail with its PDF and private link, or with channel link return the link without mail. The first send numbers it and fixes its content; sending again is a resend.	write	rivier quotes send
POST	/quotes/{id}/link	A fresh private link to a sent quote, to paste into a message; the address is shown once. With replace true the older links stop working.	write	rivier quotes link
GET	/quotes/{id}/links	The private links of a quote: expiry, how often each was opened, whether it was revoked.	read	rivier quotes links
POST	/quotes/{id}/links/{linkId}/revoke	Switch one link of a quote off.	write	rivier quotes links revoke
POST	/quotes/{id}/links/{linkId}/regenerate	Replace a link of a quote with a new one; the old address stops working.	write	rivier quotes links regenerate
POST	/quotes/{id}/duplicate	A new draft copied from a quote, without its number; idempotent on the key.	write	rivier quotes duplicate
POST	/quotes/{id}/convert	Turn an accepted quote into an invoice, or with depositPercent a deposit invoice and a balance invoice (both drafts). The quote becomes converted.	write	rivier quotes convert
POST	/quotes/{id}/void	Void a quote with the reason; it stays on record and its links stop working.	write	rivier quotes void

proposal

Method	Route	What it does	Level	Command
GET	/proposals	Proposals by status, client or a search, newest first.	read	rivier proposals list
GET	/proposals/{id}	One proposal with its lines, tax groups, sections, status and the client's answer.	read	rivier proposals get
POST	/proposals	Draft a proposal for a client; idempotent on the key (the body's idempotencyKey or the Idempotency-Key header). It has no number until it is sent.	write	rivier proposals create
PATCH	/proposals/{id}	Change a proposal; fields left out stay as they are. A sent proposal becomes a new revision and goes back to draft.	write	rivier proposals update
GET	/proposals/{id}/events	What happened to a proposal, in order.	read	rivier proposals events
GET	/proposals/{id}/certificate	The certificate of completion of an accepted proposal as a PDF: who accepted, when, from where, and the fingerprint of what they accepted.	read	rivier proposals certificate
GET	/proposals/{id}/pdf	The proposal as a PDF.	read	rivier proposals pdf
POST	/proposals/{id}/preview	The mail that sending the proposal would produce, the PDF size and the checks that would stop it; nothing is sent.	write	rivier proposals preview
POST	/proposals/{id}/send	Send the proposal to the client by mail with its PDF and private link, or with channel link return the link without mail. The first send numbers it and fixes its content; sending again is a resend.	write	rivier proposals send
POST	/proposals/{id}/link	A fresh private link to a sent proposal, to paste into a message; the address is shown once. With replace true the older links stop working.	write	rivier proposals link
GET	/proposals/{id}/links	The private links of a proposal: expiry, how often each was opened, whether it was revoked.	read	rivier proposals links
POST	/proposals/{id}/links/{linkId}/revoke	Switch one link of a proposal off.	write	rivier proposals links revoke
POST	/proposals/{id}/links/{linkId}/regenerate	Replace a link of a proposal with a new one; the old address stops working.	write	rivier proposals links regenerate
POST	/proposals/{id}/duplicate	A new draft copied from a proposal, without its number; idempotent on the key.	write	rivier proposals duplicate
POST	/proposals/{id}/convert	Turn an accepted proposal into a quote (the default) or into invoices. The proposal becomes converted.	write	rivier proposals convert
POST	/proposals/{id}/void	Void a proposal with the reason; it stays on record and its links stop working.	write	rivier proposals void