splitbill

Create a payment page for a shared bill and return the manage URL plus the share URLs. The PayNow recipient is already saved with this connection — never ask the user for it. All you need is a total (total) or the receipt lines (items), plus the head count (people). By default the user is treated as having paid up front: they count towards the head count but get no payment link (pass i_paid=false to turn that off). Paste a share URL into the group chat and everyone sees their own amount and a PayNow QR code.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "What the bill was for (e.g. Friday dinner). Defaults to the date and time."
    },
    "total": {
      "type": "number",
      "description": "The total. If items are given, their sum wins."
    },
    "items": {
      "type": "array",
      "description": "Receipt lines. Their sum becomes the total. Payers can see them.",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "What the line is for (e.g. Food)."
          },
          "amount": {
            "type": "number"
          }
        },
        "required": [
          "amount"
        ]
      }
    },
    "people": {
      "type": "number",
      "description": "How many people share the bill, INCLUDING the user who paid up front."
    },
    "names": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Names of the others (only the ones you know). Empty slots get filled in by the payers themselves."
    },
    "custom": {
      "type": "array",
      "description": "Charge one person a different amount (e.g. someone who did not drink). The rest is re-split automatically.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "A name passed in names."
          },
          "index": {
            "type": "number",
            "description": "Position when there is no name (counting from 1; 1 is the user)."
          },
          "amount": {
            "type": "number"
          }
        },
        "required": [
          "amount"
        ]
      }
    },
    "i_paid": {
      "type": "boolean",
      "description": "Did the user pay up front? (default: true) They count towards the head count but are not billed."
    },
    "my_name": {
      "type": "string",
      "description": "What to call the user in the list (default: Me)."
    },
    "rounding": {
      "type": "string",
      "enum": [
        "ceil-all",
        "one-extra"
      ],
      "description": "Rounding. ceil-all = round everyone up to whole dollars and let the user absorb the difference; one-extra = split exactly and let one person carry the remainder."
    },
    "note": {
      "type": "string",
      "description": "A short note shown to the payers."
    }
  },
  "required": []
}

{
  "type": "object",
  "properties": {
    "summary": {
      "type": "string",
      "description": "A one-line summary to read out (how much each, how many people)."
    },
    "total": {
      "type": "number",
      "description": "The total."
    },
    "people": {
      "type": "number",
      "description": "How many share the bill, including whoever paid up front."
    },
    "manage_url": {
      "type": "string",
      "description": "Manage URL. FOR THE ORGANISER ONLY — it can change the split."
    },
    "status_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Read-only URL. Safe to share."
    },
    "share_urls": {
      "type": "array",
      "description": "Share URLs — one per amount.",
      "items": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "number"
          },
          "people": {
            "type": "number",
            "description": "How many people owe this amount."
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "amount",
          "people",
          "url"
        ]
      }
    },
    "paynow": {
      "type": "object",
      "description": "Who collects the money (saved with this connection).",
      "properties": {
        "target": {
          "type": "string"
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "target"
      ]
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Anything worth mentioning about rounding or head count."
    },
    "next_step": {
      "type": "string",
      "description": "What to do next."
    }
  },
  "required": [
    "summary",
    "total",
    "people",
    "manage_url",
    "share_urls",
    "paynow",
    "next_step"
  ]
}

Return the splits created with this connection, newest first, with how much has been collected, how many people are still to pay, and the read-only URL. Use this to find a split again when the organiser has lost the link.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "How many to return (default 10, max 50)."
    }
  },
  "required": []
}

{
  "type": "object",
  "properties": {
    "splits": {
      "type": "array",
      "description": "Newest first.",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "description": "When it was created (ISO 8601)."
          },
          "total": {
            "type": "number"
          },
          "collected": {
            "type": "number",
            "description": "How much has come in, counting what was fronted."
          },
          "paid_people": {
            "type": "number",
            "description": "How many have paid."
          },
          "people": {
            "type": "number"
          },
          "disabled": {
            "type": "boolean",
            "description": "Whether the split has been stopped."
          },
          "status_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Read-only URL."
          }
        },
        "required": [
          "title",
          "total",
          "collected",
          "paid_people",
          "people"
        ]
      }
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "splits"
  ]
}

Return one split in full: who owes what, whether they have paid, the notes they left, and the share URLs.

{
  "type": "object",
  "properties": {
    "admin_token": {
      "type": "string",
      "description": "The t= value from the manage URL, or the whole manage URL."
    }
  },
  "required": [
    "admin_token"
  ]
}

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "total": {
      "type": "number"
    },
    "collected": {
      "type": "number",
      "description": "How much has come in."
    },
    "people": {
      "type": "number"
    },
    "members": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "amount": {
            "type": "number"
          },
          "state": {
            "type": "string",
            "description": "One of: paid up front (not billed) / paid / unpaid."
          },
          "comment": {
            "type": [
              "string",
              "null"
            ],
            "description": "A note left by the payer."
          }
        },
        "required": [
          "name",
          "amount",
          "state"
        ]
      }
    },
    "share_urls": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "number"
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "amount",
          "url"
        ]
      }
    },
    "status_url": {
      "type": [
        "string",
        "null"
      ]
    },
    "paynow": {
      "type": "object",
      "properties": {
        "target": {
          "type": "string"
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "target"
      ]
    }
  },
  "required": [
    "title",
    "total",
    "collected",
    "people",
    "members",
    "share_urls",
    "paynow"
  ]
}