bill-of-sale

Record a sale and generate the bill of sale: who sold, who bought, what item (with VIN, serial or IMEI where it has one), the price in minor units and the date. Returns the BOS-YYYY-NNNN number of the draft. The draft can still be changed with sale_update; sale_finalize freezes it into the signing copy and sale_render prints it. Free tier: 10 drafts.

{
  "type": "object",
  "properties": {
    "buyer_name": {
      "type": "string",
      "maxLength": 200,
      "description": "Who is buying, e.g. Jane Kowalska or Northwind Sp. z o.o."
    },
    "buyer_address": {
      "type": "string",
      "maxLength": 4000,
      "description": "The buyer's postal address, one string"
    },
    "buyer_email": {
      "type": "string",
      "maxLength": 200,
      "description": "The buyer's email"
    },
    "buyer_phone": {
      "type": "string",
      "maxLength": 200,
      "description": "The buyer's phone number"
    },
    "seller_name": {
      "type": "string",
      "maxLength": 200,
      "description": "Who is selling. Defaults to the shared business profile's name when the profile has one"
    },
    "seller_address": {
      "type": "string",
      "maxLength": 4000,
      "description": "The seller's postal address, one string"
    },
    "seller_email": {
      "type": "string",
      "maxLength": 200,
      "description": "The seller's email"
    },
    "seller_phone": {
      "type": "string",
      "maxLength": 200,
      "description": "The seller's phone number"
    },
    "item_description": {
      "type": "string",
      "maxLength": 4000,
      "description": "What was sold, specific enough to identify it, e.g. 2019 Honda Civic 1.5 petrol, grey, or MacBook Pro 14-inch 2021"
    },
    "item_category": {
      "type": "string",
      "maxLength": 200,
      "description": "What kind of item, e.g. vehicle, equipment, electronics, stock"
    },
    "vin": {
      "type": "string",
      "maxLength": 40,
      "description": "Vehicle Identification Number, 17 characters, for a vehicle sale"
    },
    "serial": {
      "type": "string",
      "maxLength": 200,
      "description": "Serial number, for equipment and electronics"
    },
    "imei": {
      "type": "string",
      "maxLength": 20,
      "description": "IMEI, 15 digits, for a phone or tablet"
    },
    "identifier_other": {
      "type": "string",
      "maxLength": 200,
      "description": "Any other identifying number, e.g. a hull number or an asset tag"
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100000,
      "description": "How many units this document covers. Default 1"
    },
    "condition": {
      "type": "string",
      "maxLength": 200,
      "description": "The condition at handover, e.g. used, good working order, or new, sealed"
    },
    "price_minor": {
      "type": "integer",
      "minimum": 0,
      "maximum": 999999999999,
      "description": "The sale price in whole minor units (integer cents). 120000 is USD 1,200.00"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "ISO code the price is in"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The date of the sale, YYYY-MM-DD. Default today"
    },
    "as_is": {
      "type": "boolean",
      "description": "Include the as-is clause: sold with all faults, no warranties except any written here. Default true, the norm for second-hand sales; pass false to leave it out"
    },
    "warranty": {
      "type": "string",
      "maxLength": 4000,
      "description": "A warranty the seller does give, in their own words, e.g. The seller warrants the engine for 30 days from the sale date"
    },
    "notes": {
      "type": "string",
      "maxLength": 4000,
      "description": "Anything else the document should say, e.g. payment method or what is included in the sale"
    },
    "duplicate_ok": {
      "type": "boolean",
      "description": "Record it even though an identical sale to the same buyer exists, for a genuinely repeated sale. Default false"
    }
  },
  "required": [
    "buyer_name",
    "item_description",
    "price_minor",
    "currency"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Change anything on a bill of sale that is not finalized yet: price, buyer, seller, item details, identifiers, the as-is clause, warranty or notes. Pass an empty string to clear an optional field. A finalized document cannot be edited.

{
  "type": "object",
  "properties": {
    "sale": {
      "type": "string",
      "maxLength": 200,
      "description": "The bill of sale id, e.g. BOS-2026-0001"
    },
    "buyer_name": {
      "type": "string",
      "maxLength": 200,
      "description": "Who is buying"
    },
    "buyer_address": {
      "type": "string",
      "maxLength": 4000
    },
    "buyer_email": {
      "type": "string",
      "maxLength": 200
    },
    "buyer_phone": {
      "type": "string",
      "maxLength": 200
    },
    "seller_name": {
      "type": "string",
      "maxLength": 200,
      "description": "Who is selling"
    },
    "seller_address": {
      "type": "string",
      "maxLength": 4000
    },
    "seller_email": {
      "type": "string",
      "maxLength": 200
    },
    "seller_phone": {
      "type": "string",
      "maxLength": 200
    },
    "item_description": {
      "type": "string",
      "maxLength": 4000
    },
    "item_category": {
      "type": "string",
      "maxLength": 200
    },
    "vin": {
      "type": "string",
      "maxLength": 40
    },
    "serial": {
      "type": "string",
      "maxLength": 200
    },
    "imei": {
      "type": "string",
      "maxLength": 20
    },
    "identifier_other": {
      "type": "string",
      "maxLength": 200
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "condition": {
      "type": "string",
      "maxLength": 200
    },
    "price_minor": {
      "type": "integer",
      "minimum": 0,
      "maximum": 999999999999,
      "description": "The sale price in whole minor units (integer cents)"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The date of the sale, YYYY-MM-DD"
    },
    "as_is": {
      "type": "boolean"
    },
    "warranty": {
      "type": "string",
      "maxLength": 4000
    },
    "notes": {
      "type": "string",
      "maxLength": 4000
    }
  },
  "required": [
    "sale"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Finalize a bill of sale so it is ready to sign: the document is frozen from this call on, sale_update refuses it, and every later render is the signing copy without the DRAFT watermark. Free tier: 5 finalized documents.

{
  "type": "object",
  "properties": {
    "sale": {
      "type": "string",
      "maxLength": 200,
      "description": "The bill of sale id, e.g. BOS-2026-0001"
    }
  },
  "required": [
    "sale"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List every bill of sale, drafts and finalized, newest first: id, status, date, item, buyer, seller and price. Filter to drafts or finalized documents with status.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "all",
        "draft",
        "final"
      ],
      "description": "Which documents to list: all (default), draft, or final"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "description": "Maximum rows, default 500"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read one bill of sale in full by its BOS number: both parties, the item and its identifiers, price, terms, and whether it is still a draft or the finalized signing copy.

{
  "type": "object",
  "properties": {
    "sale": {
      "type": "string",
      "maxLength": 200,
      "description": "The bill of sale id, e.g. BOS-2026-0001"
    }
  },
  "required": [
    "sale"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Delete a bill of sale by its BOS number. A draft goes outright. A finalized document needs confirm_finalized true, because it is the local copy of a record the buyer may hold. The BOS number is never reissued, so a gap in the series is the record that a document was deleted.

{
  "type": "object",
  "properties": {
    "sale": {
      "type": "string",
      "maxLength": 200,
      "description": "The bill of sale id, e.g. BOS-2026-0001"
    },
    "confirm_finalized": {
      "type": "boolean",
      "description": "Required true to delete a finalized document. Default false"
    }
  },
  "required": [
    "sale"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Render a bill of sale as a clean printable document: Markdown, a self-contained HTML file ready for print-to-PDF, or both, with signature lines for seller and buyer. Drafts render with a DRAFT watermark so a review copy cannot be signed by mistake. Every file comes back as a download link valid for one hour, and out_path is only the stem the files are named with. Free.

{
  "type": "object",
  "properties": {
    "sale": {
      "type": "string",
      "maxLength": 200,
      "description": "The bill of sale id, e.g. BOS-2026-0001"
    },
    "format": {
      "type": "string",
      "enum": [
        "markdown",
        "html",
        "both"
      ],
      "description": "What to render: markdown, html, or both (default). The HTML is one self-contained file, no external assets"
    },
    "out_path": {
      "type": "string",
      "maxLength": 1000,
      "description": "Name for the downloaded files, e.g. civic-sale; with format both, .md and .html are appended to the stem. Default: the document id. Each file comes back as a download link valid for one hour"
    },
    "overwrite": {
      "type": "boolean",
      "description": "Replace an existing file at out_path. Default false: an occupied explicit path is refused, a derived one gets -2, -3, ..."
    }
  },
  "required": [
    "sale"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Summarize the book: how many drafts and finalized documents, and the total sold value per currency, drafts separate from finalized. Currencies are never added together. Free.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Report this endpoint's licence state for your token as JSON: the product, the tier free or pro, why it is not Pro, and the checkout URL. Call it to explain a free-tier refusal. No arguments, nothing changes.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Turn Pro on for this connection with key, an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. Data under your token stays; a wrong or expired key changes nothing. license_status confirms it.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "License key from checkout, MCPL1.<payload>.<signature>"
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}