DoRoutes API · version 1

Invoices

GET/v1/admin/reports/stats/invoices

Invoiced and received by month

Needs the reports.read permission. Every month from from to to, at most 24. Invoiced is sent invoices less sent credit notes by their date, net and VAT apart; received is payments not removed, by the day they were paid.

Parameters

fromstring (date), in the query, required
tostring (date), in the query, required

Response 200 · object

The months.

monthsarray of InvoiceMonth, required
- monthstring, required
- invoiced_net_penceinteger (int64), required
- invoiced_vat_penceinteger (int64), required
- received_penceinteger (int64), required

Example response 200

{
  "months": [
    {
      "month": "string",
      "invoiced_net_pence": 0,
      "invoiced_vat_pence": 0,
      "received_pence": 0
    }
  ]
}

Response 400 · Error

The request is not valid.

errorobject, required
- codestring, required
  A short machine-readable name, such as not_found.
- messagestring, required
  What went wrong, for people.
request_idstring, required
Matches the X-Request-ID response header.

Example response 400

{
  "error": {
    "code": "string",
    "message": "string"
  },
  "request_id": "string"
}

Response 401 · Error

No tenant key, or no valid session.

Fields as in Invoiced and received by month

Response 403 · Error

The session may not do this.

Fields as in Invoiced and received by month

Response 500 · Error

Something failed on our side.

Fields as in Invoiced and received by month

GET/v1/admin/invoices

Invoices and credit notes

Needs the invoices.read permission. Newest first, without lines or payments. status is draft, sent, part_paid, paid or overdue (sent, owed and past its due date in the business's time zone); from and to are the business's dates on the issue date, or the creation date of a draft.

Parameters

statusstring, in the query
draft, sent, part_paid, paid or overdue
kindstring, in the query
invoice or credit_note
customer_idinteger (int64), in the query
A customer
job_idinteger (int64), in the query
A job
quote_idinteger (int64), in the query
A quote
fromstring, in the query
YYYY-MM-DD
tostring, in the query
YYYY-MM-DD

Response 200 · object

The documents.

invoicesarray of Invoice, required
- idinteger (int64), required
- kindstring, required
  One of: invoice credit_note
- numberstring
  Absent on a draft.
- statusstring, required
  One of: draft sent part_paid paid
- customer_idinteger (int64) or null, required
- customer_namestring, required
  The customer's name now; empty once the customer is removed.
- job_idinteger (int64) or null, required
- quote_idinteger (int64) or null, required
- credits_invoice_idinteger (int64) or null, required
- bill_toobject
  The customer as the document was sent to them.
  - namestring, required
  - emailstring, required
  - addressstring, required
  - vat_numberstring
- issued_onstring (date)
- due_onstring (date)
- currencystring, required
  One of: GBP
- linesarray of InvoiceLine, required
  - idinteger (int64), required
  - descriptionstring, required
  - quantitystring, required
  - unit_penceinteger (int64), required
  - vat_ratestring, required
    One of: standard reduced zero exempt none
  - net_penceinteger (int64), required
- totalsobject, required
  - by_ratearray of object, required
    - ratestring, required
    - net_penceinteger (int64), required
    - vat_penceinteger (int64), required
  - net_penceinteger (int64), required
  - vat_penceinteger (int64), required
  - gross_penceinteger (int64), required
- paid_penceinteger (int64), required
- credited_penceinteger (int64), required
- refunded_penceinteger (int64), required
  On a credit note, what was refunded against it, or is being.
- owed_penceinteger (int64), required
- overdueboolean, required
- notesstring, required
- paymentsarray of InvoicePayment, required
  - idinteger (int64), required
  - invoice_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    One of: bank_transfer card cash cheque other paypal
  - referencestring, required
  - recorded_atstring, required
  - onlineboolean, required
    Paid online through a payment provider (method card, reference naming the provider's payment).
  - card_brandstring
  - card_last4string
  - refunded_penceinteger (int64), required
    What was given back of it online, or is being.
- refundsarray of InvoiceRefund, required
  Refunds of an invoice's payments, or against a credit note.
  - idinteger (int64), required
  - invoice_idinteger (int64), required
    The invoice the payment was recorded on.
  - payment_idinteger (int64), required
  - credit_note_idinteger (int64) or null, required
  - amount_penceinteger (int64), required
  - statusstring, required
    One of: pending succeeded failed
  - externalboolean, required
  - failurestring
  - requested_atstring, required
  - finished_atstring
- refundablearray of InvoiceRefundable, required
  On a sent credit note, the online payments it may still refund.
  - payment_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    card for a Stripe payment, paypal for a PayPal one.
    One of: card paypal
  - card_brandstring
  - card_last4string
- flagsarray of InvoiceFlag, required
  On an invoice, refunds made in the payment provider's dashboard that no credit note matches, and open disputes.
  - kindstring, required
    One of: refund dispute
  - amount_penceinteger (int64), required
  - messagestring, required
- syncInvoiceSync or null
  - idinteger (int64), required
  - statusstring, required
    One of: pending done failed
  - providerstring, required
  - errorstring
  - done_atstring
- created_atstring, required
- sent_atstring
- depositboolean
  A quote's deposit invoice.
- balanceboolean
  A quote's balance invoice, raised by the balance run before the move.

Example response 200

{
  "invoices": [
    {
      "id": 0,
      "kind": "invoice",
      "number": "string",
      "status": "draft",
      "customer_id": 0,
      "customer_name": "string",
      "job_id": 0,
      "quote_id": 0,
      "credits_invoice_id": 0,
      "bill_to": {
        "name": "string",
        "email": "string",
        "address": "string",
        "vat_number": "string"
      },
      "issued_on": "date",
      "due_on": "date",
      "currency": "GBP",
      "lines": [
        {
          "id": 0,
          "description": "string",
          "quantity": "string",
          "unit_pence": 0,
          "vat_rate": "standard",
          "net_pence": 0
        }
      ],
      "totals": {
        "by_rate": [
          {
            "rate": "string",
            "net_pence": 0,
            "vat_pence": 0
          }
        ],
        "net_pence": 0,
        "vat_pence": 0,
        "gross_pence": 0
      },
      "paid_pence": 0,
      "credited_pence": 0,
      "refunded_pence": 0,
      "owed_pence": 0,
      "overdue": true,
      "notes": "string",
      "payments": [
        {
          "id": 0,
          "invoice_id": 0,
          "amount_pence": 0,
          "paid_on": "date",
          "method": "bank_transfer",
          "reference": "string",
          "recorded_at": "string",
          "online": true,
          "card_brand": "string",
          "card_last4": "string",
          "refunded_pence": 0
        }
      ],
      "refunds": [
        {
          "id": 0,
          "invoice_id": 0,
          "payment_id": 0,
          "credit_note_id": 0,
          "amount_pence": 0,
          "status": "pending",
          "external": true,
          "failure": "string",
          "requested_at": "string",
          "finished_at": "string"
        }
      ],
      "refundable": [
        {
          "payment_id": 0,
          "amount_pence": 0,
          "paid_on": "date",
          "method": "card",
          "card_brand": "string",
          "card_last4": "string"
        }
      ],
      "flags": [
        {
          "kind": "refund",
          "amount_pence": 0,
          "message": "string"
        }
      ],
      "sync": {
        "id": 0,
        "status": "pending",
        "provider": "string",
        "error": "string",
        "done_at": "string"
      },
      "created_at": "string",
      "sent_at": "string",
      "deposit": true,
      "balance": true
    }
  ]
}

Response 400 · Error

The request is not valid.

Fields as in Invoiced and received by month

Response 401 · Error

No tenant key, or no valid session.

Fields as in Invoiced and received by month

Response 403 · Error

The session may not do this.

Fields as in Invoiced and received by month

Response 500 · Error

Something failed on our side.

Fields as in Invoiced and received by month

POST/v1/admin/invoices

Raise a draft invoice

Needs the invoices.write permission. For a customer, a job or a quote; a job gives its quote and customer, a quote its customer. Without lines, a job's or a quote's draft takes what is left of the quote's price after the invoices already raised on the quote or its jobs. Each line's VAT rate is none when the business is not VAT registered, and any other rate when it is. Published as invoice.created.

Request body · object

customer_idinteger (int64) or null
job_idinteger (int64) or null
quote_idinteger (int64) or null
linesarray of InvoiceLineInput
- descriptionstring, required
- quantitystring, required
  A decimal above 0, with up to 6 digits and 3 places.
- unit_penceinteger (int64), required
- vat_ratestring, required
  One of: standard reduced zero exempt none
notesstring

Example request

{
  "customer_id": 0,
  "job_id": 0,
  "quote_id": 0,
  "lines": [
    {
      "description": "string",
      "quantity": "string",
      "unit_pence": 0,
      "vat_rate": "standard"
    }
  ],
  "notes": "string"
}

Response 200 · object

The draft.

invoiceInvoice, required
An invoice or credit note. owed_pence is gross less credited and paid; a refund that succeeds takes its amount off paid_pence of the invoice it was paid on. overdue is worked out when read.
- idinteger (int64), required
- kindstring, required
  One of: invoice credit_note
- numberstring
  Absent on a draft.
- statusstring, required
  One of: draft sent part_paid paid
- customer_idinteger (int64) or null, required
- customer_namestring, required
  The customer's name now; empty once the customer is removed.
- job_idinteger (int64) or null, required
- quote_idinteger (int64) or null, required
- credits_invoice_idinteger (int64) or null, required
- bill_toobject
  The customer as the document was sent to them.
  - namestring, required
  - emailstring, required
  - addressstring, required
  - vat_numberstring
- issued_onstring (date)
- due_onstring (date)
- currencystring, required
  One of: GBP
- linesarray of InvoiceLine, required
  - idinteger (int64), required
  - descriptionstring, required
  - quantitystring, required
  - unit_penceinteger (int64), required
  - vat_ratestring, required
    One of: standard reduced zero exempt none
  - net_penceinteger (int64), required
- totalsobject, required
  - by_ratearray of object, required
    - ratestring, required
    - net_penceinteger (int64), required
    - vat_penceinteger (int64), required
  - net_penceinteger (int64), required
  - vat_penceinteger (int64), required
  - gross_penceinteger (int64), required
- paid_penceinteger (int64), required
- credited_penceinteger (int64), required
- refunded_penceinteger (int64), required
  On a credit note, what was refunded against it, or is being.
- owed_penceinteger (int64), required
- overdueboolean, required
- notesstring, required
- paymentsarray of InvoicePayment, required
  - idinteger (int64), required
  - invoice_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    One of: bank_transfer card cash cheque other paypal
  - referencestring, required
  - recorded_atstring, required
  - onlineboolean, required
    Paid online through a payment provider (method card, reference naming the provider's payment).
  - card_brandstring
  - card_last4string
  - refunded_penceinteger (int64), required
    What was given back of it online, or is being.
- refundsarray of InvoiceRefund, required
  Refunds of an invoice's payments, or against a credit note.
  - idinteger (int64), required
  - invoice_idinteger (int64), required
    The invoice the payment was recorded on.
  - payment_idinteger (int64), required
  - credit_note_idinteger (int64) or null, required
  - amount_penceinteger (int64), required
  - statusstring, required
    One of: pending succeeded failed
  - externalboolean, required
  - failurestring
  - requested_atstring, required
  - finished_atstring
- refundablearray of InvoiceRefundable, required
  On a sent credit note, the online payments it may still refund.
  - payment_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    card for a Stripe payment, paypal for a PayPal one.
    One of: card paypal
  - card_brandstring
  - card_last4string
- flagsarray of InvoiceFlag, required
  On an invoice, refunds made in the payment provider's dashboard that no credit note matches, and open disputes.
  - kindstring, required
    One of: refund dispute
  - amount_penceinteger (int64), required
  - messagestring, required
- syncInvoiceSync or null
  - idinteger (int64), required
  - statusstring, required
    One of: pending done failed
  - providerstring, required
  - errorstring
  - done_atstring
- created_atstring, required
- sent_atstring
- depositboolean
  A quote's deposit invoice.
- balanceboolean
  A quote's balance invoice, raised by the balance run before the move.

Example response 200

{
  "invoice": {
    "id": 0,
    "kind": "invoice",
    "number": "string",
    "status": "draft",
    "customer_id": 0,
    "customer_name": "string",
    "job_id": 0,
    "quote_id": 0,
    "credits_invoice_id": 0,
    "bill_to": {
      "name": "string",
      "email": "string",
      "address": "string",
      "vat_number": "string"
    },
    "issued_on": "date",
    "due_on": "date",
    "currency": "GBP",
    "lines": [
      {
        "id": 0,
        "description": "string",
        "quantity": "string",
        "unit_pence": 0,
        "vat_rate": "standard",
        "net_pence": 0
      }
    ],
    "totals": {
      "by_rate": [
        {
          "rate": "string",
          "net_pence": 0,
          "vat_pence": 0
        }
      ],
      "net_pence": 0,
      "vat_pence": 0,
      "gross_pence": 0
    },
    "paid_pence": 0,
    "credited_pence": 0,
    "refunded_pence": 0,
    "owed_pence": 0,
    "overdue": true,
    "notes": "string",
    "payments": [
      {
        "id": 0,
        "invoice_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "bank_transfer",
        "reference": "string",
        "recorded_at": "string",
        "online": true,
        "card_brand": "string",
        "card_last4": "string",
        "refunded_pence": 0
      }
    ],
    "refunds": [
      {
        "id": 0,
        "invoice_id": 0,
        "payment_id": 0,
        "credit_note_id": 0,
        "amount_pence": 0,
        "status": "pending",
        "external": true,
        "failure": "string",
        "requested_at": "string",
        "finished_at": "string"
      }
    ],
    "refundable": [
      {
        "payment_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "card",
        "card_brand": "string",
        "card_last4": "string"
      }
    ],
    "flags": [
      {
        "kind": "refund",
        "amount_pence": 0,
        "message": "string"
      }
    ],
    "sync": {
      "id": 0,
      "status": "pending",
      "provider": "string",
      "error": "string",
      "done_at": "string"
    },
    "created_at": "string",
    "sent_at": "string",
    "deposit": true,
    "balance": true
  }
}

Response 400 · Error

The request is not valid.

Fields as in Invoiced and received by month

Response 401 · Error

No tenant key, or no valid session.

Fields as in Invoiced and received by month

Response 403 · Error

The session may not do this.

Fields as in Invoiced and received by month

Response 404 · Error

Not found, or not yours.

Fields as in Invoiced and received by month

Response 500 · Error

Something failed on our side.

Fields as in Invoiced and received by month

GET/v1/admin/invoices/{id}

An invoice or credit note

Needs the invoices.read permission. With its lines, its payments not removed, what is owed and whether it is overdue.

Parameters

idstring, in the path, required

Response 200 · object

The document.

invoiceInvoice, required
An invoice or credit note. owed_pence is gross less credited and paid; a refund that succeeds takes its amount off paid_pence of the invoice it was paid on. overdue is worked out when read.
- idinteger (int64), required
- kindstring, required
  One of: invoice credit_note
- numberstring
  Absent on a draft.
- statusstring, required
  One of: draft sent part_paid paid
- customer_idinteger (int64) or null, required
- customer_namestring, required
  The customer's name now; empty once the customer is removed.
- job_idinteger (int64) or null, required
- quote_idinteger (int64) or null, required
- credits_invoice_idinteger (int64) or null, required
- bill_toobject
  The customer as the document was sent to them.
  - namestring, required
  - emailstring, required
  - addressstring, required
  - vat_numberstring
- issued_onstring (date)
- due_onstring (date)
- currencystring, required
  One of: GBP
- linesarray of InvoiceLine, required
  - idinteger (int64), required
  - descriptionstring, required
  - quantitystring, required
  - unit_penceinteger (int64), required
  - vat_ratestring, required
    One of: standard reduced zero exempt none
  - net_penceinteger (int64), required
- totalsobject, required
  - by_ratearray of object, required
    - ratestring, required
    - net_penceinteger (int64), required
    - vat_penceinteger (int64), required
  - net_penceinteger (int64), required
  - vat_penceinteger (int64), required
  - gross_penceinteger (int64), required
- paid_penceinteger (int64), required
- credited_penceinteger (int64), required
- refunded_penceinteger (int64), required
  On a credit note, what was refunded against it, or is being.
- owed_penceinteger (int64), required
- overdueboolean, required
- notesstring, required
- paymentsarray of InvoicePayment, required
  - idinteger (int64), required
  - invoice_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    One of: bank_transfer card cash cheque other paypal
  - referencestring, required
  - recorded_atstring, required
  - onlineboolean, required
    Paid online through a payment provider (method card, reference naming the provider's payment).
  - card_brandstring
  - card_last4string
  - refunded_penceinteger (int64), required
    What was given back of it online, or is being.
- refundsarray of InvoiceRefund, required
  Refunds of an invoice's payments, or against a credit note.
  - idinteger (int64), required
  - invoice_idinteger (int64), required
    The invoice the payment was recorded on.
  - payment_idinteger (int64), required
  - credit_note_idinteger (int64) or null, required
  - amount_penceinteger (int64), required
  - statusstring, required
    One of: pending succeeded failed
  - externalboolean, required
  - failurestring
  - requested_atstring, required
  - finished_atstring
- refundablearray of InvoiceRefundable, required
  On a sent credit note, the online payments it may still refund.
  - payment_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    card for a Stripe payment, paypal for a PayPal one.
    One of: card paypal
  - card_brandstring
  - card_last4string
- flagsarray of InvoiceFlag, required
  On an invoice, refunds made in the payment provider's dashboard that no credit note matches, and open disputes.
  - kindstring, required
    One of: refund dispute
  - amount_penceinteger (int64), required
  - messagestring, required
- syncInvoiceSync or null
  - idinteger (int64), required
  - statusstring, required
    One of: pending done failed
  - providerstring, required
  - errorstring
  - done_atstring
- created_atstring, required
- sent_atstring
- depositboolean
  A quote's deposit invoice.
- balanceboolean
  A quote's balance invoice, raised by the balance run before the move.

Example response 200

{
  "invoice": {
    "id": 0,
    "kind": "invoice",
    "number": "string",
    "status": "draft",
    "customer_id": 0,
    "customer_name": "string",
    "job_id": 0,
    "quote_id": 0,
    "credits_invoice_id": 0,
    "bill_to": {
      "name": "string",
      "email": "string",
      "address": "string",
      "vat_number": "string"
    },
    "issued_on": "date",
    "due_on": "date",
    "currency": "GBP",
    "lines": [
      {
        "id": 0,
        "description": "string",
        "quantity": "string",
        "unit_pence": 0,
        "vat_rate": "standard",
        "net_pence": 0
      }
    ],
    "totals": {
      "by_rate": [
        {
          "rate": "string",
          "net_pence": 0,
          "vat_pence": 0
        }
      ],
      "net_pence": 0,
      "vat_pence": 0,
      "gross_pence": 0
    },
    "paid_pence": 0,
    "credited_pence": 0,
    "refunded_pence": 0,
    "owed_pence": 0,
    "overdue": true,
    "notes": "string",
    "payments": [
      {
        "id": 0,
        "invoice_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "bank_transfer",
        "reference": "string",
        "recorded_at": "string",
        "online": true,
        "card_brand": "string",
        "card_last4": "string",
        "refunded_pence": 0
      }
    ],
    "refunds": [
      {
        "id": 0,
        "invoice_id": 0,
        "payment_id": 0,
        "credit_note_id": 0,
        "amount_pence": 0,
        "status": "pending",
        "external": true,
        "failure": "string",
        "requested_at": "string",
        "finished_at": "string"
      }
    ],
    "refundable": [
      {
        "payment_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "card",
        "card_brand": "string",
        "card_last4": "string"
      }
    ],
    "flags": [
      {
        "kind": "refund",
        "amount_pence": 0,
        "message": "string"
      }
    ],
    "sync": {
      "id": 0,
      "status": "pending",
      "provider": "string",
      "error": "string",
      "done_at": "string"
    },
    "created_at": "string",
    "sent_at": "string",
    "deposit": true,
    "balance": true
  }
}

Response 400 · Error

The request is not valid.

Fields as in Invoiced and received by month

Response 401 · Error

No tenant key, or no valid session.

Fields as in Invoiced and received by month

Response 403 · Error

The session may not do this.

Fields as in Invoiced and received by month

Response 404 · Error

Not found, or not yours.

Fields as in Invoiced and received by month

Response 500 · Error

Something failed on our side.

Fields as in Invoiced and received by month

PUT/v1/admin/invoices/{id}

Change a draft

Needs the invoices.write permission. Replaces the lines and notes; a sent document is a conflict.

Parameters

idstring, in the path, required

Request body · object

linesarray of InvoiceLineInput
- descriptionstring, required
- quantitystring, required
  A decimal above 0, with up to 6 digits and 3 places.
- unit_penceinteger (int64), required
- vat_ratestring, required
  One of: standard reduced zero exempt none
notesstring

Example request

{
  "lines": [
    {
      "description": "string",
      "quantity": "string",
      "unit_pence": 0,
      "vat_rate": "standard"
    }
  ],
  "notes": "string"
}

Response 200 · object

The draft.

invoiceInvoice, required
An invoice or credit note. owed_pence is gross less credited and paid; a refund that succeeds takes its amount off paid_pence of the invoice it was paid on. overdue is worked out when read.
- idinteger (int64), required
- kindstring, required
  One of: invoice credit_note
- numberstring
  Absent on a draft.
- statusstring, required
  One of: draft sent part_paid paid
- customer_idinteger (int64) or null, required
- customer_namestring, required
  The customer's name now; empty once the customer is removed.
- job_idinteger (int64) or null, required
- quote_idinteger (int64) or null, required
- credits_invoice_idinteger (int64) or null, required
- bill_toobject
  The customer as the document was sent to them.
  - namestring, required
  - emailstring, required
  - addressstring, required
  - vat_numberstring
- issued_onstring (date)
- due_onstring (date)
- currencystring, required
  One of: GBP
- linesarray of InvoiceLine, required
  - idinteger (int64), required
  - descriptionstring, required
  - quantitystring, required
  - unit_penceinteger (int64), required
  - vat_ratestring, required
    One of: standard reduced zero exempt none
  - net_penceinteger (int64), required
- totalsobject, required
  - by_ratearray of object, required
    - ratestring, required
    - net_penceinteger (int64), required
    - vat_penceinteger (int64), required
  - net_penceinteger (int64), required
  - vat_penceinteger (int64), required
  - gross_penceinteger (int64), required
- paid_penceinteger (int64), required
- credited_penceinteger (int64), required
- refunded_penceinteger (int64), required
  On a credit note, what was refunded against it, or is being.
- owed_penceinteger (int64), required
- overdueboolean, required
- notesstring, required
- paymentsarray of InvoicePayment, required
  - idinteger (int64), required
  - invoice_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    One of: bank_transfer card cash cheque other paypal
  - referencestring, required
  - recorded_atstring, required
  - onlineboolean, required
    Paid online through a payment provider (method card, reference naming the provider's payment).
  - card_brandstring
  - card_last4string
  - refunded_penceinteger (int64), required
    What was given back of it online, or is being.
- refundsarray of InvoiceRefund, required
  Refunds of an invoice's payments, or against a credit note.
  - idinteger (int64), required
  - invoice_idinteger (int64), required
    The invoice the payment was recorded on.
  - payment_idinteger (int64), required
  - credit_note_idinteger (int64) or null, required
  - amount_penceinteger (int64), required
  - statusstring, required
    One of: pending succeeded failed
  - externalboolean, required
  - failurestring
  - requested_atstring, required
  - finished_atstring
- refundablearray of InvoiceRefundable, required
  On a sent credit note, the online payments it may still refund.
  - payment_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    card for a Stripe payment, paypal for a PayPal one.
    One of: card paypal
  - card_brandstring
  - card_last4string
- flagsarray of InvoiceFlag, required
  On an invoice, refunds made in the payment provider's dashboard that no credit note matches, and open disputes.
  - kindstring, required
    One of: refund dispute
  - amount_penceinteger (int64), required
  - messagestring, required
- syncInvoiceSync or null
  - idinteger (int64), required
  - statusstring, required
    One of: pending done failed
  - providerstring, required
  - errorstring
  - done_atstring
- created_atstring, required
- sent_atstring
- depositboolean
  A quote's deposit invoice.
- balanceboolean
  A quote's balance invoice, raised by the balance run before the move.

Example response 200

{
  "invoice": {
    "id": 0,
    "kind": "invoice",
    "number": "string",
    "status": "draft",
    "customer_id": 0,
    "customer_name": "string",
    "job_id": 0,
    "quote_id": 0,
    "credits_invoice_id": 0,
    "bill_to": {
      "name": "string",
      "email": "string",
      "address": "string",
      "vat_number": "string"
    },
    "issued_on": "date",
    "due_on": "date",
    "currency": "GBP",
    "lines": [
      {
        "id": 0,
        "description": "string",
        "quantity": "string",
        "unit_pence": 0,
        "vat_rate": "standard",
        "net_pence": 0
      }
    ],
    "totals": {
      "by_rate": [
        {
          "rate": "string",
          "net_pence": 0,
          "vat_pence": 0
        }
      ],
      "net_pence": 0,
      "vat_pence": 0,
      "gross_pence": 0
    },
    "paid_pence": 0,
    "credited_pence": 0,
    "refunded_pence": 0,
    "owed_pence": 0,
    "overdue": true,
    "notes": "string",
    "payments": [
      {
        "id": 0,
        "invoice_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "bank_transfer",
        "reference": "string",
        "recorded_at": "string",
        "online": true,
        "card_brand": "string",
        "card_last4": "string",
        "refunded_pence": 0
      }
    ],
    "refunds": [
      {
        "id": 0,
        "invoice_id": 0,
        "payment_id": 0,
        "credit_note_id": 0,
        "amount_pence": 0,
        "status": "pending",
        "external": true,
        "failure": "string",
        "requested_at": "string",
        "finished_at": "string"
      }
    ],
    "refundable": [
      {
        "payment_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "card",
        "card_brand": "string",
        "card_last4": "string"
      }
    ],
    "flags": [
      {
        "kind": "refund",
        "amount_pence": 0,
        "message": "string"
      }
    ],
    "sync": {
      "id": 0,
      "status": "pending",
      "provider": "string",
      "error": "string",
      "done_at": "string"
    },
    "created_at": "string",
    "sent_at": "string",
    "deposit": true,
    "balance": true
  }
}

Response 400 · Error

The request is not valid.

Fields as in Invoiced and received by month

Response 401 · Error

No tenant key, or no valid session.

Fields as in Invoiced and received by month

Response 403 · Error

The session may not do this.

Fields as in Invoiced and received by month

Response 404 · Error

Not found, or not yours.

Fields as in Invoiced and received by month

Response 409 · Error

It clashes with what is stored.

Fields as in Invoiced and received by month

Response 500 · Error

Something failed on our side.

Fields as in Invoiced and received by month

DELETE/v1/admin/invoices/{id}

Delete a draft

Needs the invoices.write permission. A sent document is a conflict.

Parameters

idstring, in the path, required

Response 200 · object

Deleted.

deletedboolean, required

Example response 200

{
  "deleted": true
}

Response 400 · Error

The request is not valid.

Fields as in Invoiced and received by month

Response 401 · Error

No tenant key, or no valid session.

Fields as in Invoiced and received by month

Response 403 · Error

The session may not do this.

Fields as in Invoiced and received by month

Response 404 · Error

Not found, or not yours.

Fields as in Invoiced and received by month

Response 409 · Error

It clashes with what is stored.

Fields as in Invoiced and received by month

Response 500 · Error

Something failed on our side.

Fields as in Invoiced and received by month

POST/v1/admin/invoices/{id}/send

Send a draft

Needs the invoices.write permission. Numbers it from the business's number format, sets its date (today, in the business's time zone) and due date (plus invoice_terms_days; a credit note is due on its date), copies the customer as billed, emails them the PDF and locks it. An invoice needs a total above 0; a credit note can't be more than is left uncredited on its invoice. Published as invoice.sent.

Parameters

idstring, in the path, required

Response 200 · object

The sent document.

invoiceInvoice, required
An invoice or credit note. owed_pence is gross less credited and paid; a refund that succeeds takes its amount off paid_pence of the invoice it was paid on. overdue is worked out when read.
- idinteger (int64), required
- kindstring, required
  One of: invoice credit_note
- numberstring
  Absent on a draft.
- statusstring, required
  One of: draft sent part_paid paid
- customer_idinteger (int64) or null, required
- customer_namestring, required
  The customer's name now; empty once the customer is removed.
- job_idinteger (int64) or null, required
- quote_idinteger (int64) or null, required
- credits_invoice_idinteger (int64) or null, required
- bill_toobject
  The customer as the document was sent to them.
  - namestring, required
  - emailstring, required
  - addressstring, required
  - vat_numberstring
- issued_onstring (date)
- due_onstring (date)
- currencystring, required
  One of: GBP
- linesarray of InvoiceLine, required
  - idinteger (int64), required
  - descriptionstring, required
  - quantitystring, required
  - unit_penceinteger (int64), required
  - vat_ratestring, required
    One of: standard reduced zero exempt none
  - net_penceinteger (int64), required
- totalsobject, required
  - by_ratearray of object, required
    - ratestring, required
    - net_penceinteger (int64), required
    - vat_penceinteger (int64), required
  - net_penceinteger (int64), required
  - vat_penceinteger (int64), required
  - gross_penceinteger (int64), required
- paid_penceinteger (int64), required
- credited_penceinteger (int64), required
- refunded_penceinteger (int64), required
  On a credit note, what was refunded against it, or is being.
- owed_penceinteger (int64), required
- overdueboolean, required
- notesstring, required
- paymentsarray of InvoicePayment, required
  - idinteger (int64), required
  - invoice_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    One of: bank_transfer card cash cheque other paypal
  - referencestring, required
  - recorded_atstring, required
  - onlineboolean, required
    Paid online through a payment provider (method card, reference naming the provider's payment).
  - card_brandstring
  - card_last4string
  - refunded_penceinteger (int64), required
    What was given back of it online, or is being.
- refundsarray of InvoiceRefund, required
  Refunds of an invoice's payments, or against a credit note.
  - idinteger (int64), required
  - invoice_idinteger (int64), required
    The invoice the payment was recorded on.
  - payment_idinteger (int64), required
  - credit_note_idinteger (int64) or null, required
  - amount_penceinteger (int64), required
  - statusstring, required
    One of: pending succeeded failed
  - externalboolean, required
  - failurestring
  - requested_atstring, required
  - finished_atstring
- refundablearray of InvoiceRefundable, required
  On a sent credit note, the online payments it may still refund.
  - payment_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    card for a Stripe payment, paypal for a PayPal one.
    One of: card paypal
  - card_brandstring
  - card_last4string
- flagsarray of InvoiceFlag, required
  On an invoice, refunds made in the payment provider's dashboard that no credit note matches, and open disputes.
  - kindstring, required
    One of: refund dispute
  - amount_penceinteger (int64), required
  - messagestring, required
- syncInvoiceSync or null
  - idinteger (int64), required
  - statusstring, required
    One of: pending done failed
  - providerstring, required
  - errorstring
  - done_atstring
- created_atstring, required
- sent_atstring
- depositboolean
  A quote's deposit invoice.
- balanceboolean
  A quote's balance invoice, raised by the balance run before the move.

Example response 200

{
  "invoice": {
    "id": 0,
    "kind": "invoice",
    "number": "string",
    "status": "draft",
    "customer_id": 0,
    "customer_name": "string",
    "job_id": 0,
    "quote_id": 0,
    "credits_invoice_id": 0,
    "bill_to": {
      "name": "string",
      "email": "string",
      "address": "string",
      "vat_number": "string"
    },
    "issued_on": "date",
    "due_on": "date",
    "currency": "GBP",
    "lines": [
      {
        "id": 0,
        "description": "string",
        "quantity": "string",
        "unit_pence": 0,
        "vat_rate": "standard",
        "net_pence": 0
      }
    ],
    "totals": {
      "by_rate": [
        {
          "rate": "string",
          "net_pence": 0,
          "vat_pence": 0
        }
      ],
      "net_pence": 0,
      "vat_pence": 0,
      "gross_pence": 0
    },
    "paid_pence": 0,
    "credited_pence": 0,
    "refunded_pence": 0,
    "owed_pence": 0,
    "overdue": true,
    "notes": "string",
    "payments": [
      {
        "id": 0,
        "invoice_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "bank_transfer",
        "reference": "string",
        "recorded_at": "string",
        "online": true,
        "card_brand": "string",
        "card_last4": "string",
        "refunded_pence": 0
      }
    ],
    "refunds": [
      {
        "id": 0,
        "invoice_id": 0,
        "payment_id": 0,
        "credit_note_id": 0,
        "amount_pence": 0,
        "status": "pending",
        "external": true,
        "failure": "string",
        "requested_at": "string",
        "finished_at": "string"
      }
    ],
    "refundable": [
      {
        "payment_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "card",
        "card_brand": "string",
        "card_last4": "string"
      }
    ],
    "flags": [
      {
        "kind": "refund",
        "amount_pence": 0,
        "message": "string"
      }
    ],
    "sync": {
      "id": 0,
      "status": "pending",
      "provider": "string",
      "error": "string",
      "done_at": "string"
    },
    "created_at": "string",
    "sent_at": "string",
    "deposit": true,
    "balance": true
  }
}

Response 400 · Error

The request is not valid.

Fields as in Invoiced and received by month

Response 401 · Error

No tenant key, or no valid session.

Fields as in Invoiced and received by month

Response 403 · Error

The session may not do this.

Fields as in Invoiced and received by month

Response 404 · Error

Not found, or not yours.

Fields as in Invoiced and received by month

Response 409 · Error

It clashes with what is stored.

Fields as in Invoiced and received by month

Response 500 · Error

Something failed on our side.

Fields as in Invoiced and received by month

POST/v1/admin/invoices/{id}/resend

Email a sent document again

Needs the invoices.write permission.

Parameters

idstring, in the path, required

Response 200 · object

The document.

invoiceInvoice, required
An invoice or credit note. owed_pence is gross less credited and paid; a refund that succeeds takes its amount off paid_pence of the invoice it was paid on. overdue is worked out when read.
- idinteger (int64), required
- kindstring, required
  One of: invoice credit_note
- numberstring
  Absent on a draft.
- statusstring, required
  One of: draft sent part_paid paid
- customer_idinteger (int64) or null, required
- customer_namestring, required
  The customer's name now; empty once the customer is removed.
- job_idinteger (int64) or null, required
- quote_idinteger (int64) or null, required
- credits_invoice_idinteger (int64) or null, required
- bill_toobject
  The customer as the document was sent to them.
  - namestring, required
  - emailstring, required
  - addressstring, required
  - vat_numberstring
- issued_onstring (date)
- due_onstring (date)
- currencystring, required
  One of: GBP
- linesarray of InvoiceLine, required
  - idinteger (int64), required
  - descriptionstring, required
  - quantitystring, required
  - unit_penceinteger (int64), required
  - vat_ratestring, required
    One of: standard reduced zero exempt none
  - net_penceinteger (int64), required
- totalsobject, required
  - by_ratearray of object, required
    - ratestring, required
    - net_penceinteger (int64), required
    - vat_penceinteger (int64), required
  - net_penceinteger (int64), required
  - vat_penceinteger (int64), required
  - gross_penceinteger (int64), required
- paid_penceinteger (int64), required
- credited_penceinteger (int64), required
- refunded_penceinteger (int64), required
  On a credit note, what was refunded against it, or is being.
- owed_penceinteger (int64), required
- overdueboolean, required
- notesstring, required
- paymentsarray of InvoicePayment, required
  - idinteger (int64), required
  - invoice_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    One of: bank_transfer card cash cheque other paypal
  - referencestring, required
  - recorded_atstring, required
  - onlineboolean, required
    Paid online through a payment provider (method card, reference naming the provider's payment).
  - card_brandstring
  - card_last4string
  - refunded_penceinteger (int64), required
    What was given back of it online, or is being.
- refundsarray of InvoiceRefund, required
  Refunds of an invoice's payments, or against a credit note.
  - idinteger (int64), required
  - invoice_idinteger (int64), required
    The invoice the payment was recorded on.
  - payment_idinteger (int64), required
  - credit_note_idinteger (int64) or null, required
  - amount_penceinteger (int64), required
  - statusstring, required
    One of: pending succeeded failed
  - externalboolean, required
  - failurestring
  - requested_atstring, required
  - finished_atstring
- refundablearray of InvoiceRefundable, required
  On a sent credit note, the online payments it may still refund.
  - payment_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    card for a Stripe payment, paypal for a PayPal one.
    One of: card paypal
  - card_brandstring
  - card_last4string
- flagsarray of InvoiceFlag, required
  On an invoice, refunds made in the payment provider's dashboard that no credit note matches, and open disputes.
  - kindstring, required
    One of: refund dispute
  - amount_penceinteger (int64), required
  - messagestring, required
- syncInvoiceSync or null
  - idinteger (int64), required
  - statusstring, required
    One of: pending done failed
  - providerstring, required
  - errorstring
  - done_atstring
- created_atstring, required
- sent_atstring
- depositboolean
  A quote's deposit invoice.
- balanceboolean
  A quote's balance invoice, raised by the balance run before the move.

Example response 200

{
  "invoice": {
    "id": 0,
    "kind": "invoice",
    "number": "string",
    "status": "draft",
    "customer_id": 0,
    "customer_name": "string",
    "job_id": 0,
    "quote_id": 0,
    "credits_invoice_id": 0,
    "bill_to": {
      "name": "string",
      "email": "string",
      "address": "string",
      "vat_number": "string"
    },
    "issued_on": "date",
    "due_on": "date",
    "currency": "GBP",
    "lines": [
      {
        "id": 0,
        "description": "string",
        "quantity": "string",
        "unit_pence": 0,
        "vat_rate": "standard",
        "net_pence": 0
      }
    ],
    "totals": {
      "by_rate": [
        {
          "rate": "string",
          "net_pence": 0,
          "vat_pence": 0
        }
      ],
      "net_pence": 0,
      "vat_pence": 0,
      "gross_pence": 0
    },
    "paid_pence": 0,
    "credited_pence": 0,
    "refunded_pence": 0,
    "owed_pence": 0,
    "overdue": true,
    "notes": "string",
    "payments": [
      {
        "id": 0,
        "invoice_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "bank_transfer",
        "reference": "string",
        "recorded_at": "string",
        "online": true,
        "card_brand": "string",
        "card_last4": "string",
        "refunded_pence": 0
      }
    ],
    "refunds": [
      {
        "id": 0,
        "invoice_id": 0,
        "payment_id": 0,
        "credit_note_id": 0,
        "amount_pence": 0,
        "status": "pending",
        "external": true,
        "failure": "string",
        "requested_at": "string",
        "finished_at": "string"
      }
    ],
    "refundable": [
      {
        "payment_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "card",
        "card_brand": "string",
        "card_last4": "string"
      }
    ],
    "flags": [
      {
        "kind": "refund",
        "amount_pence": 0,
        "message": "string"
      }
    ],
    "sync": {
      "id": 0,
      "status": "pending",
      "provider": "string",
      "error": "string",
      "done_at": "string"
    },
    "created_at": "string",
    "sent_at": "string",
    "deposit": true,
    "balance": true
  }
}

Response 400 · Error

The request is not valid.

Fields as in Invoiced and received by month

Response 401 · Error

No tenant key, or no valid session.

Fields as in Invoiced and received by month

Response 403 · Error

The session may not do this.

Fields as in Invoiced and received by month

Response 404 · Error

Not found, or not yours.

Fields as in Invoiced and received by month

Response 409 · Error

It clashes with what is stored.

Fields as in Invoiced and received by month

Response 500 · Error

Something failed on our side.

Fields as in Invoiced and received by month

GET/v1/admin/invoices/{id}/pdf

A document as a PDF

Needs the invoices.read permission. Made on request; a draft is marked Draft.

Parameters

idstring, in the path, required

Response 200

The PDF.

Response 400 · Error

The request is not valid.

Fields as in Invoiced and received by month

Response 401 · Error

No tenant key, or no valid session.

Fields as in Invoiced and received by month

Response 403 · Error

The session may not do this.

Fields as in Invoiced and received by month

Response 404 · Error

Not found, or not yours.

Fields as in Invoiced and received by month

Response 500 · Error

Something failed on our side.

Fields as in Invoiced and received by month

POST/v1/admin/invoices/{id}/credit

Raise a draft credit note

Needs the invoices.write permission. Against a sent invoice. Without lines, a copy of the invoice's lines, which needs nothing credited yet. Sending it lowers what is owed on the invoice.

Parameters

idstring, in the path, required

Request body · object

linesarray of InvoiceLineInput
- descriptionstring, required
- quantitystring, required
  A decimal above 0, with up to 6 digits and 3 places.
- unit_penceinteger (int64), required
- vat_ratestring, required
  One of: standard reduced zero exempt none

Example request

{
  "lines": [
    {
      "description": "string",
      "quantity": "string",
      "unit_pence": 0,
      "vat_rate": "standard"
    }
  ]
}

Response 200 · object

The draft credit note.

invoiceInvoice, required
An invoice or credit note. owed_pence is gross less credited and paid; a refund that succeeds takes its amount off paid_pence of the invoice it was paid on. overdue is worked out when read.
- idinteger (int64), required
- kindstring, required
  One of: invoice credit_note
- numberstring
  Absent on a draft.
- statusstring, required
  One of: draft sent part_paid paid
- customer_idinteger (int64) or null, required
- customer_namestring, required
  The customer's name now; empty once the customer is removed.
- job_idinteger (int64) or null, required
- quote_idinteger (int64) or null, required
- credits_invoice_idinteger (int64) or null, required
- bill_toobject
  The customer as the document was sent to them.
  - namestring, required
  - emailstring, required
  - addressstring, required
  - vat_numberstring
- issued_onstring (date)
- due_onstring (date)
- currencystring, required
  One of: GBP
- linesarray of InvoiceLine, required
  - idinteger (int64), required
  - descriptionstring, required
  - quantitystring, required
  - unit_penceinteger (int64), required
  - vat_ratestring, required
    One of: standard reduced zero exempt none
  - net_penceinteger (int64), required
- totalsobject, required
  - by_ratearray of object, required
    - ratestring, required
    - net_penceinteger (int64), required
    - vat_penceinteger (int64), required
  - net_penceinteger (int64), required
  - vat_penceinteger (int64), required
  - gross_penceinteger (int64), required
- paid_penceinteger (int64), required
- credited_penceinteger (int64), required
- refunded_penceinteger (int64), required
  On a credit note, what was refunded against it, or is being.
- owed_penceinteger (int64), required
- overdueboolean, required
- notesstring, required
- paymentsarray of InvoicePayment, required
  - idinteger (int64), required
  - invoice_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    One of: bank_transfer card cash cheque other paypal
  - referencestring, required
  - recorded_atstring, required
  - onlineboolean, required
    Paid online through a payment provider (method card, reference naming the provider's payment).
  - card_brandstring
  - card_last4string
  - refunded_penceinteger (int64), required
    What was given back of it online, or is being.
- refundsarray of InvoiceRefund, required
  Refunds of an invoice's payments, or against a credit note.
  - idinteger (int64), required
  - invoice_idinteger (int64), required
    The invoice the payment was recorded on.
  - payment_idinteger (int64), required
  - credit_note_idinteger (int64) or null, required
  - amount_penceinteger (int64), required
  - statusstring, required
    One of: pending succeeded failed
  - externalboolean, required
  - failurestring
  - requested_atstring, required
  - finished_atstring
- refundablearray of InvoiceRefundable, required
  On a sent credit note, the online payments it may still refund.
  - payment_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    card for a Stripe payment, paypal for a PayPal one.
    One of: card paypal
  - card_brandstring
  - card_last4string
- flagsarray of InvoiceFlag, required
  On an invoice, refunds made in the payment provider's dashboard that no credit note matches, and open disputes.
  - kindstring, required
    One of: refund dispute
  - amount_penceinteger (int64), required
  - messagestring, required
- syncInvoiceSync or null
  - idinteger (int64), required
  - statusstring, required
    One of: pending done failed
  - providerstring, required
  - errorstring
  - done_atstring
- created_atstring, required
- sent_atstring
- depositboolean
  A quote's deposit invoice.
- balanceboolean
  A quote's balance invoice, raised by the balance run before the move.

Example response 200

{
  "invoice": {
    "id": 0,
    "kind": "invoice",
    "number": "string",
    "status": "draft",
    "customer_id": 0,
    "customer_name": "string",
    "job_id": 0,
    "quote_id": 0,
    "credits_invoice_id": 0,
    "bill_to": {
      "name": "string",
      "email": "string",
      "address": "string",
      "vat_number": "string"
    },
    "issued_on": "date",
    "due_on": "date",
    "currency": "GBP",
    "lines": [
      {
        "id": 0,
        "description": "string",
        "quantity": "string",
        "unit_pence": 0,
        "vat_rate": "standard",
        "net_pence": 0
      }
    ],
    "totals": {
      "by_rate": [
        {
          "rate": "string",
          "net_pence": 0,
          "vat_pence": 0
        }
      ],
      "net_pence": 0,
      "vat_pence": 0,
      "gross_pence": 0
    },
    "paid_pence": 0,
    "credited_pence": 0,
    "refunded_pence": 0,
    "owed_pence": 0,
    "overdue": true,
    "notes": "string",
    "payments": [
      {
        "id": 0,
        "invoice_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "bank_transfer",
        "reference": "string",
        "recorded_at": "string",
        "online": true,
        "card_brand": "string",
        "card_last4": "string",
        "refunded_pence": 0
      }
    ],
    "refunds": [
      {
        "id": 0,
        "invoice_id": 0,
        "payment_id": 0,
        "credit_note_id": 0,
        "amount_pence": 0,
        "status": "pending",
        "external": true,
        "failure": "string",
        "requested_at": "string",
        "finished_at": "string"
      }
    ],
    "refundable": [
      {
        "payment_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "card",
        "card_brand": "string",
        "card_last4": "string"
      }
    ],
    "flags": [
      {
        "kind": "refund",
        "amount_pence": 0,
        "message": "string"
      }
    ],
    "sync": {
      "id": 0,
      "status": "pending",
      "provider": "string",
      "error": "string",
      "done_at": "string"
    },
    "created_at": "string",
    "sent_at": "string",
    "deposit": true,
    "balance": true
  }
}

Response 400 · Error

The request is not valid.

Fields as in Invoiced and received by month

Response 401 · Error

No tenant key, or no valid session.

Fields as in Invoiced and received by month

Response 403 · Error

The session may not do this.

Fields as in Invoiced and received by month

Response 404 · Error

Not found, or not yours.

Fields as in Invoiced and received by month

Response 409 · Error

It clashes with what is stored.

Fields as in Invoiced and received by month

Response 500 · Error

Something failed on our side.

Fields as in Invoiced and received by month

POST/v1/admin/invoices/{id}/payments

Record a payment

Needs the invoices.write permission. Against a sent invoice; above 0 and at most what is owed. Published as invoice.paid once nothing is owed.

Parameters

idstring, in the path, required

Request body · object

amount_penceinteger (int64), required
paid_onstring (date), required
methodstring, required
One of: bank_transfer card cash cheque other paypal
referencestring

Example request

{
  "amount_pence": 0,
  "paid_on": "date",
  "method": "bank_transfer",
  "reference": "string"
}

Response 200 · object

The invoice.

invoiceInvoice, required
An invoice or credit note. owed_pence is gross less credited and paid; a refund that succeeds takes its amount off paid_pence of the invoice it was paid on. overdue is worked out when read.
- idinteger (int64), required
- kindstring, required
  One of: invoice credit_note
- numberstring
  Absent on a draft.
- statusstring, required
  One of: draft sent part_paid paid
- customer_idinteger (int64) or null, required
- customer_namestring, required
  The customer's name now; empty once the customer is removed.
- job_idinteger (int64) or null, required
- quote_idinteger (int64) or null, required
- credits_invoice_idinteger (int64) or null, required
- bill_toobject
  The customer as the document was sent to them.
  - namestring, required
  - emailstring, required
  - addressstring, required
  - vat_numberstring
- issued_onstring (date)
- due_onstring (date)
- currencystring, required
  One of: GBP
- linesarray of InvoiceLine, required
  - idinteger (int64), required
  - descriptionstring, required
  - quantitystring, required
  - unit_penceinteger (int64), required
  - vat_ratestring, required
    One of: standard reduced zero exempt none
  - net_penceinteger (int64), required
- totalsobject, required
  - by_ratearray of object, required
    - ratestring, required
    - net_penceinteger (int64), required
    - vat_penceinteger (int64), required
  - net_penceinteger (int64), required
  - vat_penceinteger (int64), required
  - gross_penceinteger (int64), required
- paid_penceinteger (int64), required
- credited_penceinteger (int64), required
- refunded_penceinteger (int64), required
  On a credit note, what was refunded against it, or is being.
- owed_penceinteger (int64), required
- overdueboolean, required
- notesstring, required
- paymentsarray of InvoicePayment, required
  - idinteger (int64), required
  - invoice_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    One of: bank_transfer card cash cheque other paypal
  - referencestring, required
  - recorded_atstring, required
  - onlineboolean, required
    Paid online through a payment provider (method card, reference naming the provider's payment).
  - card_brandstring
  - card_last4string
  - refunded_penceinteger (int64), required
    What was given back of it online, or is being.
- refundsarray of InvoiceRefund, required
  Refunds of an invoice's payments, or against a credit note.
  - idinteger (int64), required
  - invoice_idinteger (int64), required
    The invoice the payment was recorded on.
  - payment_idinteger (int64), required
  - credit_note_idinteger (int64) or null, required
  - amount_penceinteger (int64), required
  - statusstring, required
    One of: pending succeeded failed
  - externalboolean, required
  - failurestring
  - requested_atstring, required
  - finished_atstring
- refundablearray of InvoiceRefundable, required
  On a sent credit note, the online payments it may still refund.
  - payment_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    card for a Stripe payment, paypal for a PayPal one.
    One of: card paypal
  - card_brandstring
  - card_last4string
- flagsarray of InvoiceFlag, required
  On an invoice, refunds made in the payment provider's dashboard that no credit note matches, and open disputes.
  - kindstring, required
    One of: refund dispute
  - amount_penceinteger (int64), required
  - messagestring, required
- syncInvoiceSync or null
  - idinteger (int64), required
  - statusstring, required
    One of: pending done failed
  - providerstring, required
  - errorstring
  - done_atstring
- created_atstring, required
- sent_atstring
- depositboolean
  A quote's deposit invoice.
- balanceboolean
  A quote's balance invoice, raised by the balance run before the move.

Example response 200

{
  "invoice": {
    "id": 0,
    "kind": "invoice",
    "number": "string",
    "status": "draft",
    "customer_id": 0,
    "customer_name": "string",
    "job_id": 0,
    "quote_id": 0,
    "credits_invoice_id": 0,
    "bill_to": {
      "name": "string",
      "email": "string",
      "address": "string",
      "vat_number": "string"
    },
    "issued_on": "date",
    "due_on": "date",
    "currency": "GBP",
    "lines": [
      {
        "id": 0,
        "description": "string",
        "quantity": "string",
        "unit_pence": 0,
        "vat_rate": "standard",
        "net_pence": 0
      }
    ],
    "totals": {
      "by_rate": [
        {
          "rate": "string",
          "net_pence": 0,
          "vat_pence": 0
        }
      ],
      "net_pence": 0,
      "vat_pence": 0,
      "gross_pence": 0
    },
    "paid_pence": 0,
    "credited_pence": 0,
    "refunded_pence": 0,
    "owed_pence": 0,
    "overdue": true,
    "notes": "string",
    "payments": [
      {
        "id": 0,
        "invoice_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "bank_transfer",
        "reference": "string",
        "recorded_at": "string",
        "online": true,
        "card_brand": "string",
        "card_last4": "string",
        "refunded_pence": 0
      }
    ],
    "refunds": [
      {
        "id": 0,
        "invoice_id": 0,
        "payment_id": 0,
        "credit_note_id": 0,
        "amount_pence": 0,
        "status": "pending",
        "external": true,
        "failure": "string",
        "requested_at": "string",
        "finished_at": "string"
      }
    ],
    "refundable": [
      {
        "payment_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "card",
        "card_brand": "string",
        "card_last4": "string"
      }
    ],
    "flags": [
      {
        "kind": "refund",
        "amount_pence": 0,
        "message": "string"
      }
    ],
    "sync": {
      "id": 0,
      "status": "pending",
      "provider": "string",
      "error": "string",
      "done_at": "string"
    },
    "created_at": "string",
    "sent_at": "string",
    "deposit": true,
    "balance": true
  }
}

Response 400 · Error

The request is not valid.

Fields as in Invoiced and received by month

Response 401 · Error

No tenant key, or no valid session.

Fields as in Invoiced and received by month

Response 403 · Error

The session may not do this.

Fields as in Invoiced and received by month

Response 404 · Error

Not found, or not yours.

Fields as in Invoiced and received by month

Response 409 · Error

It clashes with what is stored.

Fields as in Invoiced and received by month

Response 500 · Error

Something failed on our side.

Fields as in Invoiced and received by month

POST/v1/admin/invoices/{id}/refunds

Refund an online payment against a credit note

Needs the invoices.write permission. Against a sent credit note, of an online payment of the invoice it credits, above 0 and at most the payment's amount in the credit note's refundable. The refund is pending until the payment provider confirms it, then queued for the accounting package and emailed to the customer. A refusal by the provider is a 409 in its words. Published as invoice.refunds.

Parameters

idstring, in the path, required
The credit note.

Request body · object

payment_idinteger (int64), required
amount_penceinteger (int64), required

Example request

{
  "payment_id": 0,
  "amount_pence": 0
}

Response 200 · object

The credit note.

invoiceInvoice, required
An invoice or credit note. owed_pence is gross less credited and paid; a refund that succeeds takes its amount off paid_pence of the invoice it was paid on. overdue is worked out when read.
- idinteger (int64), required
- kindstring, required
  One of: invoice credit_note
- numberstring
  Absent on a draft.
- statusstring, required
  One of: draft sent part_paid paid
- customer_idinteger (int64) or null, required
- customer_namestring, required
  The customer's name now; empty once the customer is removed.
- job_idinteger (int64) or null, required
- quote_idinteger (int64) or null, required
- credits_invoice_idinteger (int64) or null, required
- bill_toobject
  The customer as the document was sent to them.
  - namestring, required
  - emailstring, required
  - addressstring, required
  - vat_numberstring
- issued_onstring (date)
- due_onstring (date)
- currencystring, required
  One of: GBP
- linesarray of InvoiceLine, required
  - idinteger (int64), required
  - descriptionstring, required
  - quantitystring, required
  - unit_penceinteger (int64), required
  - vat_ratestring, required
    One of: standard reduced zero exempt none
  - net_penceinteger (int64), required
- totalsobject, required
  - by_ratearray of object, required
    - ratestring, required
    - net_penceinteger (int64), required
    - vat_penceinteger (int64), required
  - net_penceinteger (int64), required
  - vat_penceinteger (int64), required
  - gross_penceinteger (int64), required
- paid_penceinteger (int64), required
- credited_penceinteger (int64), required
- refunded_penceinteger (int64), required
  On a credit note, what was refunded against it, or is being.
- owed_penceinteger (int64), required
- overdueboolean, required
- notesstring, required
- paymentsarray of InvoicePayment, required
  - idinteger (int64), required
  - invoice_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    One of: bank_transfer card cash cheque other paypal
  - referencestring, required
  - recorded_atstring, required
  - onlineboolean, required
    Paid online through a payment provider (method card, reference naming the provider's payment).
  - card_brandstring
  - card_last4string
  - refunded_penceinteger (int64), required
    What was given back of it online, or is being.
- refundsarray of InvoiceRefund, required
  Refunds of an invoice's payments, or against a credit note.
  - idinteger (int64), required
  - invoice_idinteger (int64), required
    The invoice the payment was recorded on.
  - payment_idinteger (int64), required
  - credit_note_idinteger (int64) or null, required
  - amount_penceinteger (int64), required
  - statusstring, required
    One of: pending succeeded failed
  - externalboolean, required
  - failurestring
  - requested_atstring, required
  - finished_atstring
- refundablearray of InvoiceRefundable, required
  On a sent credit note, the online payments it may still refund.
  - payment_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    card for a Stripe payment, paypal for a PayPal one.
    One of: card paypal
  - card_brandstring
  - card_last4string
- flagsarray of InvoiceFlag, required
  On an invoice, refunds made in the payment provider's dashboard that no credit note matches, and open disputes.
  - kindstring, required
    One of: refund dispute
  - amount_penceinteger (int64), required
  - messagestring, required
- syncInvoiceSync or null
  - idinteger (int64), required
  - statusstring, required
    One of: pending done failed
  - providerstring, required
  - errorstring
  - done_atstring
- created_atstring, required
- sent_atstring
- depositboolean
  A quote's deposit invoice.
- balanceboolean
  A quote's balance invoice, raised by the balance run before the move.

Example response 200

{
  "invoice": {
    "id": 0,
    "kind": "invoice",
    "number": "string",
    "status": "draft",
    "customer_id": 0,
    "customer_name": "string",
    "job_id": 0,
    "quote_id": 0,
    "credits_invoice_id": 0,
    "bill_to": {
      "name": "string",
      "email": "string",
      "address": "string",
      "vat_number": "string"
    },
    "issued_on": "date",
    "due_on": "date",
    "currency": "GBP",
    "lines": [
      {
        "id": 0,
        "description": "string",
        "quantity": "string",
        "unit_pence": 0,
        "vat_rate": "standard",
        "net_pence": 0
      }
    ],
    "totals": {
      "by_rate": [
        {
          "rate": "string",
          "net_pence": 0,
          "vat_pence": 0
        }
      ],
      "net_pence": 0,
      "vat_pence": 0,
      "gross_pence": 0
    },
    "paid_pence": 0,
    "credited_pence": 0,
    "refunded_pence": 0,
    "owed_pence": 0,
    "overdue": true,
    "notes": "string",
    "payments": [
      {
        "id": 0,
        "invoice_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "bank_transfer",
        "reference": "string",
        "recorded_at": "string",
        "online": true,
        "card_brand": "string",
        "card_last4": "string",
        "refunded_pence": 0
      }
    ],
    "refunds": [
      {
        "id": 0,
        "invoice_id": 0,
        "payment_id": 0,
        "credit_note_id": 0,
        "amount_pence": 0,
        "status": "pending",
        "external": true,
        "failure": "string",
        "requested_at": "string",
        "finished_at": "string"
      }
    ],
    "refundable": [
      {
        "payment_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "card",
        "card_brand": "string",
        "card_last4": "string"
      }
    ],
    "flags": [
      {
        "kind": "refund",
        "amount_pence": 0,
        "message": "string"
      }
    ],
    "sync": {
      "id": 0,
      "status": "pending",
      "provider": "string",
      "error": "string",
      "done_at": "string"
    },
    "created_at": "string",
    "sent_at": "string",
    "deposit": true,
    "balance": true
  }
}

Response 400 · Error

The request is not valid.

Fields as in Invoiced and received by month

Response 401 · Error

No tenant key, or no valid session.

Fields as in Invoiced and received by month

Response 403 · Error

The session may not do this.

Fields as in Invoiced and received by month

Response 404 · Error

Not found, or not yours.

Fields as in Invoiced and received by month

Response 409 · Error

It clashes with what is stored.

Fields as in Invoiced and received by month

Response 500 · Error

Something failed on our side.

Fields as in Invoiced and received by month

DELETE/v1/admin/invoice-payments/{id}

Remove a payment

Needs the invoices.write permission. For a payment recorded by mistake; who removed it and when are kept. A payment with refunds is a 409.

Parameters

idstring, in the path, required

Response 200 · object

The invoice.

invoiceInvoice, required
An invoice or credit note. owed_pence is gross less credited and paid; a refund that succeeds takes its amount off paid_pence of the invoice it was paid on. overdue is worked out when read.
- idinteger (int64), required
- kindstring, required
  One of: invoice credit_note
- numberstring
  Absent on a draft.
- statusstring, required
  One of: draft sent part_paid paid
- customer_idinteger (int64) or null, required
- customer_namestring, required
  The customer's name now; empty once the customer is removed.
- job_idinteger (int64) or null, required
- quote_idinteger (int64) or null, required
- credits_invoice_idinteger (int64) or null, required
- bill_toobject
  The customer as the document was sent to them.
  - namestring, required
  - emailstring, required
  - addressstring, required
  - vat_numberstring
- issued_onstring (date)
- due_onstring (date)
- currencystring, required
  One of: GBP
- linesarray of InvoiceLine, required
  - idinteger (int64), required
  - descriptionstring, required
  - quantitystring, required
  - unit_penceinteger (int64), required
  - vat_ratestring, required
    One of: standard reduced zero exempt none
  - net_penceinteger (int64), required
- totalsobject, required
  - by_ratearray of object, required
    - ratestring, required
    - net_penceinteger (int64), required
    - vat_penceinteger (int64), required
  - net_penceinteger (int64), required
  - vat_penceinteger (int64), required
  - gross_penceinteger (int64), required
- paid_penceinteger (int64), required
- credited_penceinteger (int64), required
- refunded_penceinteger (int64), required
  On a credit note, what was refunded against it, or is being.
- owed_penceinteger (int64), required
- overdueboolean, required
- notesstring, required
- paymentsarray of InvoicePayment, required
  - idinteger (int64), required
  - invoice_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    One of: bank_transfer card cash cheque other paypal
  - referencestring, required
  - recorded_atstring, required
  - onlineboolean, required
    Paid online through a payment provider (method card, reference naming the provider's payment).
  - card_brandstring
  - card_last4string
  - refunded_penceinteger (int64), required
    What was given back of it online, or is being.
- refundsarray of InvoiceRefund, required
  Refunds of an invoice's payments, or against a credit note.
  - idinteger (int64), required
  - invoice_idinteger (int64), required
    The invoice the payment was recorded on.
  - payment_idinteger (int64), required
  - credit_note_idinteger (int64) or null, required
  - amount_penceinteger (int64), required
  - statusstring, required
    One of: pending succeeded failed
  - externalboolean, required
  - failurestring
  - requested_atstring, required
  - finished_atstring
- refundablearray of InvoiceRefundable, required
  On a sent credit note, the online payments it may still refund.
  - payment_idinteger (int64), required
  - amount_penceinteger (int64), required
  - paid_onstring (date), required
  - methodstring, required
    card for a Stripe payment, paypal for a PayPal one.
    One of: card paypal
  - card_brandstring
  - card_last4string
- flagsarray of InvoiceFlag, required
  On an invoice, refunds made in the payment provider's dashboard that no credit note matches, and open disputes.
  - kindstring, required
    One of: refund dispute
  - amount_penceinteger (int64), required
  - messagestring, required
- syncInvoiceSync or null
  - idinteger (int64), required
  - statusstring, required
    One of: pending done failed
  - providerstring, required
  - errorstring
  - done_atstring
- created_atstring, required
- sent_atstring
- depositboolean
  A quote's deposit invoice.
- balanceboolean
  A quote's balance invoice, raised by the balance run before the move.

Example response 200

{
  "invoice": {
    "id": 0,
    "kind": "invoice",
    "number": "string",
    "status": "draft",
    "customer_id": 0,
    "customer_name": "string",
    "job_id": 0,
    "quote_id": 0,
    "credits_invoice_id": 0,
    "bill_to": {
      "name": "string",
      "email": "string",
      "address": "string",
      "vat_number": "string"
    },
    "issued_on": "date",
    "due_on": "date",
    "currency": "GBP",
    "lines": [
      {
        "id": 0,
        "description": "string",
        "quantity": "string",
        "unit_pence": 0,
        "vat_rate": "standard",
        "net_pence": 0
      }
    ],
    "totals": {
      "by_rate": [
        {
          "rate": "string",
          "net_pence": 0,
          "vat_pence": 0
        }
      ],
      "net_pence": 0,
      "vat_pence": 0,
      "gross_pence": 0
    },
    "paid_pence": 0,
    "credited_pence": 0,
    "refunded_pence": 0,
    "owed_pence": 0,
    "overdue": true,
    "notes": "string",
    "payments": [
      {
        "id": 0,
        "invoice_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "bank_transfer",
        "reference": "string",
        "recorded_at": "string",
        "online": true,
        "card_brand": "string",
        "card_last4": "string",
        "refunded_pence": 0
      }
    ],
    "refunds": [
      {
        "id": 0,
        "invoice_id": 0,
        "payment_id": 0,
        "credit_note_id": 0,
        "amount_pence": 0,
        "status": "pending",
        "external": true,
        "failure": "string",
        "requested_at": "string",
        "finished_at": "string"
      }
    ],
    "refundable": [
      {
        "payment_id": 0,
        "amount_pence": 0,
        "paid_on": "date",
        "method": "card",
        "card_brand": "string",
        "card_last4": "string"
      }
    ],
    "flags": [
      {
        "kind": "refund",
        "amount_pence": 0,
        "message": "string"
      }
    ],
    "sync": {
      "id": 0,
      "status": "pending",
      "provider": "string",
      "error": "string",
      "done_at": "string"
    },
    "created_at": "string",
    "sent_at": "string",
    "deposit": true,
    "balance": true
  }
}

Response 400 · Error

The request is not valid.

Fields as in Invoiced and received by month

Response 401 · Error

No tenant key, or no valid session.

Fields as in Invoiced and received by month

Response 403 · Error

The session may not do this.

Fields as in Invoiced and received by month

Response 404 · Error

Not found, or not yours.

Fields as in Invoiced and received by month

Response 409 · Error

It clashes with what is stored.

Fields as in Invoiced and received by month

Response 500 · Error

Something failed on our side.

Fields as in Invoiced and received by month