# finpo API reference Base URL: `/api/developer/v1`. Send `Authorization: Bearer `. Money is an integer in the smallest unit of the business’s currency. Lists take `limit`, `starting_after` and `ending_before`. ## Business ### Retrieve the business `GET /business` (tool `retrieve_business`, scope `business:read`) The business the key belongs to: its name, its account number, the currency its money is in, and what kind of business it is. ## Locations ### List locations `GET /locations` (tool `list_locations`, scope `business:read`) The business’s branches: every place it sells from or keeps stock in. Most shops have one. ## Categories ### List categories `GET /categories` (tool `list_categories`, scope `products:read`) The categories products are grouped in, as the shop arranged them. ## Products ### List products `GET /products` (tool `list_products`, scope `products:read`) The shop’s products, newest first. `query` finds products the way the shop’s own counter does: a barcode, a code, or a name, even typed wrong. Parameters: - `limit` (integer): How many to return, 1 to 100. The default is 20. - `starting_after` (string): The id of the last object of the page before: the next page starts after it. - `ending_before` (string): The id of the first object of the page after: the page before ends before it. - `query` (string): A barcode, a SKU, or words of the name. Forgiving of spelling. - `category` (string): Only products in this category. - `active` (boolean): Only products on sale (true) or only those taken off sale (false). ### Retrieve a product `GET /products/{id}` (tool `retrieve_product`, scope `products:read`) One product, with every unit it is sold in and its price. Parameters: - `id` (string, required): The object’s id. ### Create a product `POST /products` (tool `create_product`, scope `products:write`, secret key only) Adds a product, sold one at a time at one price. It is written exactly as a product added in finpo is, with its signed record, and checked against the plan’s limits. For sizes, cartons and fractions, add the product in finpo itself. Parameters: - `name` (string, required): What the product is called at the counter. - `price` (integer, required): The price of one, in the smallest unit of the business’s currency (kobo for naira). - `unit_label` (string): What one is called: "Tin", "Pack", "Plate". The default is "Each". - `sku` (string): The shop’s own code for it. One is made up when none is sent. - `barcodes` (array): Barcodes printed on it. - `brand` (string): The maker. - `category` (string): The id of a category. - `kind` (string, one of good | menu | service): A thing on a shelf (the default), a plate on a menu, or a service that holds no stock. - `cost` (integer): What one cost the shop. Only kept when the key has the `costs:read` scope. - `opening_quantity` (integer): How many the shop has now. The default is none. - `location` (string): The location the opening quantity is at. The default is the main one. ## Stock levels ### List stock levels `GET /stock_levels` (tool `list_stock_levels`, scope `stock:read`) How much of each product is at each location, in the product’s own unit, as counted and confirmed. `pending_change` is what staff recorded and the owner has not approved yet. Parameters: - `limit` (integer): How many to return, 1 to 100. The default is 20. - `starting_after` (string): The id of the last object of the page before: the next page starts after it. - `ending_before` (string): The id of the first object of the page after: the page before ends before it. - `product` (string): Only this product. - `location` (string): Only this location. ## Customers ### List customers `GET /customers` (tool `list_customers`, scope `customers:read`, secret key only) The shop’s customers, newest first, with their visits, points and what they owe. `query` finds a name even typed wrong, or a phone number. Parameters: - `limit` (integer): How many to return, 1 to 100. The default is 20. - `starting_after` (string): The id of the last object of the page before: the next page starts after it. - `ending_before` (string): The id of the first object of the page after: the page before ends before it. - `query` (string): A name or a phone number. ### Retrieve a customer `GET /customers/{id}` (tool `retrieve_customer`, scope `customers:read`, secret key only) One customer by id: their name and contacts, how often they come and what they have spent, their points, and what they owe the shop. Parameters: - `id` (string, required): The object’s id. ### Create a customer `POST /customers` (tool `create_customer`, scope `customers:write`, secret key only) Adds a customer. A business keeps one customer per name, so a name already on the list is refused with `resource_conflict`. Parameters: - `name` (string, required): Their name. - `phone` (string): Their phone number, which is how the shop finds them again. - `notes` (string): Anything the shop should know. ## Sales ### List sales `GET /sales` (tool `list_sales`, scope `sales:read`, secret key only) Sales recorded at the counter and on the shop computer, newest first, with their lines and payments. Sales cannot be written through the API: they are signed where they happen, which is what lets finpo check them. Parameters: - `limit` (integer): How many to return, 1 to 100. The default is 20. - `starting_after` (string): The id of the last object of the page before: the next page starts after it. - `ending_before` (string): The id of the first object of the page after: the page before ends before it. - `day_from` (string): The first business day, as YYYY-MM-DD. - `day_to` (string): The last business day, as YYYY-MM-DD. - `location` (string): Only sales at this location. ### Retrieve a sale `GET /sales/{id}` (tool `retrieve_sale`, scope `sales:read`, secret key only) One sale, and whether it was cancelled or refunded since. Parameters: - `id` (string, required): The object’s id. ## Orders ### List orders `GET /orders` (tool `list_orders`, scope `orders:read`, secret key only) Orders the shop has received, from its own staff, its order page, its tables and the API, newest first. Parameters: - `limit` (integer): How many to return, 1 to 100. The default is 20. - `starting_after` (string): The id of the last object of the page before: the next page starts after it. - `ending_before` (string): The id of the first object of the page after: the page before ends before it. - `status` (string, one of new | confirmed | preparing | ready | out_for_delivery | completed | cancelled): Only orders in this state. ### Retrieve an order `GET /orders/{id}` (tool `retrieve_order`, scope `orders:read`, secret key only) One order, with its lines and where it is now. Parameters: - `id` (string, required): The object’s id. ### Create an order `POST /orders` (tool `create_order`, scope `orders:write`) Sends an order to the shop, the way a customer’s order from its order page arrives: staff see it on the Orders board, prepare it, and take the money at the counter, where it becomes a signed sale. Prices are always the shop’s own: the order is priced by finpo from the products and units sent. Safe with a publishable key, from a shop’s own website or app. Parameters: - `customer_name` (string, required): Who the order is for. - `customer_phone` (string, required): A number the shop can call. - `fulfilment` (string, one of pickup | delivery): Collected at the shop (the default) or delivered. - `delivery_address` (string): Where to deliver it. Needed for a delivery. - `lines` (array, required): What is being ordered. - `product` (string, required): The product’s id. - `unit` (string): The key of the unit it is sold in. The default is its first unit. - `quantity` (integer, required): How many. - `note` (string): Anything the shop should know. - `location` (string): The location to send it to. The default is the main one. ## Webhook endpoints ### List webhook endpoints `GET /webhook_endpoints` (tool `list_webhook_endpoints`, scope `webhooks:write`, secret key only) The addresses finpo sends events to. The signing secret is shown only when an endpoint is created. ### Create a webhook endpoint `POST /webhook_endpoints` (tool `create_webhook_endpoint`, scope `webhooks:write`, secret key only) Starts sending the chosen events to an address. The answer carries the signing secret, once: keep it, and check every delivery’s `Finpo-Signature` header with it (see Webhooks). Parameters: - `url` (string, required): An https address of yours. - `enabled_events` (array, required): Which events to send: sale.recorded, stock.changed, item.upserted, customer.upserted, order.created. ### Delete a webhook endpoint `DELETE /webhook_endpoints/{id}` (tool `delete_webhook_endpoint`, scope `webhooks:write`, secret key only) Stops sending events to that address. Parameters: - `id` (string, required): The object’s id.